feat(core): the pip-audit parser, and SP-4's fixture at last

SP-4's exit criterion was "command line + JSON fixture pinned". The command line was
pinned in prose in Phase 0; the fixture never was, so every claim about pip-audit's
output in PRD, SECURITY and CODE-HEALTH-SPEC has been unchecked since. It is captured
now, from the pinned 2.10.1 against the spike's own `urllib3==2.0.0` environment, and
`crates/pipdock-core/src/audit.rs` is written against it rather than against the
documents.

Four things running it settled, none of which reading could:

- **No severity exists, under either service.** The vuln object is exactly `id`,
  `fix_versions`, `aliases`, `description`; pip-audit's service model has no severity
  field at all. PRD P1-1's "severity-sorted" and SECURITY §6's "(CVE/GHSA id,
  severity, fixed-in)" were both written against a field that has never existed. The
  next commit corrects them; `sort_advisories` orders by package, then by whether
  anything *fixes* it, then by id — the one distinction that changes what a user can
  do. Deriving a severity from the id's year or the prose would be a number PipDock
  invented, shown beside real ones.
- **The ids are `PYSEC-*`, so the default service is PyPI**, and the CVE is an alias.
  Leaving that default is what keeps `legal/PRIVACY-POLICY.md` §3's "exactly one
  destination" true — and it costs nothing: the same environment under
  `--vulnerability-service osv` returns the *same eight advisories*, set difference
  empty in both directions.
- **Ids repeat**, so dedup is load-bearing rather than tidy. Ten rows for eight
  advisories under PyPI; sixteen for the same eight under OSV. Keyed on `(pkg, id)`,
  because one advisory can legitimately apply to two installed packages.
- **stderr carries a `pip-compile` advisory on every run**, so stdout is parsed first
  and failure classified only if that fails — SP-1's rule for uv, which writes its
  plan to stderr for the same reason.

`advisory_url` builds the OSV link from a **validated** id rather than taking a URL
out of the tool's JSON. That is the difference between this and `PdHealthReport`'s
`finding.url`, which `capabilities/external-links.json` calls out as the only URL in
the application derived from a third party's output: a whitelist of ASCII alphanumerics
and `-` cannot produce a `/`, `?`, `#`, `:` or `%`, so nothing that passes can be
anything but a path segment under one host. Ten hostile ids are asserted to get no
link at all.

No wire registration yet — the types derive `JsonSchema` but stay out of
`SCHEMA_TYPES` until a command returns one, exactly as P2 held `ToolsManifest` back
until P3 had a use for it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-18 10:55:11 +07:00
1 parent 8d9a28dc03
commit 5023e39485
6 files changed
+360

No files matched your search

