All tutorials

Troubleshooting

Cordon 0.7.011 sections · 4 diagramsView this tutorial on GitHub

When a scan fails, stops early, or passes where you expected a finding, Cordon has almost always said why: in its exit code, in the scan coverage notes under the findings, or in the hint printed under an error. This tutorial starts from what you see and works back to the cause. Each fix is stated as Cordon states it, so the words here match the words on your screen.

Every run ends in one of five exit codes, and they never change meaning (foundation/errors.py). The code says which part of this tutorial you need.

Troubleshooting, figure 1
   ┌──────────────┐
   │ cordon-scan  │
   └──────┬───────┘
          │ exit code
          ▼
   ┌──────────────┐     ┌────────────────────────────────────────────────┐
   │ 0  clean     │────►│ nothing met the gate. Expected a finding?      │
   └──────────────┘     │ see "A scan passed that should not have"       │
   ┌──────────────┐     └────────────────────────────────────────────────┘
   │ 1  findings  │────►┌────────────────────────────────────────────────┐
   └──────────────┘     │ read them with -v; see "Findings you disagree  │
   ┌──────────────┐     │ with"                                          │
   │ 2  scanner   │     └────────────────────────────────────────────────┘
   │    error     │────►┌────────────────────────────────────────────────┐
   └──────────────┘     │ Cordon failed: see "Errors before any result"  │
   ┌──────────────┐     └────────────────────────────────────────────────┘
   │ 3  config    │────►┌────────────────────────────────────────────────┐
   │    error     │     │ a flag, file or policy is wrong: the hint      │
   └──────────────┘     │ under the error names it                       │
   ┌──────────────┐     └────────────────────────────────────────────────┘
   │ 4  incomplete│────►┌────────────────────────────────────────────────┐
   └──────────────┘     │ part of the target was not read: see "The scan │
                        │ is incomplete"                                 │
                        └────────────────────────────────────────────────┘
CodeMeaningFirst thing to run
0Nothing met the failure policycordon-scanner scan . --severity info to see what sat below it
1A finding met the failure policycordon-scanner scan . -v for the evidence and the fix
2Cordon itself failedrerun with --format json; report the error with the file named
3A configuration problemread the hint: line; cordon-scanner config validate
4The scan did not read everything, and --fail-on-incomplete was setread the "scan coverage" notes

An incomplete scan is not a pass. A gate that read half a repository and said "clean" is the failure this tool exists to prevent, so the CI templates set --fail-on-incomplete and fail on 4 as well as on 1. Without the flag, as on a laptop, an incomplete scan exits by its findings, and the coverage notes still say what was not read. Turning it off in CI is the Action's fail-on-incomplete: "false", written where reviewers can see it, for a repository known to exceed a limit.

Under the findings, a scan prints scan coverage notes: each one is something it could not do, and each carries its own fix. The ones met most often:

