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.

Download Pre-Compiled Binaries (v0.8.1) Signed keylessly via Sigstore OIDC

Installation

You can quickly download the pre-compiled binary for your architecture from the GitHub Releases tab, or compile it directly from the repository source using Go 1.26:

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
make cli-build
./clearcutt --version

Run this shell command to fetch and install the correct architecture binary automatically:

# Determine OS and Arch
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
VERSION="v0.8.1"

# Download binary asset and signature from releases
curl -fsSLO "https://github.com/northcutted/clearcutt/releases/download/${VERSION}/clearcutt-${OS}-${ARCH}"
curl -fsSLO "https://github.com/northcutted/clearcutt/releases/download/${VERSION}/clearcutt-${OS}-${ARCH}.sig"

# Verify keyless signature offline
cosign verify-blob "clearcutt-${OS}-${ARCH}" \
  --bundle "clearcutt-${OS}-${ARCH}.sig" \
  --certificate-identity-regexp "https://github.com/northcutted/clearcutt/.*" \
  --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 details
clearcutt inspect java25-distroless

# Force strict mode (fail on any unknown metadata fields)
clearcutt inspect java25-distroless --strict

verify

Gated Verification Gatekeeper

Enforces software supply chain compliance checks. Gates on signatures, SBOMs, SLSA level requirements, smoke test status, active support lifecycles, and maximum vulnerability counts. Can verify images, local catalog indexes, or published OCI release evidence.

# Enforce full gate limits locally on a catalog image
clearcutt verify image java25-distroless \
  --require-signature \
  --require-sbom \
  --max-critical 0 \
  --max-high 3 \
  --exceptions exceptions.yaml

# Verify published OCI release evidence against Cosign + SLSA
clearcutt verify release-evidence \
  --ref ghcr.io/northcutted/clearcutt/clearcutt-java25:distroless-v0.6.2 \
  --repo northcutted/clearcutt \
  --workflow-identity "https://github.com/northcutted/clearcutt/.github/workflows/release.yml@refs/heads/main"

# Verify the local catalog structure and database schema compliance
clearcutt verify catalog

certify

Declarative Downstream Auditer

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
docker save ghcr.io/acme/my-app:latest -o my-app.tar

# Run declarative offline certification checks
clearcutt certify my-app.tar \
  --base java25-distroless \
  --policy certification-policy.yaml

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:distroless-v0.2.2 \
  --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

Nix Overlay Scaffolder

Generates self-contained Nix multi-stage grafting workspaces to overlay ClearCutt runtimes onto enterprise-mandated base images. Includes Makefile, Containerfile, smoke tests, and GitHub Actions pipelines.

# Scaffold Java 25 UBI9 graft workspace
clearcutt overlay generate \
  --runtime java25 \
  --tier distroless \
  --base registry.access.redhat.com/ubi9/ubi-minimal \
  --output my-java25-overlay/

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 init / status

Platform Kit Management

Initializes and checks the status of the forkable ClearCutt platform kit. Scaffolds initial fleet configuration templates, documents, and application templates, and validates platform components wiring.

# Initialize a new platform kit layout
clearcutt platform init --owner my-org --repo my-base-images

# Verify status of all platform wiring checks
clearcutt platform status

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: "Vulnerable functions are completely sealed and unreachable in our distroless runtime closures."

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:
      - "java25-distroless"
      - "python3.14-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"
  }
}