Feature: Filtering results by analyzing project imports

[kelbyludwig]

Pre-submission checks

• I am not reporting a new vulnerability or requesting a new vulnerability identifier. These must be reported or managed via upstream dependency sources or services, not this repository.
• I agree to follow the PSF Code of Conduct.
• I have looked through the open issues for a duplicate request.

What's the problem this feature will solve?

Would pip-audit be open to adding a vulnerability relevance step based on the ecosystem_specific structure defined in the PyPa advisory database schema? This would allow, users to filter pip-audit results that are most relevant to their project. (For similar prior art, see govulncheck's package-level filtering described here). I'm considering implementing it but it would add project-wide static analysis to pip-audit which may be a non-trivial shift in scope for the project.

Describe the solution you'd like

The UX I'd imagine is just a flag that, when enabled, will filter out vulnerability results if an advisory has data about relevant modules and the audited project's source includes a matching import statement. At a high-level:

$ pip-audit -r requirements.txt --check-imports 
...
Found 2 vulnerabilities for packages you require, but your code doesn't appear to call
these vulnerabilities. 

# This is cribbing some wording from `govulncheck` which does similar analysis

For the first version of an implementation, I'd propose:

• Update the VulnerabilityResult structure to store ecosystem_specific.imports if present.
  • I do not believe this field is used in the advisory database but I've proposed adding a few cases in a PR here: Add a few instances of ecosystem_specific data advisory-database#263.
  • I believe this would only be relevant for the OSV --vulnerability-service at least initially. I'm not sure if PyPI exposes the ecosystem_imports data in its API.
• Add a flag like --check-imports that enables a project-wide analysis step.
• Add an analysis step to pip-audit that:
  • os.walk's the provided project_path for Python source files.
  • Uses ast to walk each project file and normalize imports into a string. I have a proof of concept for this step here.
  • Use the normalized paths to filter VulnerabilityResults on ecosystem_specific.imports[].modules. I'd likely hook this into the audit implementation around here.
• For this first version I'm not using the ecosystem_specific imports[].attribute field. That analysis is more involved and a potentially good second (or third, or fourth) step :)

I'm open to feedback on the design particulars (e.g. Flag names, project filtering, UX questions) but as a first step I wasn't quite sure if directionally this idea was even considered in-scope for pip-audit.

Additional context

No response