NoteWhat happenedFix
OPERATIONAL.INTEL.STALEThe threat intel is older than its limit (24 hours when Cordon can refresh it), so recent malware and advisories may not matchLet the scan reach OSV; or run cordon-scanner advisories sync, cordon-scanner intel update, or cordon-scanner bundle install
OPERATIONAL.SCAN.TIMEOUTThe total time budget ran outRaise --timeout, or unpack an archive and scan it as a directory
OPERATIONAL.FILE.TIMEOUTNo longer raised by a scan: every detector now runs on every file, as on every member of a package, so whether a file was cut no longer depends on the machine's load. Kept here for reports from earlier versionsNothing to do; total_timeout bounds the scan as a whole (OPERATIONAL.SCAN.TIMEOUT)
OPERATIONAL.SCAN.MEMORY_LIMITRetained content reached its budget; later files were not examinedRaise limits.max_memory_bytes, exclude generated or vendored directories, or scan in parts
OPERATIONAL.SCAN.FINDING_LIMITThe finding cap was reachedRaise limits.max_findings; this many findings usually share one cause worth fixing first
OPERATIONAL.WALK.TOO_DEEPA tree went deeper than max_path_depthRaise scan.limits.max_path_depth, or scan the deep tree directly
OPERATIONAL.WALK.ERRORPaths could not be traversedCheck permissions and path lengths
OPERATIONAL.FILE.UNREADABLEA file could not be readCheck permissions, or exclude the path deliberately
OPERATIONAL.GRAPH.LIMITThe dependency graph passed max_dependenciesRaise limits.max_dependencies, or scan projects separately
OPERATIONAL.ARCHIVE.REJECTEDAn archive was refused by a limitTreat it as unexamined; raise the limit deliberately if the input is legitimate
OPERATIONAL.ARCHIVE.NOT_EXPANDEDArchives were left closedScan without --no-expand
OPERATIONAL.LOCKFILE.UNSUPPORTEDA lockfile format Cordon does not read (Bun's binary bun.lockb)Commit the text form beside it (bun install --save-text-lockfile)
OPERATIONAL.LOCKFILE.UNPARSEDA lockfile could not be parsedRegenerate it with the package manager
OPERATIONAL.MANIFEST.UNPARSEDA manifest has a syntax error, or a construct refused on purpose (a DTD in a .csproj)Fix the syntax so the manifest can be checked
OPERATIONAL.PARSER.FAILEDA parser crashed on a fileA bug: report it with the file
OPERATIONAL.DETECTOR.FAILEDA detector crashed on a fileA bug: report it with the file
OPERATIONAL.FILE.LFS_POINTERFiles are Git LFS pointers, not their contentClone with LFS content (actions/checkout needs lfs: true)
OPERATIONAL.VCS.UNREADABLE.001History was unavailable: usually a shallow cloneScan where the repository is complete (fetch-depth: 0)
OPERATIONAL.SECRET_HISTORY.INCOMPLETE.001The history pass stopped at a boundRaise the bound, or scan history in its own job
OPERATIONAL.IMAGE.UNREADABLEAn image's layers could not be readExport again with docker save or skopeo copy ... oci-archive:
OPERATIONAL.IMAGE.PARTIALPart of an image's OS inventory is missingExport without zstd compression, or check the distribution is supported
OPERATIONAL.IMAGE.NOT_MATCHEDOS packages were inventoried but not matched against distribution advisoriescordon-scanner advisories sync --os debian (or ubuntu, alpine, wolfi, chainguard, rocky, almalinux, redhat, suse, opensuse) once, or scan with --online
OPERATIONAL.SBOM.INVALIDA file shaped like an SBOM could not be readRegenerate it with its tool, or validate it against the schema

Some notes are information, not failures: OPERATIONAL.FILE.BINARY (binaries are not read as source), OPERATIONAL.FILE.SYMLINK (links are recorded, never followed), OPERATIONAL.ADVISORY.DATABASE_SCOPE (the bundled database holds malicious and high/critical records; advisories sync takes the full set) and OPERATIONAL.IMAGE.CONTENTS (what an image scan covered). Every rule, these included, is in 28 · Every rule.

Three causes cover nearly every case.

Troubleshooting, figure 2
   ┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
   │ below the gate       │   │ not in the intel yet │   │ not read at all      │
   │                      │   │                      │   │                      │
   │ --severity info      │   │ intel: line at the   │   │ excluded, pruned,    │
   │ shows what the gate  │   │ end of the output:   │   │ gitignored with      │
   │ left out             │   │ source and age       │   │ --tracked, or in a   │
   │                      │   │                      │   │ coverage note        │
   └──────────────────────┘   └──────────────────────┘   └──────────────────────┘

Below the gate. --fail-on high passes a medium finding; --severity hides what is below it from the report as well. Rerun with --severity info and the same --fail-on to see the whole picture.

Not in the intel yet. The last lines of every scan say where the advisories came from and how old they are:

intel: osv, 0h old

osv means the scan asked OSV for what changed since the bundled database was built, and matched against that. package or bundle with a large age means it could not: an advisory published after the database was built will not match. Cordon refreshes on its own unless it is told not to (--offline, CORDON_OFFLINE=1, or CORDON_NO_ADVISORY_REFRESH=1) or cannot reach osv-vulnerabilities.storage.googleapis.com. A runner behind an egress allowlist needs that host added; the requests name no package, so they reveal nothing about the code.

Not read at all. A directory in the built-in prune list (node_modules, .venv, build output) is skipped and named in a POLICY.COVERAGE.PRUNED note; --include brings it back. --tracked scans only what git tracks, so a generated or gitignored file is out of scope. An --exclude that matched more than expected is reported as POLICY.COVERAGE.BROAD_EXCLUSION.

-v prints, for each finding, the evidence, how its score was derived and the fix. If the finding is wrong for your code, say so where it can be reviewed:

Troubleshooting, figure 3
   ┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
   │ one finding          │   │ everything that      │   │ a whole class        │
   │                      │   │ exists today         │   │                      │
   │ cordon-scanner       │   │ cordon-scanner       │   │ cordon.yaml:         │
   │ suppress add         │   │ baseline create      │   │ disable the rule,    │
   │ (reason, expiry)     │   │ (adopt gradually)    │   │ under the org policy │
   └──────────────────────┘   └──────────────────────┘   └──────────────────────┘

A suppression carries a reason and an expiry; suppress prune removes the expired ones. A baseline records what exists now so only new findings fail; baseline compare shows what changed since. A rule disabled in cordon.yaml is refused if the organisation policy forbids it (tutorial 14). Test fixtures are the common case: findings under a path that holds test material are reported below their usual severity already, and a fixture directory full of deliberate payloads belongs in --exclude.

A finding Cordon should not have made at all is a bug worth reporting, with the file reduced to the smallest input that still produces it.

Exit codes 2 and 3 print a message and, usually, a hint: line saying what to do. The ones met most often:

MessageCauseFix
unknown key(s) in cordon.yaml: ...A misspelt or outdated keycordon-scanner config validate; the schema is in tutorial 14
organisation policy not found: ...--policy or CORDON_POLICY names a missing filePoint it at the file, or at the published URL with its digest
policy ... does not match its pinned digestThe policy changed after it was pinnedFetch the published copy (config fetch-policy), or update the pin
unknown detector(s): ...A --detector name that does not existThe message lists the available ones
unknown output format ...A --format that does not existtext, json, sarif, junit, markdown, github, codeclimate, vex
target does not exist: ...The path is wrong for the working directoryIn CI, check the job's working directory
CORDON_OFFLINE is set, so the feed will not be fetchedintel update with the network turned offUnset it for the update, or install a bundle

cordon-scanner config explain prints the configuration in effect once the command line, cordon.yaml and the organisation policy are combined, with its hash: two runs with the same hash were configured the same.

The runner is not your laptop. The differences that matter:

DifferenceSymptomFix
Shallow checkoutOPERATIONAL.VCS.UNREADABLE.001; --history reads nothingfetch-depth: 0 (GitHub), GIT_DEPTH: 0 (GitLab), clone: depth: full (Bitbucket)
LFS content not fetchedOPERATIONAL.FILE.LFS_POINTERlfs: true on checkout
No network, or an allowlistOPERATIONAL.INTEL.STALE; intel: packageAllow osv-vulnerabilities.storage.googleapis.com, or ship a signed bundle (tutorial 11)
A slower machineOPERATIONAL.SCAN.TIMEOUTRaise --timeout; scan in parts
Windows line endingsFewer dependencies than locally0.6.0 reads CRLF the same as LF; on an older version set core.autocrlf false for the checkout
A different cacheResults differ between runs--no-cache to compare: a cached result is reused only under the same configuration
A different scanner versionNew or missing findingsPin CORDON_VERSION; read the CHANGELOG for the version that changed

Every template installs the scanner from PyPI with --require-hashes, against the hash pin committed at the release tag (action/requirements.txt at v<version>). An install that fails on a hash is the template refusing an artefact it cannot verify, which is what it is for.

permissions:  contents: read  security-events: write    # SARIF upload; without it the upload step fails  id-token: write           # only for Cordon Cloud uploadsteps:  - uses: actions/checkout@<sha>    with:      fetch-depth: 0        # only if you scan --history  - uses: Threx-code/cordon/[email protected]
SymptomCauseFix
CORDON_VERSION is X, but this ref pins a different versionCORDON_VERSION disagrees with the Action's refPoint uses: at the tag for that version, or unset CORDON_VERSION
This ref of the Action carries no hash pin, so the download cannot be verified.A ref (a branch, an old SHA) without action/requirements.txtPoint uses: at a release tag; allow-unverified-install: true only for a ref that predates signed releases
Resource not accessible by integration on SARIF uploadsecurity-events: write missingAdd it to the job's permissions
Fails on a pull request from a forkA fork's token cannot write security events or mint an ID tokenSkip the upload on forks: if: github.event.pull_request.head.repo.fork == false
Fails, nothing in the findingsExit 4 under fail-on-incomplete: true (the default)Read the coverage notes in the step log

ci/gitlab/cordon.gitlab-ci.yml reads CORDON_VERSION, CORDON_SEVERITY, CORDON_FAIL_ON, CORDON_OFFLINE and CORDON_UPLOAD. CORDON_VERSION is not a version means it is not X.Y.Z. The pin is fetched from raw.githubusercontent.com; a runner that cannot reach it fails before installing, and needs that host allowed or the pin vendored. Cloud upload uses the job's id_tokens (CORDON_ID_TOKEN).

The pipe takes SEVERITY, FAIL_ON and UPLOAD as variables:, and reads BITBUCKET_CLONE_DIR. Upload needs oidc: true on the step, which provides BITBUCKET_STEP_OIDC_TOKEN. History needs clone: depth: full.

Each reads CORDON_VERSION, CORDON_SEVERITY, CORDON_FAIL_ON and CORDON_UPLOAD. Upload uses the platform's identity token (CORDON_ID_TOKEN); Azure, CircleCI and Buildkite also need CORDON_ORGANIZATION, and Azure a service connection in CORDON_SERVICE_CONNECTION. The templates are ci/azure/cordon-task.yml, ci/circleci/orb.yml, ci/buildkite/pipeline.yml and ci/jenkins/vars/cordonScan.groovy; the gate they implement is tutorial 10's.

ci/generic/scan.sh runs the published image (CORDON_IMAGE) with Docker, honouring CORDON_FAIL_ON and CORDON_OFFLINE. If Docker is not available on the runner, install the scanner with the hash pin instead, as the templates do.

Troubleshooting, figure 4
   ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────────┐
   │ git commit / │───►│ hook runs    │───►│ blocked: findings, or        │
   │ git push     │    │ cordon scan  │    │ a guard that was changed     │
   └──────────────┘    └──────────────┘    └──────────────────────────────┘
SymptomCauseFix
tampered: <file> does not match the manifestA guarded file (a workflow that runs the scanner, the policy, a baseline) changedIf intended, cordon-scanner guard update, and have the manifest diff reviewed with it
The hook does not run at allNot installed, or core.hooksPath points elsewherecordon-scanner guard install; git config core.hooksPath
The hook is slowIt scans more than the changeHooks scan staged files (--staged); a full scan belongs in CI

git commit --no-verify skips a hook. It is sometimes right, and always visible in review: the CI gate runs the same scan regardless.

SymptomFix
OPERATIONAL.IMAGE.UNREADABLEExport with docker save -o image.tar <image>, then scan the tar
OS packages listed, none matched (OPERATIONAL.IMAGE.NOT_MATCHED)cordon-scanner advisories sync --os <family> once, then scan offline
A language package you expected is missingImages list what is installed: a lockfile in the image counts only where its packages are installed
The scan runs out of memory on a very large imageScan it on a machine with more memory, or raise limits.max_memory_bytes deliberately
CauseFix
A large monorepo--jobs for more workers; the cache makes the second run incremental
Vendored or generated trees--exclude them, deliberately and visibly
Large archivesThey are opened and scanned; --no-expand trades coverage for speed, and says so
Every scan on a fresh runnerCache the directory in CORDON_CACHE_DIR between runs
Network checks--online asks registries; leave it for scheduled jobs if pull requests must be fast

A report that can be acted on has the version, the command, and the JSON result:

cordon-scanner --versioncordon-scanner scan . -v --format json:result.json --audit-log audit.jsonl

result.json holds every finding, coverage note and the intel status; the audit log records what the scan did. Both name paths in the repository and nothing else. For a crash (exit 2), the smallest file that reproduces it is worth more than any description.

Next: 30 · Cordon for AI agents: the MCP server.