ClearCutt CLI & Governance Engine

The core command-line companion and compliance engine. Audit image tarballs, rebase downstream app images, enforce exceptions, verify OIDC signatures, generate policies, and spin up Nix runtime overlays.

SECURE PLATFORM ENFORCEMENT

Automate Verification,
Anywhere in CI/CD.

The clearcutt CLI keeps governance checks offline and runs app lifecycle operations registry-direct without Docker. Build precompiled artifacts onto ClearCutt bases, inspect multi-arch manifests, parse OpenVEX triages, and rebase patched bases under untouched application layers.

CLI Release Assets (latest release) Signed keylessly via Sigstore OIDC

Installation

Build from source in any fork, or download signed CLI binaries from a release that actually publishes CLI assets:

Requires Go 1.26+ installed on your system. Run compilation in the repository directory root:

git clone https://github.com/northcutted/clearcutt.git
cd clearcutt
go -C cli build -o ../clearcutt ./cmd/clearcutt
./clearcutt --version

Use this only for releases that include platform-specific ClearCutt binary assets and matching Sigstore bundles.

# Determine OS and Arch
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
BASE_URL="https://github.com/northcutted/clearcutt/releases/latest/download"

# Download binary asset and signature from the latest release
curl -fsSLO "${BASE_URL}/clearcutt-${OS}-${ARCH}"
curl -fsSLO "${BASE_URL}/clearcutt-${OS}-${ARCH}.sig"

# Verify keyless signature against the exact release workflow identity
cosign verify-blob "clearcutt-${OS}-${ARCH}" \
  --bundle "clearcutt-${OS}-${ARCH}.sig" \
  --certificate-identity "https://github.com/northcutted/clearcutt/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

chmod +x "clearcutt-${OS}-${ARCH}"
sudo mv "clearcutt-${OS}-${ARCH}" /usr/local/bin/clearcutt

Command Reference

ClearCutt CLI divides duties into clean, dedicated, zero-daemon subcommands. Explore the primary governance command boundaries below:

inspect

Inspect Catalog Metadata

Queries and audits high-fidelity catalog record structures locally. Evaluates configurations, architectures, image layers, unprivileged user settings, dynamic linkers, and cryptographic references.

# Show standard fixture details
clearcutt --catalog cli/internal/testdata/catalog inspect java21-distroless

# Force strict mode (fail on any unknown metadata fields)
clearcutt --catalog cli/internal/testdata/catalog inspect java21-distroless --strict

verify

Catalog And Release Checks

Runs catalog and release-evidence checks. The image gate checks catalog-record evidence flags, smoke test status, active support lifecycles, and vulnerability thresholds; release-evidence verifies a published OCI ref with registry-side Cosign and SLSA checks.

# Enforce catalog policy gates locally on a fixture image
clearcutt --catalog cli/internal/testdata/catalog verify image java21-distroless \
  --require-signature \
  --require-sbom \
  --require-provenance \
  --max-critical 0 \
  --max-high 3 \
  --allow-preview

# Verify published OCI release evidence against the Nix-backed verifier toolchain
clearcutt verify release-evidence \
  --ref ghcr.io/northcutted/clearcutt/clearcutt-java25:v0.14.0-distroless \
  --repo northcutted/clearcutt \
  --workflow-identity "https://github.com/northcutted/clearcutt/.github/workflows/release.yml@refs/heads/main" \
  --core-dir core

# Verify a local rebuild against published layers
clearcutt verify rebuild ghcr.io/northcutted/clearcutt/clearcutt-java21:v0.14.0-distroless \
  --target java21-distroless \
  --rebuild \
  --pull-registry-archive \
  --require-digest-match \
  --require-layer-match \
  --diffoscope-out rebuild.diff.txt \
  --output-predicate

# Validate local catalog structure and schemas
clearcutt --catalog cli/internal/testdata/catalog catalog validate

