cordon
GitHubSign in
All tutorials

The advisory database

Cordon 0.6.03 sections · 2 diagramsView this tutorial on GitHub

The malicious/vulnerable-package lists (tutorial 03) ship with the tool and are used offline at scan time. This is how you keep them fresh.

   SCAN TIME                         REFRESH TIME (separate, deliberate)   ─────────                         ──────────────────────────────────   read the bundled data, offline    cordon-scanner advisories sync   no network, reproducible          cordon-scanner advisories sync --bundle <url>
The advisory database, figure 1
   A) BUILD FROM OSV                         B) INSTALL A SIGNED BUNDLE
   ─────────────────                         ──────────────────────────
   advisories sync                           advisories sync --bundle <url>
        │                                          │
        ▼                                          ▼
   pull OSV's bulk export                     download a pre-built bundle
        │                                          │
        ▼                                     ┌────┴───────────────────────────┐
   rank + normalise per ecosystem             │ verify Ed25519 signature       │
        │                                     │ against the PINNED release key │
        ▼                                     │  BEFORE unpacking anything     │
   write local advisory data                 └────┬────────────────────────────┘
                                                  ▼
                                              extract → digest-check every file

Building from source reads OSV's per-ecosystem exports from osv-vulnerabilities.storage.googleapis.com and, for RubyGems, the Ruby Advisory Database (rubysec) from codeload.github.com -- the source bundler-audit and Trivy use, which carries Ruby advisories OSV does not. An advisory both sources carry is kept once. Nothing about the code you scan is sent to either.

The advisory database, figure 2
   A vulnerability database is a high-value target: water it down and every scan
   that trusts it goes quiet. So the bundle is signed, and the signature is checked
   BEFORE a single byte is unpacked — with a verify-only Ed25519 that is vendored
   into the tool, so refreshing needs no third-party crypto dependency.

        download ─▶ VERIFY SIG ─▶ safe-extract ─▶ per-file digest ─▶ install
                       │
                    fail here  ─▶ nothing is unpacked, old data untouched
   cordon-scanner scan .  --advisories path/to/advisories/     # air-gapped sites
   --only npm pypi        sync just these ecosystems

Next: 10 · CI & git hooks.