+3
View File
@@ -33,3 +33,6 @@ crates/pipdock-core/tests/fixtures/**/*.json text eol=crlf
# get — the rule above would have rewritten a captured document's line endings and quietly made it # get — the rule above would have rewritten a captured document's line endings and quietly made it
# something no tool ever emitted. Later rules win, which is what lets this sit as an exception. # something no tool ever emitted. Later rules win, which is what lets this sit as an exception.
crates/pipdock-core/tests/fixtures/health/** -text crates/pipdock-core/tests/fixtures/health/** -text
# pip-audit captures are a tool's own output, like health/ above.
crates/pipdock-core/tests/fixtures/audit/** -text
+315
View File
@@ -0,0 +1,315 @@
//! pip-audit over an installed environment — PRD P1-1, SECURITY §6.
//!
//! Runs out of **its own venv** ([`crate::health::AUDIT_TOOLS`], [`crate::health::audit_dir`]) and
//! in freeze-file mode, which SP-4 established is the only mode there is: `--path <site-packages>`
//! is rejected outright when combined with `--no-deps`, so the environment reaches the tool as a
//! `pip freeze` document rather than as a directory.
//!
//! Four things this module exists to get right, every one measured against the pinned 2.10.1
//! rather than read out of a document (`tests/fixtures/audit/`):
//!
//! 1. **The ids are `PYSEC-*`, because the default vulnerability service is PyPI.** Left as the
//! default deliberately: PipDock querying `api.osv.dev` itself would add a second network
//! destination and falsify `legal/PRIVACY-POLICY.md` §3's "exactly one destination". Findings
//! still *link* to OSV, which is a visit the user's browser makes after a click — the case §3
//! already carves out.
//! 2. **There is no severity, under either service.** The vuln object carries exactly `id`,
//! `fix_versions`, `aliases` and `description`. PRD P1-1's "severity-sorted" and SECURITY §6's
//! "(CVE/GHSA id, severity, fixed-in)" were written against a field that has never existed, so
//! [`sort_advisories`] sorts by what is real instead.
//! 3. **Ids repeat.** The captured run returns ten rows for **eight** advisories; the same
//! environment under `--vulnerability-service osv` returns sixteen rows and the *same* eight.
//! A count taken before [`dedupe`] is wrong under either service.
//! 4. **stderr is not a failure signal.** pip-audit writes a `pip-compile`/hashes advisory on
//! every single run. Parse stdout first and classify only if that fails — the rule SP-1 left
//! behind for uv, which writes its plan to stderr for the same reason.
use std::collections::BTreeSet;
use crate::errors::{Code, PdError, Result};
use crate::model::{PkgName, Version};
/// Where a finding links. The id is appended after validation — never interpolated raw.
const OSV_BASE: &str = "https://osv.dev/vulnerability/";
/// One advisory against one installed distribution.
#[derive(
Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema,
)]
#[serde(rename_all = "camelCase")]
pub struct Advisory {
/// The installed distribution the advisory is against.
pub pkg: PkgName,
/// The version installed, not the version that fixes it.
pub version: Version,
/// pip-audit's primary id — `PYSEC-*` under the default service.
pub id: String,
/// Other ids for the same advisory, which is where the `CVE-*` and `GHSA-*` live.
///
/// PRD P1-1 says "known CVEs"; a CVE is never the primary id here, so a screen that wants to
/// show one reads this.
#[serde(default)]
pub aliases: Vec<String>,
/// Versions that fix it. **Empty is meaningful** — an advisory with nowhere to upgrade to —
/// and [`sort_advisories`] puts those last rather than hiding them.
#[serde(default)]
pub fix_versions: Vec<String>,
/// The advisory prose, verbatim. Never translated (I18N §2) and never trimmed here.
pub description: String,
/// The OSV entry, when the id is shaped like one.
///
/// **Built from a validated id rather than taken from the tool**, which is the whole
/// difference between this and `PdHealthReport`'s `finding.url`.
/// `capabilities/external-links.json` records that ruff's URL is the only one in the
/// application derived from a third party's output; this one is derived from a string PipDock
/// has checked, so widening the allowlist to `osv.dev` does not widen what can reach it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub url: Option<String>,
}
/// The OSV entry for an advisory id, or `None` if the id is not shaped like one.
///
/// The check is a whitelist, not an escape: ASCII letters, digits and `-`, 4 to 64 characters,
/// leading letter. Nothing that passes can carry a `/`, `?`, `#`, `:` or `%`, so the result cannot
/// be anything but a path segment under [`OSV_BASE`] — which is what lets the opener allowlist
/// stay scoped to one host. SECURITY §2's obligation follows the *input*, and this input is a
/// third-party tool's JSON.
#[must_use]
pub fn advisory_url(id: &str) -> Option<String> {
let ok = (4..=64).contains(&id.len())
&& id.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
&& id.starts_with(|c: char| c.is_ascii_alphabetic());
ok.then(|| format!("{OSV_BASE}{id}"))
}
/// pip-audit's `-f json` document, only the parts PipDock reads.
mod raw {
#[derive(serde::Deserialize)]
pub struct Doc {
#[serde(default)]
pub dependencies: Vec<Dep>,
}
#[derive(serde::Deserialize)]
pub struct Dep {
pub name: String,
#[serde(default)]
pub version: String,
#[serde(default)]
pub vulns: Vec<Vuln>,
}
#[derive(serde::Deserialize)]
pub struct Vuln {
pub id: String,
#[serde(default)]
pub fix_versions: Vec<String>,
#[serde(default)]
pub aliases: Vec<String>,
#[serde(default)]
pub description: String,
}
}
/// How many distributions the run covered, and what it found.
///
/// The count is separate from `advisories.len()` on purpose: "audited 145 packages, found nothing"
/// and "audited nothing" are different answers, and a screen that cannot tell them apart repeats
/// P4's *no issues found before anything had run*.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Audited {
/// Distributions present in the freeze document.
pub packages: usize,
/// Deduplicated and sorted.
pub advisories: Vec<Advisory>,
}
/// Parse a pip-audit `-f json` document.
///
/// # Errors
/// `PD-HLT-002` when stdout is not the document `--format json` promises. That is the only failure
/// mode here: a non-zero exit is **not** one, because findings exit 1.
pub fn parse(stdout: &str) -> Result<Audited> {
let doc: raw::Doc = serde_json::from_str(stdout).map_err(|e| {
PdError::new(
Code::HltToolFailed,
format!("pip-audit did not emit the JSON document --format json promises: {e}"),
)
})?;
let mut advisories = Vec::new();
for dep in &doc.dependencies {
// A name pip-audit echoed back out of a freeze document PipDock wrote. Validated anyway:
// it is the join key against the installed table, and an unparseable one would be a row
// matching nothing rather than a row that is merely wrong.
let Ok(pkg) = PkgName::parse(&dep.name) else {
continue;
};
for vuln in &dep.vulns {
advisories.push(Advisory {
pkg: pkg.clone(),
version: Version(dep.version.clone()),
url: advisory_url(&vuln.id),
id: vuln.id.clone(),
aliases: vuln.aliases.clone(),
fix_versions: vuln.fix_versions.clone(),
description: vuln.description.clone(),
});
}
}
Ok(Audited {
packages: doc.dependencies.len(),
advisories: sort_advisories(dedupe(advisories)),
})
}
/// Collapse advisories repeated for one package.
///
/// pip-audit emits the same id more than once — twice each for two of the eight in the captured
/// run, and eight times each under the OSV service. The key is `(pkg, id)` rather than `id` alone,
/// because one advisory legitimately applies to two different installed packages.
#[must_use]
pub fn dedupe(advisories: Vec<Advisory>) -> Vec<Advisory> {
let mut seen = BTreeSet::new();
advisories
.into_iter()
.filter(|a| seen.insert((a.pkg.clone(), a.id.clone())))
.collect()
}
/// Order: package, then whether anything fixes it, then id.
///
/// **Not severity.** PRD P1-1 asked for severity-sorted and pip-audit has no such field, so this
/// sorts by the one distinction that changes what a user can *do*: an advisory with a
/// `fix_versions` entry is one the normal Update flow can act on, and an advisory without one is
/// not. Inventing a severity — from the id's year, from the description's wording — would be a
/// number PipDock made up, shown beside real ones.
#[must_use]
pub fn sort_advisories(mut advisories: Vec<Advisory>) -> Vec<Advisory> {
advisories.sort_by(|a, b| {
a.pkg
.cmp(&b.pkg)
.then(a.fix_versions.is_empty().cmp(&b.fix_versions.is_empty()))
.then(a.id.cmp(&b.id))
});
advisories
}
#[cfg(test)]
mod tests {
use super::*;
/// The pinned 2.10.1 over `urllib3==2.0.0` — see the directory's README for provenance.
const CAPTURE: &str = include_str!("../tests/fixtures/audit/urllib3-2.0.0.json");
#[test]
fn the_capture_parses_and_collapses_to_eight() {
let got = parse(CAPTURE).expect("the committed capture must parse");
assert_eq!(got.packages, 1);
// Ten rows in the document, eight advisories. Asserted as a number rather than "fewer than
// before", because this count is what a Security tab puts on screen.
assert_eq!(got.advisories.len(), 8, "ten rows collapse to eight");
let ids: BTreeSet<&str> = got.advisories.iter().map(|a| a.id.as_str()).collect();
assert_eq!(ids.len(), 8, "no id survives twice");
assert!(ids.contains("PYSEC-2023-192"));
}
#[test]
fn the_cve_is_an_alias_and_never_the_id() {
let got = parse(CAPTURE).expect("parses");
let a = got
.advisories
.iter()
.find(|a| a.id == "PYSEC-2023-192")
.expect("the capture carries it");
assert!(a.aliases.contains(&"CVE-2023-43804".to_owned()));
assert!(a.aliases.iter().any(|x| x.starts_with("GHSA-")));
assert!(
!a.id.starts_with("CVE-"),
"PRD says CVEs; the id is not one"
);
assert_eq!(a.fix_versions, ["1.26.17", "2.0.6"]);
assert_eq!(a.version.0, "2.0.0", "the installed version, not the fix");
}
#[test]
fn every_advisory_links_to_its_osv_entry() {
let got = parse(CAPTURE).expect("parses");
for a in &got.advisories {
assert_eq!(
a.url,
Some(format!("{OSV_BASE}{}", a.id)),
"{} lost its link",
a.id
);
}
}
#[test]
fn an_id_that_could_escape_the_path_segment_gets_no_link() {
// Why the URL is built rather than taken: these are what a compromised — or merely
// surprising — tool output could otherwise carry into `opener:allow-open-url`.
for bad in [
"../../evil",
"PYSEC-2023-192/../../x",
"PYSEC 2023 192",
"javascript:alert(1)",
"https://evil.test/x",
"PYSEC-2023-192?x=1",
"PYSEC-2023-192#f",
"%2e%2e",
"1PYSEC",
"ab",
] {
assert_eq!(advisory_url(bad), None, "{bad:?} must not become a URL");
}
assert!(advisory_url("PYSEC-2023-192").is_some());
assert!(advisory_url("GHSA-v845-jxx5-vc9f").is_some());
assert!(advisory_url("CVE-2023-43804").is_some());
}
#[test]
fn fixable_advisories_sort_ahead_of_unfixable_ones() {
// The order PRD P1-1 gets instead of severity, so it is asserted rather than assumed.
let mk = |pkg: &str, id: &str, fixes: &[&str]| Advisory {
pkg: PkgName::parse(pkg).expect("valid"),
version: Version("1.0".to_owned()),
id: id.to_owned(),
aliases: vec![],
fix_versions: fixes.iter().map(|s| (*s).to_owned()).collect(),
description: String::new(),
url: None,
};
let got = sort_advisories(vec![
mk("zlib-wrapper", "PYSEC-1", &["1.1"]),
mk("aiohttp", "PYSEC-3", &[]),
mk("aiohttp", "PYSEC-2", &["2.0"]),
]);
let order: Vec<&str> = got.iter().map(|a| a.id.as_str()).collect();
assert_eq!(order, ["PYSEC-2", "PYSEC-3", "PYSEC-1"]);
}
#[test]
fn stdout_that_is_not_the_promised_document_is_a_tool_failure() {
// Not a panic, and not a silent empty report: pip-audit printing anything else means the
// run did not do what was asked, and PD-HLT-002 is the code that says so.
let err = parse("Found 10 known vulnerabilities in 1 package").expect_err("not JSON");
assert_eq!(err.code, Code::HltToolFailed);
}
#[test]
fn a_clean_environment_is_zero_advisories_over_a_real_package_count() {
let doc =
r#"{"dependencies":[{"name":"certifi","version":"2024.2.2","vulns":[]}],"fixes":[]}"#;
let got = parse(doc).expect("parses");
assert_eq!((got.packages, got.advisories.len()), (1, 0));
}
}
+1
View File
@@ -23,6 +23,7 @@
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))] #![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
pub mod audit;
pub mod bindings; pub mod bindings;
pub mod cache; pub mod cache;
pub mod compat; pub mod compat;
+37
View File
@@ -0,0 +1,37 @@
# pip-audit capture
SP-4's exit criterion asked for "command line + JSON fixture pinned". The command line was pinned
in prose in `spikes/README.md` in Phase 0; **the fixture never was**, and P1-1 needed it.
Captured 2026-08-18 with the ledger's pinned **pip-audit 2.10.1**, against the spike's own target
environment (`spikes/out/target-env`, a Python 3.12 venv holding `urllib3==2.0.0`), by the exact
invocation SECURITY §6 and SP-4 settled on:
```
pip-audit -r spikes/out/freeze.txt --no-deps -f json
```
Exit code **1** — findings, not failure.
Not redacted, and it does not need to be: unlike the pip/uv captures there is no path, no
duration, no address and no environment marker in it. The only `://` in the file is inside the
advisory prose. `spikes/capture.py` does not produce this, for the same reason it does not produce
`health/sample` — reconstructing the seeded environment is the expensive part, not the run.
## What it pins, and why each matters
* **`PYSEC-*` ids.** pip-audit's *default* vulnerability service is PyPI, not OSV. That is what
lets PipDock keep `legal/PRIVACY-POLICY.md` §3's "exactly one destination" true.
* **`aliases` carries the `CVE-*` and `GHSA-*`.** PRD P1-1 says "known CVEs"; the CVE is an alias,
never the primary id.
* **Duplicate ids.** `PYSEC-2023-192` and `PYSEC-2023-212` each appear **twice**, so the ten rows
here are **eight** advisories. The same run under `--vulnerability-service osv` returns sixteen
rows and the *same eight* — the set difference is empty in both directions, so the service
choice costs no coverage and dedup is load-bearing either way.
* **No severity field, under either service.** The keys are exactly `id`, `fix_versions`,
`aliases` and `description`; pip-audit's own service model has no severity at all. PRD P1-1's
"severity-sorted" and SECURITY §6's "(CVE/GHSA id, severity, fixed-in)" were both written
against a field that does not exist, and P1-1 corrects them rather than inventing one.
`urllib3-2.0.0.stderr.txt` is the companion: pip-audit writes a `pip-compile`/hashes advisory to
stderr on **every** run, which must never be read as failure.
@@ -0,0 +1 @@
{"dependencies": [{"name": "urllib3", "version": "2.0.0", "vulns": [{"id": "PYSEC-2023-192", "fix_versions": ["1.26.17", "2.0.6"], "aliases": ["CVE-2023-43804", "GHSA-v845-jxx5-vc9f"], "description": "urllib3 doesn't treat the `Cookie` HTTP header special or provide any helpers for managing cookies over HTTP, that is the responsibility of the user. However, it is possible for a user to specify a `Cookie` header and unknowingly leak information via HTTP redirects to a different origin if that user doesn't disable redirects explicitly. Users **must** handle redirects themselves instead of relying on urllib3's automatic redirects to achieve safe processing of the `Cookie` header, thus we decided to strip the header by default in order to further protect users who aren't using the correct approach. ## Affected usages We believe the number of usages affected by this advisory is low. It requires all of the following to be true to be exploited: * Using an affected version of urllib3 (patched in v1.26.17 and v2.0.6) * Using the `Cookie` header on requests, which is mostly typical for impersonating a browser. * Not disabling HTTP redirects * Either not using HTTPS or for the origin server to redirect to a malicious origin. ## Remediation * Upgrading to at least urllib3 v1.26.17 or v2.0.6 * Disabling HTTP redirects using `redirects=False` when sending requests. * Not using the `Cookie` header."}, {"id": "PYSEC-2023-192", "fix_versions": ["1.26.17", "2.0.6"], "aliases": ["CVE-2023-43804", "GHSA-v845-jxx5-vc9f"], "description": "urllib3 is a user-friendly HTTP client library for Python. urllib3 doesn't treat the `Cookie` HTTP header special or provide any helpers for managing cookies over HTTP, that is the responsibility of the user. However, it is possible for a user to specify a `Cookie` header and unknowingly leak information via HTTP redirects to a different origin if that user doesn't disable redirects explicitly. This issue has been patched in urllib3 version 1.26.17 or 2.0.5."}, {"id": "PYSEC-2023-212", "fix_versions": ["1.26.18", "2.0.7"], "aliases": ["CVE-2023-45803", "GHSA-g4mx-q9vg-27p4"], "description": "urllib3 previously wouldn't remove the HTTP request body when an HTTP redirect response using status 303 \"See Other\" after the request had its method changed from one that could accept a request body (like `POST`) to `GET` as is required by HTTP RFCs. Although the behavior of removing the request body is not specified in the section for redirects, it can be inferred by piecing together information from different sections and we have observed the behavior in other major HTTP client implementations like curl and web browsers. From [RFC 9110 Section 9.3.1](https://www.rfc-editor.org/rfc/rfc9110.html#name-get): > A client SHOULD NOT generate content in a GET request unless it is made directly to an origin server that has previously indicated, in or out of band, that such a request has a purpose and will be adequately supported. ## Affected usages Because the vulnerability requires a previously trusted service to become compromised in order to have an impact on confidentiality we believe the exploitability of this vulnerability is low. Additionally, many users aren't putting sensitive data in HTTP request bodies, if this is the case then this vulnerability isn't exploitable. Both of the following conditions must be true to be affected by this vulnerability: * If you're using urllib3 and submitting sensitive information in the HTTP request body (such as form data or JSON) * The origin service is compromised and starts redirecting using 303 to a malicious peer or the redirected-to service becomes compromised. ## Remediation You can remediate this vulnerability with any of the following steps: * Upgrade to a patched version of urllib3 (v1.26.18 or v2.0.7) * Disable redirects for services that you aren't expecting to respond with redirects with `redirects=False`. * Disable automatic redirects with `redirects=False` and handle 303 redirects manually by stripping the HTTP request body."}, {"id": "PYSEC-2023-212", "fix_versions": ["1.26.18", "2.0.7"], "aliases": ["CVE-2023-45803", "GHSA-g4mx-q9vg-27p4"], "description": "urllib3 is a user-friendly HTTP client library for Python. urllib3 previously wouldn't remove the HTTP request body when an HTTP redirect response using status 301, 302, or 303 after the request had its method changed from one that could accept a request body (like `POST`) to `GET` as is required by HTTP RFCs. Although this behavior is not specified in the section for redirects, it can be inferred by piecing together information from different sections and we have observed the behavior in other major HTTP client implementations like curl and web browsers. Because the vulnerability requires a previously trusted service to become compromised in order to have an impact on confidentiality we believe the exploitability of this vulnerability is low. Additionally, many users aren't putting seLine truncated
@@ -0,0 +1,3 @@
WARNING:pip_audit._cli:--no-deps is supported, but users are encouraged to fully hash their pinned dependencies
WARNING:pip_audit._cli:Consider using a tool like `pip-compile`: https://pip-tools.readthedocs.io/en/latest/#using-hashes
Found 10 known vulnerabilities in 1 package