# Check generated-catalog evidence completeness
clearcutt --catalog ./dist/catalog verify catalog

certify

Declarative Downstream Auditor

Audits downstream application image tarballs offline. Unpacks layered filesystems in-memory to verify the absence of shells, interactive package managers, and root UIDs.

# Export docker/podman OCI tarball for the digest-pinned app image
APP_IMAGE=ghcr.io/acme/my-app:1.0.0
APP_DIGEST=$(docker buildx imagetools inspect "$APP_IMAGE" --format '{{json .Manifest.Digest}}' | tr -d '"')
docker save "$APP_IMAGE" -o my-app.tar

# Run declarative offline certification checks
clearcutt certify my-app.tar \
  --base java25-distroless \
  --policy certification-policy.yaml \
  --image-ref "${APP_IMAGE%:*}@${APP_DIGEST}"

app build / rebase / template

Rebasable App Lifecycle

Builds precompiled artifacts directly into OCI images, compares candidate bases, and rebases patched base layers under byte-preserved application layers with cosign signature and attestation gates. Also scaffolds app-team starters.

# Scaffold an app-team starter project using ClearCutt
clearcutt app template java --output clearcutt-template-java --name my-java-app

# Build a rebasable app image
clearcutt app build \
  --base java21-distroless \
  --artifact target/app.jar \
  --dest /workspace/app.jar \
  --entrypoint '["java","-jar","/workspace/app.jar"]' \
  --image ghcr.io/acme/payments-api:1.0.0

# Rebase after the base is patched
clearcutt app rebase \
  --image ghcr.io/acme/payments-api:1.0.0 \
  --candidate-base ghcr.io/northcutted/clearcutt/clearcutt-java21:vX.Y.Z-distroless \
  --candidate-base-id java21-distroless \
  --tag ghcr.io/acme/payments-api:1.0.0-rebased \
  --dev-identity "$DEV_SIGNER" \
  --sign \
  --attest

All stack examples

diff

Release Difference Analyser

Generates release-to-release differences. Resolves release tags and tag-aliases dynamically, mapping image size changes, platform additions, packages updates, and CVE deltas.

# Diff previous release vs latest
clearcutt diff java25-distroless --from latest-1 --to latest

overlay generate / verify

Nix Overlay Scaffolder

Generates flake-backed grafting workspaces to overlay ClearCutt runtimes onto enterprise-mandated base images. The verifier emits an offline in-toto predicate proving the grafted image preserves the runtime /nix/store closure bytes.

# Scaffold Java 21 UBI9 graft workspace
clearcutt overlay generate \
  --runtime java21 \
  --tier slim \
  --base registry.access.redhat.com/ubi9/ubi-minimal@sha256:... \
  --runtime-ref ghcr.io/northcutted/clearcutt/clearcutt-java21:v0.14.0-slim@sha256:... \
  --image ghcr.io/acme/java21-ubi:v0.14.0 \
  --output my-java21-overlay/

# Emit an offline closure-equivalence predicate
clearcutt overlay verify \
  --runtime-archive clearcutt-java21.tar \
  --grafted-archive my-java21-overlay/result \
  --runtime-ref ghcr.io/northcutted/clearcutt/clearcutt-java21:v0.14.0-slim@sha256:... \
  --grafted-ref ghcr.io/acme/java21-ubi:v0.14.0@sha256:... \
  --target java21-slim \
  --output-predicate

conformance run

Offline Conformance Auditor

Audits the current host/container environment offline — run it inside the image under test. Validates timezone configuration, CA certificate pathways, unprivileged execution, a writable /tmp, and any language interpreters on PATH.

# Audit the current environment (run inside the container under test)
clearcutt conformance run --expect-runtime java

exceptions validate

Exceptions Schema Validator

Audits declarative exceptions.yaml governance files against standard schemas. Verifies active owners, reference tags, and immediately flags any expired exception mappings.

