Supply chain and resource safety

cad-agent depends on Python and npm packages, vendors other people's code into vendor/ and the web kit, and sends readers to hundreds of outside projects from its catalogue and pages. tools/resource_audit.py checks all of it the same way every time: known advisories and malicious packages, pins and recorded hashes, vendored files against their upstream, licences, and links that died, moved or now point somewhere else. Each pull request into dev gets the offline checks; a weekly run adds the online ones and keeps one issue current. The latest run is in the supply-chain report, and the cad-supply-chain skill says what to do with each finding.

Real output of tools/resource_audit.py, drawn from the committed report of this repository. A test redraws it from the report's JSON, so the two cannot disagree.

What it checks

Everything fetched is data: advisory text, package metadata, tarballs and pages are parsed, never run or followed as instructions, and a tarball is read in memory, never unpacked to disk. Before building it we compared what exists (the fold at the end of this page); the report calls those services rather than keeping its own advisory logic.

Where it runs

flowchart TD
    D["into dev:<br/>a PR or a push"] -->|"whole checkout,<br/>what it adds,<br/>its rows"| G["CI's supply-chain job<br/>offline, not required"]
    M["into main: a release<br/>PR or the push after it"] -->|"whole checkout<br/>only"| G
    classDef here fill:#fffdf5,stroke:#173d3c,color:#173d3c
    classDef near fill:#eef1e4,stroke:#6f8a80,color:#173d3c
    class G here
    class D,M near

What a change adds is judged where new items enter the project, on PRs and pushes into dev: each added dependency, vendored file or catalogue entry needs its row in the PR description, and none may have a medium or worse finding. A release PR into main carries items that went through that gate in their own PRs. The job warns rather than blocks, so a red result there was the reviewer's call, and items from before the job existed never went through it. Compared with main, "what it adds" would be everything since the last release, which no release PR can describe, so it and the push after it get the whole-checkout check alone: no high or critical finding anywhere.

The weekly run

flowchart TD
    W["weekly schedule,<br/>or a run by hand"] --> O["report job: online checks,<br/>read-only token"]
    O -->|"the report,<br/>as an artifact"| I["issue job: one tracking<br/>issue, kept current"]
    classDef here fill:#fffdf5,stroke:#173d3c,color:#173d3c
    classDef near fill:#eef1e4,stroke:#6f8a80,color:#173d3c
    classDef out fill:#ffe1cc,stroke:#bd3a12,color:#173d3c
    class O here
    class W near
    class I out

The online checks gate nothing. The job that reads third-party answers holds no write permission; the job that may write issues reads only the report. A service that does not answer is reported as "not verified", and the issue keeps its earlier findings open as "not re-checked" rather than counting them as fixed.

Run it

python3 tools/resource_audit.py report                               # the offline checks, as CI runs them
python3 tools/resource_audit.py rows --base origin/dev --online       # the rows to paste under "Supply chain"
python3 tools/resource_audit.py gate --base origin/dev --into dev --pr-body-file body.md   # CI's check, locally
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
python3 tools/resource_audit.py render                                # re-draw the page and figure from its JSON

Run the refresh from a checkout with nothing uncommitted: the report records the revision it read and says so when the tree had changes. Repository settings (secret scanning, Dependabot alerts) need admin rights, so only the owner's run with --repo Valpatel/cad-agent sees them.

Making it required (owner)

The supply-chain job is not a required check: a failure warns and does not block. To make it one, the owner adds the check named supply-chain to the required checks of dev; on main it would only repeat the whole-checkout check. If the repository's Actions event policy lists events per workflow file, .github/workflows/supply-chain.yml needs schedule and workflow_dispatch. Agents do not change these settings (#153).