Supply-chain and resource safety

cad-agent depends on, vendors and links to many projects we do not control. A compromised package, a vendored file that quietly changed, or a catalogue link whose repository was deleted and re-registered by someone else can hurt everyone who follows us. tools/resource_audit.py checks all of it the same way every time; this skill says when to run it, how to read it and what to do with what it finds. The supply-chain page shows where it runs, and the latest report what it found. It complements SECURITY.md (vendored-code rules) and the red-flag scan in tools/security_scan.py, which reads the code itself; this report reads what surrounds it.

flowchart TD
    A["about to add a dependency,<br/>vendored file, link or tool"] --> R["rows --online<br/>(report --online for advice)"]
    R --> F{"a finding?"}
    F -->|"none"| P["paste the rows under<br/>Supply chain in the PR"]
    F -->|"yes"| D["fix it, or accept it with<br/>its fp and a reason"]
    D --> R
    P --> G["CI's supply-chain job:<br/>rows present, nothing new at medium"]

When to run it

python3 tools/resource_audit.py report                       # offline: what CI enforces (seconds, no network)
python3 tools/resource_audit.py rows --base origin/dev --online   # rows for what your branch adds
python3 tools/resource_audit.py report --online \
    --json research/security-report.json --md research/security-report.md \
    --svg docs/img/supply-chain/findings.svg                 # refresh the committed report, from a clean checkout

--online makes a few hundred light requests and downloads the npm tarballs the web kit receipts name (about 20 MB; about a minute). Run it on demand, not in a loop. --installed also checks the installed versions of our direct Python dependencies in your own environment (not every package in it), and --catalog dist/catalog.json reads the links of a built site too.

Repository settings are the owner's. Secret scanning and Dependabot alerts can only be read with admin rights: the owner runs report --online --repo Valpatel/cad-agent with their own login. Agents and the weekly workflow leave --repo out; never change a setting, only report it.

How to read it

The latest committed report, drawn by the tool from its JSON (render). Each bar is one area; the counts are open findings at low or above.

Every finding has a severity, a subject (the item: pypi:pillow, npm:marked, vendor:text-to-cad, webkit:mermaid, url:https://…, doc:<file>, repo:<owner/repo>), the evidence, the suggested action and a fingerprint fp (the check, the subject and a stable key), so the weekly issue only changes when the findings do. The JSON (research/security-report.json) holds the full inventory: every dependency with its range, newest release, licence and advisory counts, and the transitive Python packages deps.dev resolves; every vendored project with its pin, licence, drift against upstream and Scorecard; every web kit folder with its packages, the libraries its files bundle and whether its files match the npm package its receipt names; every link with where it is used.

What blocks

A merge into dev (CI's supply-chain job runs gate, offline):

• any high or critical finding anywhere in the checkout;
• a medium or worse finding on something the PR adds;
• an added dependency, vendored file or catalogue entry without its row in the PR description. A row is a table row whose first cell is the item's id in backticks, as rows prints it; a mention in prose does not count. Paste the table under Supply chain in the PR template; "None" when nothing is added.

A release PR into main, and the push to main after it, get the whole-checkout check alone. Their items went through this gate in their own PRs into dev (it warns rather than blocks, so a red result there was the reviewer's call); judged against main, "what the change adds" would be everything since the last release.

flowchart TD
    D["into dev"] -->|"whole checkout,<br/>what it adds,<br/>its rows"| G["gate --into"]
    M["into main"] -->|"whole checkout<br/>only"| G
    G -->|"high or critical anywhere,<br/>medium on what is added,<br/>a missing row"| X["the job fails"]

The job is not a required check (making it one is the owner's call, on the supply-chain page). It runs the PR's own copy of tools/resource_audit.py, research/security-accepted.yaml and ci.yml, so a PR can change them and pass: it is an honesty check, not a security boundary. Reviewers read every change to those three files, and above all an acceptance added in the same PR as the finding it hides.

The online findings do not gate CI (the network must never make CI flaky). The reviewer reads the rows you pasted, which should come from rows --online.

An adoption (moving an entry to trial, adopted or used, vendoring it, or copying its code):

• no high or critical advisory without a fix and a plan;
• the repository is not archived, deleted or moved without an explanation;
• a licence we can use: MIT, BSD or Apache-2.0 to incorporate; GPL and AGPL as external programs only; no licence or non-commercial means ideas only (the policy in upstreams/registry.yaml);
• a Scorecard below 4, or none, means you read its code and maintenance yourself and say so in the PR;
• for each new dependency, a "can we drop it?" note in the PR: what it does that the standard library or an existing dependency cannot, and which extra it lives in. Fewer dependencies is the goal.

What to do with a finding

Fix it in a PR, or record why it is fine (below). The action for each kind of finding is in the report itself and here:

Use visible statuses on the site (unmaintained, moved, under review, gone): the catalogue shows the status of an upstreams/registry.yaml entry or a research/landscape.json library as its badge (other entries: say it in their notes). A flagged entry stays listed with its status until a person decides to drop it.

Accepting a finding

Some findings are understood and fine (an install script that runs only on macOS for an optional test dependency). Record them in research/security-accepted.yaml, reviewed in a PR like any change:

flowchart TD
    F["a finding you understand<br/>and judge fine"] --> C{"critical?"}
    C -->|"yes"| N["never accepted:<br/>fix it, tell the owner"]
    C -->|"no"| A["an entry in security-accepted.yaml:<br/>check, subject, fp, reason, date"]
    A --> R["reviewed in a PR; it stays in the<br/>report, marked accepted, not counted"]

- check: npm-install-script
  subject: npm:fsevents
  fp: 0123456789abcdef          # the finding's fingerprint, from the report: this finding only
  reason: optional macOS-only dependency of Playwright; CI runs on Linux, where it is not installed
  accepted: 2026-11-01

Without fp, an acceptance covers every finding of that check on that subject, so the tool refuses an advisory acceptance without one: accepting one moderate advisory must not hide the next one on the same package. An accepted finding stays in the report, marked accepted, and no longer counts for the exit code. The tool never accepts a critical finding (a malicious package, a critical advisory), and you never accept a hash mismatch or drift you cannot explain.

Limits (say them when you report)

Where it comes from

The report calls existing services instead of keeping its own advisory logic: OSV.dev (the database behind pip-audit and osv-scanner, including the OpenSSF malicious-packages feed), npm audit, PyPI and the npm registry, Open Source Insights (deps.dev) for dependency graphs, the GitHub API, and the OpenSSF Scorecard API. Link-check ideas come from lychee: fall back from HEAD to GET, and treat 403 and 429 as not verified rather than broken. The weekly workflow (.github/workflows/supply-chain.yml) runs it online and keeps one issue current: a read-only job makes the report, and a second job, which holds the only write permission (issues), turns it into the issue.