# Validate exceptions catalog file
clearcutt exceptions validate exceptions.yaml --fail-on-expired-exceptions

mirror / mirror verify

Mirroring script generator & verifier

Generates high-fidelity skopeo and cosign scripts to copy multi-arch base layers while preserving Sigstore signatures and referrers. Verifies mirrored referrers offline.

# Generate secure copy script
clearcutt mirror --source ghcr.io/acme/java25 --target my-registry.internal/java25

# Offline verification of copied referrers
clearcutt mirror verify --source ghcr.io/acme/java25 --target my-registry.internal/java25

platform bootstrap / render / plan / apply

Control Plane Bootstrap

Renders a user-owned GitHub control-plane repository, prints side-effect-free plans, applies confirmed GitHub setup through gh/git, and keeps the existing fleet scaffold path available for image-factory operators.

# Render and plan a Nix-free catalog control plane
clearcutt platform bootstrap github \
  --profile catalog-only \
  --owner acme \
  --repo image-platform \
  --registry-base ghcr.io/acme/image-platform \
  --pages \
  --environment production \
  --dir ./image-platform \
  --dry-run \
  --force

# Apply only after reviewing the plan
clearcutt platform apply github \
  --plan ./image-platform/.clearcutt/clearcutt.plan.json \
  --confirm

# Fleet profile still supports full image-factory scaffolding
clearcutt platform render ./golden-images --profile fleet --owner acme --repo golden-images --force

Standard Governance Schemas

ClearCutt uses strict schema structures for governance files to ensure consistency across local and pipeline builds.

1. Exceptions YAML (`exceptions.yaml`)

Used in verify, vex, and exceptions validate to document accepted CVEs, temporary business exemptions, and active owners:

apiVersion: clearcutt.dev/v1
kind: VulnerabilityExceptions
metadata:
  name: app-triage-exceptions
spec:
  exceptions:
    - id: "CVE-2026-9999"
      package: "openssl"
      image: "*"
      release: "*"
      status: "accepted_risk"
      reason: "inherited_from_base"
      owner: "eddie-northcutt"
      createdAt: "2026-05-30"
      expiresAt: "2026-08-30"
      references:
        - "https://nvd.nist.gov/vuln/detail/CVE-2026-9999"
      notes: "Reviewed as unreachable in this distroless runtime closure; keep exception owner and expiry current."

2. Certification Policy YAML (`certification-policy.yaml`)

Enforces downstream OCI compliance gates dynamically inside GHA workflows or local audits using certify:

apiVersion: clearcutt.dev/v1
kind: CertificationPolicy
metadata:
  name: production-hardening-contract
spec:
  base:
    allowedImages:
      - "java21-distroless"
      - "node22-slim"
    requireDigestPinned: true
    requireKnownBase: true
  supplyChain:
    requireSignature: true
    requireProvenance: true
    requireSbom: true
    minimumSlsaLevel: 3
  runtime:
    requireNonRoot: true
    forbidShell: true
    forbidPackageManagers: true
    forbidDevTier: true
  lifecycle:
    allowPreview: false
    allowDeprecated: false
    allowExperimental: false
  vulnerabilities:
    maxCritical: 0
    maxHigh: 3
    allowExceptions: true
    exceptionFile: "exceptions.yaml"

3. Rebase Attestation JSON (`rebase-attestation.schema.json`)

Records the source digest, base-layer swap, preserved compressed app-layer digests, compatibility policy, and verified developer signature evidence for app rebase --attest.

{
  "predicateType": "https://clearcutt.dev/attestations/rebase/v1",
  "predicate": {
    "sourceImage": "ghcr.io/acme/payments-api:1.0.0",
    "sourceDigest": "sha256:...",
    "preservedAppLayers": ["sha256:..."],
    "developerSignatureVerified": true,
    "developerIdentity": "$DEV_SIGNER",
    "rebaseDecision": "allowed"
  }
}