supply-chain-scan

## When to Use - Changing any of the three supply-chain layers (OSV, GuardDog, retire/trufflehog) or the offline database plumbing. The `supply_chain_common`-must-be-bind-mounted rule is in the [AGENTS.md](../../scanners/supply_chain_scan/AGENTS.md) CRITICAL RULES; this skill is the scanning behaviour. --- ## Critical Rules - **NEVER assume the offline OSV database is populated.** It is filled lazily, per-ecosystem, only on the explicit `--download-offline-databases` step - NOT on every scan and NOT at install time ([scanners/supply_chain_common/osv_db_sync.py](../../scanners/supply_chain_common/osv_db_sync.py)). A scan against an unsynced ecosystem must report it as missing, not crash. - **NEVER `chmod` the OSV DB tighter than world-readable.** The scanner runs hardened and non-root; `osv_db_sync.py` makes the whole tree world-readable/traversable on purpose so the scanner can read it. Restricting it breaks offline scans silently. - **NEVER erase an existing soft-error marker on a failed/invalid analysis.** A package the analyzer never actually inspected is recorded as a `soft_error` ([scanners/supply_chain_common/deep_recovery.py](../../scanners/supply_chain_common/deep_recovery.py)); invalid GuardDog output must be dropped, not allowed to overwrite those markers (regression fixed in commit `c5cd6a16`). - **NEVER run the OSV binary without the `--offline` pairing.** Offline mode uses the `--offline --download-offline-databases` pair; using one without the other either hits the network or reads an empty DB. --- ## Layers | Layer | Runner | Note | | --- | --- | --- | | known vulns | [osv_runner.py](../../scanners/supply_chain_common/osv_runner.py) + [osv_db_sync.py](../../scanners/supply_chain_common/osv_db_sync.py) | offline OSV DB (named volume, lazily synced) | | malicious behaviour | [guarddog_runner.py](../../scanners/supply_chain_common/guarddog_runner.py) | GuardDog heuristics; soft-errors via [deep_recovery.py](../../scanners/supply_chain_common/deep_recovery.py) | | dispatch | [analyzer_dispatch.py](../../scanners/supply_chain_common/analyzer_dispatch.py) | routes a package to the right analyzer | ## Commands ```bash ./redamon.sh supply-chain-sync <ecosystems> # bootstrap the offline OSV DB (separate from scans) ./redamon.sh test unit # supply_chain_* under the root-agent section ``` ## Resources - [docs/readmes/README.SUPPLY_CHAIN.md](../../docs/readmes/README.SUPPLY_CHAIN.md) - the 3-layer architecture and offline DB volume - Related: supply_chain [AGENTS.md](../../scanners/supply_chain_scan/AGENTS.md) CRITICAL RULES (bind-mount `supply_chain_common`)