supply-chain-scan

name	supply-chain-scan
description	Working on RedAmon's supply-chain scanner (offline OSV + GuardDog + retire + trufflehog): the offline OSV database that the scan path does not bootstrap, the world-readable requirement for the hardened scanner, and the soft-error markers that record what was never analysed. Trigger: editing scanners/supply_chain_common/, scanners/supply_chain_analyzer/ or scanners/supply_chain_scan/; touching osv_db_sync.py, osv_runner.py, guarddog_runner.py, deep_recovery.py, or the offline OSV database handling.
license	MIT
metadata	{"author":"redamon","version":"1.0.0","scope":["supply_chain"],"auto_invoke":["Editing the supply-chain scanner or its offline OSV database handling"]}

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 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). 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); 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 + osv_db_sync.py	offline OSV DB (named volume, lazily synced)
malicious behaviour	guarddog_runner.py	GuardDog heuristics; soft-errors via deep_recovery.py
dispatch	analyzer_dispatch.py	routes a package to the right analyzer

Commands

./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 - the 3-layer architecture and offline DB volume
• Related: supply_chain AGENTS.md CRITICAL RULES (bind-mount supply_chain_common)