Check It Out: Free Video Available
While you're gathering your motivation to read yet another article on regulation, let me jump in briefly! We've actually recorded a video on this topic in the meantime. I think this video will help you understand the topic even better because it's to-the-point and super concrete. After watching it (and reading this article), you should be able to write your own documentation. Check it own below and take a look for yourself!
And if you liked this video, take a look at our Wizard which includes step-by-step instructions, templates and videos for even more topics. It's way cheaper and more efficient than paying consultants (like us) to explain it to you. Startups love it and I'm sure you'll like it, too!
But now, let's move on to the actual article.
Question
Our python backend contains lots of dependencies, for example flask and the requests library. According to the IEC 62304, third-party dependencies are “SOUP” and must be documented. We have no idea how to do this. What should we do?
Short Answer
You need to create a list of your dependencies. That list can be a spreadsheet, a markdown file, or pretty much anything else which you can save as document to your Quality Management System.
Update: Check out my SOUP list template which I’ve uploaded for you, it’s 100% free!
Long Answer
Let’s look at the requirements first:
Main Requirements
The requirements differ based on your 62304 software safety class. For each SOUP item, you need to document these things:
Class A, B and C
- Title, manufacturer, unique designator (e.g. artefact name and version from dependency file) (section 8.1.2)
- Management of risks related to SOUP should be planned (section 5.1.7)
Class B and C
- Functional and performance requirements which are necessary for its intended use (section 5.3.3)
- Hardware and software requirements (section 5.3.4)
- Verify that your software architecture supports proper operation of SOUP items (section 5.3.6c)
- Identify potential failure modes (section 7.1.2c)
- Evaluate published anomaly lists (section 7.1.3)
While that may sound like a long laundry list for each dependency, it’s fairly manageable.
How to Document SOUP
Behold, my minimalistic implementation of a SOUP list (you can find a more complete table in my template):
| Name | Version | Requirements | Issue Tracker |
|---|---|---|---|
| Flask | 1.1.2 | Handle HTTP requests | https://github.com/pallets/flask/issues |
| requests | 2.23.0 | Perform HTTP requests and return results | https://github.com/psf/requests/issues |
This covers the identification and requirements aspects. I didn’t add a field for “manufacturer” as they’re
all open-source. Also notice how I summarized the functional, performance, hardware and software requirements
into one field Requirements. This probably works for most libraries as they’ll be running alongside your
software anyway; they’ll have the same hardware requirements as your software (e.g., a server running python
3). For more very critical SOUP you may want to document requirements more detailed.
This table doesn’t cover the “verify that it runs on your software architecture” aspect. I suggest you add that to your Software Development SOP in which someone signs off that the used SOUP runs on the chosen software architecture.
It also doesn’t cover the potential failure modes. Those should be covered in your risk table. You could then link those risk table entries to entries in the SOUP list. I suggest to only cover the mission-critical SOUPs in your risk analysis though, otherwise you’ll never finish analyzing risks. You could come up with a risk classification in a few categories to decide how in-depth a SOUP’s risks have to be analyzed.
Regarding the SOUP list, you could do it in a spreadsheet (ugh) or a markdown file in a git repository. Just remember that you should be able to export it (e.g. as pdf) to hand it in to your auditor (as part of your technical documentation).
Why?
To understand where regulatory requirements come from, it always makes sense to imagine the worst software developer team ever (tm). Like, a bunch of high-school kids writing an overengineered Single-Page Application in JavaScript and React.
As you may know, when you start out writing a Single Page Application and have arrived at the stage
of displaying Hello World, your package.json already includes around 99 dependencies.
When you look through the list, do you still remember why you included each of them? Maybe you will. But how about a week from now? A month? A year? And when you hand off the project to another developer, will he know?
What about bugs and security issues? How will you track them? You’re developing medical software after all, and it may be a serious problem if you suddenly have an unpatched security vulnerability in your web server dependency.
This is where the regulatory requirements for SOUP come in.
Side Quests
You’re not done just yet. Here are the remaining requirements from the 62304 regarding SOUP. The good news is that you can fulfil these through other documents:
You need to mention required SOUP items in your software development plan (section 5.1.1d): This one is pretty easy. Just reference your SOUP list from your software development plan.
You need to include SOUP items in your integration tests (section 5.1.5): Also a no-brainer. Of course SOUP is included when you run your integration tests. Broken SOUP would be caught by those tests, at least for the functions you’re using. Maybe mention this in your software development SOP.
You need a procedure to evaluate and implement upgrades, bug fixes, patches and obsolescence of SOUP items (section 6.1f): Add this procedure to your software development SOP.
Whenever you change SOUP, you need to check whether those changes impact medical device safety and/or existing risk control measures (sections 7.4.1, 7.4.2): Also quite straightforward - just re-run your relevant tests once you’ve updated a SOUP which was part of a certain software requirement.