Cordon

A language-agnostic software supply-chain security scanner. It reads source, manifests, lockfiles, build scripts, CI config, Dockerfiles and IaC — and reports malicious packages, install-time behaviour, leaked credentials and dependency risk.

Seventeen package ecosystems, from npm and PyPI to Conan, Hex, CRAN and Bazel — the file-by-file list, and which checks each one gets, is in docs/07-ECOSYSTEMS.md.

   ┌─────────────────────────────────────────────────────────────────────────┐
   │  Cordon READS.  It never executes the code it scans, and never touches  │
   │  the network unless you pass --online.  Safe on hostile packages,       │
   │  safe in an air-gap, and its results are reproducible.                  │
   └─────────────────────────────────────────────────────────────────────────┘

pipx install cordon-scanner
cordon-scanner scan .

   scan .
     │  walk        identify            run every            sort, dedupe,
     │  the tree    the target          applicable check     score
     ▼     │            │                    │                   │
   repo ───┴──▶ languages/manifests ──▶ detectors ──▶ findings ──▶ report
   dir/file/archive     lockfiles/CI                              text·json·sarif·…

New here? The tutorials are short, diagram-first walkthroughs — one per use case.

What it looks like

A package whose postinstall posts the environment to a webhook and pipes a download into a shell, and a workflow that sends a publish token to a remote host:

Real output, rendered from a captured run. It is an SVG, not a GIF — text, so it can be read in a diff before it is trusted. A tool that flags committed binaries should not ship one to advertise itself. Regenerate with python scripts/render_demo.py.

  Map of this page
  ├─ Install ................ pipx · pip · Action · container
  ├─ Run it ................. what to scan, what to emit, what appears
  ├─ Configure it ........... the file, the four layers, limits
  ├─ Environments ........... local · pre-commit · CI · monorepo · air-gap · enterprise
  ├─ Tuning ................. the noise ladder, least-blunt first
  ├─ Adopting ............... baseline the debt, gate on the new
  ├─ Accuracy ............... measured, reproducible
  ├─ What fails a build ..... compromise fails; posture is reported
  ├─ Exit codes ............. 0 clean · 1 findings · 2 broke · 3 config · 4 incomplete
  └─ Why this exists ........ the attack, and the three invariants

Install

Python 3.11 / 3.12 / 3.13 on Linux, macOS and Windows.

   OPTIONAL EXTRAS — opt-in, and each degrades to a STATED limit, never a crash
   ┌────────────────────────────────────────────────────────────────────────┐
   │  base           zero third-party runtime deps                          │
   │  [ast-js]       tree-sitter → JS/TS semantic rules   (tutorial 13)     │
   │  [attest]       sigstore    → provenance verification (tutorial 05)    │
   └────────────────────────────────────────────────────────────────────────┘

   PIN BY DIGEST, NOT BY TAG
   Action  → @<commit sha>     a tag is mutable; pinning to something the author
   Image   → @sha256:<digest>  can move defeats the point of running a scanner.

The Action and image are built from the distroless, non-root Dockerfile here, signed keylessly with cosign, and carry SLSA build provenance — the same controls the wheel and sdist get.

cordon --version
cordon-scanner rules list      # what will run

Run it

cordon-scanner scan .                                  # a directory
cordon-scanner scan ./package.tgz                      # an archive, read in memory
cordon-scanner scan . --severity high --fail-on high   # gate a pipeline

What gets scanned

   --exclude 'vendor/**'      skip paths (repeatable)
   --include 'src/**'         restrict to paths
   --tracked                  only files git tracks
   --git-diff origin/main     only what changed vs a ref
   --staged                   the git INDEX, not the working tree

   WHY --staged for a pre-commit hook
   ┌──────────────────────────────────────────────────────────────────┐
   │ a hook reading the WORKING TREE is defeated by: stage a poisoned │
   │ file → restore the clean one. The poisoned blob commits; the     │
   │ clean one is scanned. Reading the index closes that.             │
   └──────────────────────────────────────────────────────────────────┘

   Narrowing applies to FILE analysis only. Dependency & manifest checks always
   run against the whole tree — a malicious transitive dep appears in no diff.

What it emits

   -f text                 humans at a terminal (default)
   -f json                 machine-readable
   -f sarif:cordon.sarif   code-scanning platforms
   -f junit:results.xml    CI test reporters
   -f markdown             PR comments, job summaries
   -f github               inline annotations on a diff

   -f is repeatable; FMT:PATH writes to a file, bare FMT goes to stdout:
   cordon-scanner scan . -f github -f sarif:cordon.sarif -f json:result.json

What appears in the report

   --evidence masked      (default) matched values are masked
   --evidence hash_only   no snippets — for a widely-readable report (PR, upload)
   Secret findings are hash-only regardless.  --reachability annotates CVE noise
   (tutorial 04).  --online adds live registry + provenance checks (tutorial 05).

Other commands

   inventory .            what is this repo, and the evidence
   rules list|show|test   what can fire · one rule · run every rule's samples
   config explain         effective settings + which layer supplied each
   guard install|verify   fail-closed git hooks (tutorial 10)
   baseline create|compare adopt incrementally (tutorial 14)
   advisories sync        refresh the intel (tutorial 09)
   bundle create|install  air-gapped install (tutorial 11)
   sbom generate          CycloneDX / SPDX from the resolved graph

Accuracy, measured

Every number is produced by a script in this repository, against code nobody here wrote.

Per ecosystem and per attack technique, with the method for each and what the numbers are not: docs/08-ACCURACY.md.

What fails a build, and how to change it

By default a finding fails the build when it says this code is compromised or giving something away — malware, leaked credentials, obfuscation, exfiltration. A posture choice a project made about its own infrastructure is reported and does not fail: a security group open to the internet, privileged: true, a Dockerfile doing curl | sh.

That split, the configuration file, the noise ladder and every exit code: docs/10-CONFIGURATION.md.

Pre-commit, GitHub Actions, GitLab, Jenkins, containers and org-wide policy: docs/09-INTEGRATIONS.md.

Using it as a library

from cordon_scanner import Scanner

scanner = Scanner.for_target("./repository")
result = scanner.scan("./repository")

for finding in result.findings:
    print(finding.rule_id, finding.severity, finding.location)

Scanner.for_target assembles configuration through the same resolver the CLI uses, so the organisation ceiling applies. Everything returned is immutable and output is deterministic: identical inputs produce identical findings in a stable order.

Documentation

Project

Status

Beta, and the classifier says so. The detection engine, rule packs, seventeen ecosystems, reporters, policy layer, baselines, git-aware scanning and the advisory layer are implemented and tested; docs/03-INTERFACES.md separates the commands that ship from those that are designed. Interfaces may still change before 1.0, the bundled advisory set is the malicious plus high/critical subset of OSV rather than all of it, four of the seventeen ecosystems have no advisory feed to match against at all, and reachability is modelled at its import tier rather than its call-graph tier — none of it hidden: cordon-scanner rules list shows what runs, docs/07-ECOSYSTEMS.md shows which checks each ecosystem gets, and every reduction in coverage is reported as a finding rather than left for a reader to infer.

Licence

Apache-2.0. See LICENSE and NOTICE.