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?
Free Video Available
Before we get started: In addition to this article, I created a sample web application for which I documented SOUP in a IEC 62304 - compliant way. You can watch me while I fill out spreadsheets, it’s pretty exciting. The video is free, have a look!
Did this screencast help you understand SOUP? I’m currently making a few more. Sign up for early access if you’re interested!
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!
Let’s look at the requirements first:
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):
|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).
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.
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.