gstack/docs/cso-scanners.md

Running CSO scanners

gstack-cso scan RUN SCANNER [REQUEST.json] collects candidate evidence through the trusted helper when a matching qualified scanner catalog profile exists. Recognized IDs are gitleaks, osv, semgrep, zizmor, trivy, and schemathesis. Without a qualified profile, the command records a specific prerequisite; static assessment and importing existing CodeQL or other SARIF with gstack-cso import-sarif RUN REPORT.sarif remain available. The returned immutable artifact can be read later with gstack-cso scanner-outcome RUN ARTIFACT_ID; callers never need to open private state files directly.

The source-controlled catalog in scanner-images/catalog.json is empty until every release gate produces real evidence. Without a reviewed profile, the command records a specific not_assessed prerequisite. Installing a scanner on the host does not enable execution. Each profile binds a Linux platform, immutable image digest, fixed entrypoint, absolute scanner executable, version-probe hash, required adapter capabilities, helper ABI, and the exact isolation-policy hash. The helper validates that catalog when it starts and has no executable fallback. Setup preloads the current platform's qualified scanner digests through the trusted installation helper using anonymous public-registry access. A failed preload or a bounded per-image/setup deadline is a nonfatal prerequisite and never causes an audit to pull. The default is 30 seconds per declared image; GSTACK_CSO_IMAGE_PULL_TIMEOUT_SECONDS=120 selects a longer allowance (accepted range: 5–300 seconds) while the complete preload remains capped at one hour. Doctor is read-only and reports each scanner unavailable unless its exact catalog digest is already present locally.

All scanner processes use Docker containment with a watchdog, shared admission limits, read-only source, bounded output, and an isolated network namespace. Static scanners have no network access, including when the audit omits --offline. Semgrep rules and OSV/Trivy databases must be baked into the reviewed image. Their content hashes, scope, and freshness accompany the result. Database refresh is a separately reviewed image acquisition/release operation; scans never download missing assets or switch to unrestricted registry networking.

REQUEST.json can select an exact scanner profile. Schemathesis additionally requires comprehensive mode and an api object; gstack-cso schema describes its fields. The API harness supplies a bounded OpenAPI 3.0/3.1 JSON document, 1–20 unique path operation IDs, a qualified application runtime, an absolute start command, a numeric loopback port, a legitimate HTTP control, and the source files defining the security boundary. Internal schema references are allowed. Server overrides, remote references/examples, hooks, callbacks, and webhooks are rejected. The application must boot and pass the control before the scanner starts. Application and scanner share only the admitted loopback namespace. An API failure is a candidate, never a reproduced vulnerability or certified repair. Sources needing dependency preparation report that prerequisite until a prepared offline closure is available to the API runner.

Each execution probes the scanner version before scanning and validates the retained source both before and after collection. Unknown output, failed diagnostics, a timeout, changed source, or incomplete cleanup cannot become an empty clean result. The helper retains valid partial candidates when the adapter can distinguish them from failed coverage. Output that cannot be redacted is withheld.

Scanner and SARIF collection hold the run's mutation lock and reject finished or interrupted reports. Every outcome is written exclusively under a unique scanner-outcomes/ name before its coverage record enters the report. The returned artifact path is relative to the run directory. Model submissions cannot replace scanner:* coverage or certify the imported candidates. The free scanner tests use injected runners and catalogs to verify dispatch and failure handling; they do not claim real image qualification. The opt-in Docker qualification test runs the production adapter, image, watchdog, and isolation policy. It emits the version-output hash only after a representative scan completes without a coverage gap.

The release inputs in build-inputs.json remain pending until reviewers provide all six scanners on both native platforms. The inputs require immutable base and SBOM-generator image digests, exact source commits and versions, signer workflow identities and digests, and reviewed canonical SLSA/SPDX statement-set digests. The workflow cryptographically re-verifies each image with those repository, source, signer, and predicate constraints before use. Semgrep additionally requires a reviewed local rules bundle. OSV and Trivy require complete offline database bundles with recorded content hashes, freshness, and ecosystem coverage. Publishing those asset-bearing base images and reviewing their evidence are external prerequisites; the release workflow does not invent or silently replace them.

cso-scanner-images.yml lets a dispatched branch run read-only input and contract validation. Image publishing, native amd64/arm64 qualification, attestation verification, embedded-asset hash checks, containment, real-adapter execution, and catalog-proposal generation run only from protected main through the cso-scanner-release environment. Before enabling qualification or promotion, configure the repository's cso-scanner-release GitHub environment with required maintainer reviewers and deployments restricted to protected main. GitHub otherwise creates a referenced missing environment without protection rules. Promotion requires an explicit dispatch from main and approval through that configured environment. It opens a pull request containing only the proposed source catalog, so code review remains the final authorization step. previousRevision records the prior compatible catalog for rollback and must still equal the current main catalog when promotion runs.

Scanner flags follow the primary documentation linked in scanners.ts. Offline qualification must exercise the exact chosen version: OSV's maintainers documented a cache-location regression in 2.5.0, which demonstrates why a version string alone is insufficient. OSV issue #2983. Trivy uses an explicit memory scan cache alongside read-only baked databases. Trivy filesystem reference.