Skip to content

artifact-security.md

Latest commit

 

History

History
170 lines (139 loc) · 6.75 KB

artifact-security.md

File metadata and controls

170 lines (139 loc) · 6.75 KB
Raw

Artifact Security

Code Polishy owns the reusable container-security mechanism. Targets declare what artifact represents the product; they do not copy Trivy setup, database, OpenVEX, SBOM, report, or hardening scripts.

Execution contract

The policy release pins an official Trivy image by digest and verifies that digest, the expected Trivy version, the minimal scanner Dockerfile hash, and the scanner runtime's OpenVEX hash before use. It copies only the Trivy binary and CA bundle into a non-root scratch image.

The scanner image disables Go's HTTP/2 client. Its database download uses HTTPS over HTTP/1.1; target scanning remains offline. The release-owned scanner assessments document the exact remaining findings and their applicability. Ordinary Ubuntu CI and Linux release builds use the same verification script to exercise the installed scanner against a minimal scratch image with a fresh database before tagging and publication.

Each run:

  1. verifies a reachable Docker server and supported server architecture;
  2. builds and version-checks the minimal scanner without build network access;
  3. refreshes the vulnerability database in a networked container that receives only a private cache mount and no target input or credentials;
  4. validates database schema, freshness, timestamps, and hashes;
  5. self-scans the exact scanner runtime;
  6. captures each declared target into a private bounded archive;
  7. scans offline with a read-only root, non-root user, dropped capabilities, no-new-privileges, resource/time limits, no socket, and no credentials;
  8. verifies that the archive and vulnerability database did not change;
  9. writes normalized JSON/Markdown evidence, a CycloneDX SBOM, and a hash manifest beneath .code-polishy-reports/artifact-security by default; and
  10. removes temporary containers, images, archives, and databases.

HIGH and CRITICAL vulnerabilities, secrets, image-config misconfigurations, and end-of-life operating systems are blocking. Secret matches are never copied into normalized findings or reports.

Scanner self-check findings identify Code Polishy's scanner, its Trivy version, and its pinned source image. They point to .code-polishy.lock.json, because the locked Code Polishy release owns that runtime. Application findings retain their declared artifact scope and remediation. Both remain blocking.

Repair a scanner finding by upgrading to a verified Code Polishy release carrying a patched scanner; rebuilding an application image cannot repair it. The scan does not establish the availability of a fixed Code Polishy/scanner release and reports that explicitly. A component's fixed version in Trivy output alone does not prove that a verified scanner release contains it. The self-check and its release-owned OpenVEX policy remain required.

Built images are saved by immutable Docker identity. Trivy reports must match the configuration digest from that exact saved archive; see Container Archive Identity.

Target modes

Use dockerfile when the shared engine can build the product directly:

{
  "name": "api-image",
  "module": "api-delivery",
  "mode": "dockerfile",
  "dockerfile": "deploy/api.Dockerfile",
  "context": ".",
  "platform": "linux/amd64",
  "openVex": "security/api.openvex.json"
}

Use archive for an existing contained Docker/OCI archive:

{
  "name": "release-image",
  "module": "release",
  "mode": "archive",
  "archive": "dist/release-image.tar"
}

Use command only when artifact construction has product-specific sequencing. Code Polishy runs the checked-in command as an argument array and sets CODE_POLISHY_ARTIFACT_OUTPUT to a new private directory:

{
  "name": "eval-image",
  "module": "eval-runtime",
  "mode": "command",
  "producer": {
    "argv": ["./scripts/build-eval-artifact.sh"],
    "cwd": ".",
    "manifest": "manifest.json",
    "environment": [],
    "timeoutSeconds": 1800
  },
  "openVex": "security/eval.openvex.json"
}

The producer must write a regular bounded archive and this versioned manifest beneath the supplied directory:

{
  "version": 1,
  "archive": "image.tar",
  "reference": "product/eval:policy-scan",
  "imageId": "sha256:optional-exact-image-id"
}

The producer owns only product construction. It must not run Trivy, download a database, apply OpenVEX, or publish security reports. Its optional imageId denotes the configuration digest reported by Trivy.

OpenVEX

Target OpenVEX is optional and product-specific. Documents must use the OpenVEX 0.2 context, an absolute HTTPS identity, a non-future timestamp, and bounded exact not_affected statements. Every statement needs a supported justification, a substantive impact statement, and exact package PURLs.

Code Polishy scans the same immutable archive both without and with the document. It reconciles the full normalized result sets and fails when VEX:

  • suppresses a secret, misconfiguration, or end-of-life finding;
  • suppresses a vulnerability without the exact advisory/PURL statement;
  • changes or introduces a finding; or
  • contains an unused statement.

Accepted VEX findings remain visible in the report. General supply-chain vulnerabilityAssessments are a separate exact governance surface for structured dependency findings and do not loosen OpenVEX reconciliation. Container HIGH/CRITICAL findings remain governed only by the stricter OpenVEX contract.

Commands and prerequisites

code-polishy artifact-security
code-polishy supply-chain
code-polishy gate

The focused command runs configured artifact targets only. The online supply-chain profile and gate include the same module. A Docker CLI and server are required only when artifact targets exist; Trivy itself is policy-owned and does not become a target manifest dependency.

Behavior and final-state review evidence

Behavior-review files use a separate local artifact boundary under .code-polishy-reports/behavior-review. Intent capture may exist even when review remains optional. Each entry binds exact intent bytes, the current HEAD, and a digest of staged, unstaged, deleted, and untracked candidate state. The directory later holds additive requirements, the exact packet, structured final-state evidence and findings, proofs, logs, and receipt. Journal appends use an interprocess lock and every mutation publishes atomically.

Its hashes bind the same captured bytes, task-requirement snapshot, base and candidate policy decision, selected features, commits, packet, and proof records through the workflow. They are integrity checks, not signatures. The agent harness remains responsible for supplying the actual user request and isolating the review subagent. See the Behavior and Final-State Review Policy for the exact workflow and limits.