acc

module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 27, 2025 License: Apache-2.0

README

acc - Secure Workload Accelerator

acc is a secure workload accelerator that turns source code and OCI artifacts into cryptographically verifiable, policy-compliant workloads.

acc wraps and hardens OCI workflows with verification gates - ensuring that only verified, policy-compliant workloads can be built, run, pushed, or promoted.

Core Principles

  • Verification gates execution - If verification fails, workloads cannot run, push, or promote
  • Red output means stop - Always
  • Security by default - No bypass flags, no silent degradation
  • Explicit guarantees - Trust is cryptographic, not implied

Features

  • Policy-gated builds - OCI image builds with automatic SBOM generation
  • Verification enforcement - SBOM validation, policy compliance, attestation checking
  • Secure runtime - Run workloads locally with least-privilege defaults
  • Cryptographic attestations - Sign and verify build provenance
  • Multi-tool support - Works with Docker, Podman, Buildah, and nerdctl

Demo

See acc in action - 60-second auto-playing terminal walkthrough:

👉 Launch Interactive Demo 👈

Or open docs/demo/index.html locally in your browser

The demo shows:

  • Initializing an acc project with security policies
  • Verifying a compliant image (✓ PASS - non-root user)
  • Inspecting trust summary (SBOM, attestation, verification status)
  • Verifying a non-compliant image (✗ FAIL - runs as root)
  • Explaining policy violation with remediation steps
  • Creating cryptographic attestation for verified image

Note: This is an illustrative demo with simulated output. No commands are executed on your system.

Quick Start

Prerequisites
  • Go 1.21 or later
  • One of: Docker, Podman, or Buildah
  • syft for SBOM generation
Installation

Download the latest release from GitHub Releases:

Linux (AMD64):

# Download the latest release
VERSION="0.2.4"
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/acc_${VERSION}_linux_amd64.tar.gz"

# Verify checksum (recommended)
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/checksums.txt"
sha256sum -c checksums.txt --ignore-missing

# Extract and install
tar -xzf "acc_${VERSION}_linux_amd64.tar.gz"
sudo mv acc-linux-amd64 /usr/local/bin/acc
chmod +x /usr/local/bin/acc

# Verify installation
acc version

macOS (Apple Silicon):

# Download the latest release
VERSION="0.2.4"
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/acc_${VERSION}_darwin_arm64.tar.gz"

# Verify checksum (recommended)
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/checksums.txt"
shasum -a 256 -c checksums.txt --ignore-missing

# Extract and install
tar -xzf "acc_${VERSION}_darwin_arm64.tar.gz"
sudo mv acc-darwin-arm64 /usr/local/bin/acc
chmod +x /usr/local/bin/acc

# Verify installation
acc version

macOS (Intel):

# Use acc_${VERSION}_darwin_amd64.tar.gz instead
VERSION="0.2.4"
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/acc_${VERSION}_darwin_amd64.tar.gz"
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/checksums.txt"
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf "acc_${VERSION}_darwin_amd64.tar.gz"
sudo mv acc-darwin-amd64 /usr/local/bin/acc
chmod +x /usr/local/bin/acc
acc version

Windows (AMD64):

# Download the latest release
$VERSION = "0.2.4"
Invoke-WebRequest -Uri "https://github.com/cloudcwfranck/acc/releases/download/v$VERSION/acc_${VERSION}_windows_amd64.zip" -OutFile "acc_${VERSION}_windows_amd64.zip"

# Download checksums for verification
Invoke-WebRequest -Uri "https://github.com/cloudcwfranck/acc/releases/download/v$VERSION/checksums.txt" -OutFile "checksums.txt"

# Extract
Expand-Archive -Path "acc_${VERSION}_windows_amd64.zip" -DestinationPath .

# Verify
.\acc-windows-amd64.exe version

# Add to PATH (optional - requires admin)
# Move-Item .\acc-windows-amd64.exe C:\Windows\System32\acc.exe

CI/CD Usage:

# GitHub Actions / GitLab CI / Jenkins
VERSION="0.2.4"
OS="linux"  # or darwin, windows
ARCH="amd64"  # or arm64

# Download binary
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/acc_${VERSION}_${OS}_${ARCH}.tar.gz"
curl -LO "https://github.com/cloudcwfranck/acc/releases/download/v${VERSION}/checksums.txt"

# Verify checksum
sha256sum -c checksums.txt --ignore-missing || shasum -a 256 -c checksums.txt --ignore-missing

# Extract
tar -xzf "acc_${VERSION}_${OS}_${ARCH}.tar.gz"

# Make executable and add to PATH
chmod +x acc-${OS}-${ARCH}
sudo mv acc-${OS}-${ARCH} /usr/local/bin/acc

# Use in pipeline
acc version
acc verify myimage:latest
Option 2: Build from Source
# Prerequisites: Go 1.21+
git clone https://github.com/cloudcwfranck/acc.git
cd acc

# Build
go build -o acc ./cmd/acc

# Install (optional)
sudo mv acc /usr/local/bin/

# Verify
acc version
Basic Usage
1. Initialize a project
# Create a new acc project
acc init my-project

# This creates:
# - acc.yaml (project configuration)
# - .acc/policy/default.rego (starter policy)
2. Review configuration
cat acc.yaml

Example acc.yaml:

project:
  name: my-project

build:
  context: .
  defaultTag: latest

registry:
  default: localhost:5000

policy:
  mode: enforce  # enforce|warn

signing:
  mode: keyless  # keyless|key

sbom:
  format: spdx   # spdx|cyclonedx
3. Build an image
# Build with SBOM generation
acc build

# Or specify a custom tag
acc build --tag myregistry.io/myapp:v1.0.0

The build command will:

  • Build the OCI image using available tools (docker/podman/buildah)
  • Generate an SBOM using syft
  • Store artifacts in .acc/sbom/
4. Verify compliance
# Verify SBOM and policy compliance
acc verify

# JSON output
acc verify --json

Verification checks:

  • SBOM presence
  • Policy compliance (using Rego policies in .acc/policy/)
  • Attestations (for promotion workflows)
5. Run workload (with verification gate)
# Run with verification - will fail if verification fails
acc run myimage:latest

# Run with custom security settings
acc run myimage:latest --user 1000 --network bridge --read-only

# Run with specific capabilities
acc run myimage:latest --cap-add NET_ADMIN

Important: acc run always verifies before execution. If verification fails, the workload will NOT run.

Website

The official acc website provides enterprise-grade download management with automatic updates:

🌐 acc.vercel.app (deployed after v0.2.6 release)

Enterprise Features
  • 🎯 Stable-by-default downloads - Always shows latest stable release (non-prerelease)
  • ⚠️ Pre-release support - Optional toggle for early access with clear warnings
  • 🔐 Checksum verification - SHA256 verification for all downloads
  • 📊 Operational health - Real-time monitoring at /api/health and /status
  • ⚡ Auto-updates - Updates within 60 seconds of new GitHub Releases
  • 🧪 CI-validated - Every PR runs unit tests + smoke tests
How It Stays Up-to-Date

Dual Update Mechanism (Belt + Suspenders):

  1. Deploy Hook (Immediate): When a release is published on GitHub:

    • GitHub Actions triggers Vercel deploy hook via .github/workflows/site-deploy.yml
    • Site rebuilds with new release data in 30-60 seconds
    • Critical path for urgent updates

  2. ISR (Fallback): Incremental Static Regeneration with 60-second revalidation:

    • Server-side API routes refetch release data every 60 seconds
    • Guarantees updates even if deploy hook fails
    • Zero-configuration fallback

Result: New releases appear on the website within 1 minute, automatically.

Release Integrity

Every release is validated before publication:

  • ✅ Checksums required: All platform archives must have SHA256 checksums
  • ✅ Automated validation: CI fails if checksums missing or invalid
  • ✅ Download verification: Website shows checksum verification in install snippet
  • ✅ Health monitoring: /api/health validates release completeness

What users see:

  • If checksums present: Full SHA256 table + verification commands
  • If checksums missing: Warning banner "⚠️ Checksums not available for this release"
Local Development
cd site

# Install dependencies
npm install

# Run development server
npm run dev
# Open http://localhost:3000

# Run tests
npm test

# Production build
npm run build
npm run start
Architecture
  • Frontend: Next.js 14 (App Router, TypeScript, React Server Components)
  • Backend: GitHub Releases API (ISR-cached, 60s revalidation)
  • Hosting: Vercel
  • Auto-updates: ISR (60s) + Deploy Hooks (immediate)
  • Testing: Jest (27 unit tests) + Smoke tests (health, download, status pages)

See site/README.md for complete deployment, testing, and operational documentation.

SBOM Workflows

acc requires SBOMs for verification. Choose the workflow that fits your build process:

Use acc build for full automation - it builds the image AND generates the SBOM:

# Initialize project
acc init

# Build with SBOM generation (requires syft)
acc build -t myapp:latest .

# Verify
acc verify myapp:latest

Pros: Single command, automatic SBOM generation Cons: Requires syft installed

Workflow 2: Docker + Manual SBOM Generation

If you prefer docker build or have existing Dockerfiles, generate SBOM separately:

# Initialize project
acc init

# Build with Docker (standard workflow)
docker build -t myapp:latest .

# Generate SBOM manually
mkdir -p .acc/sbom
syft myapp:latest -o spdx-json=.acc/sbom/$(basename $(pwd)).spdx.json

# Verify
acc verify myapp:latest

Required: The SBOM filename MUST match pattern: <project-name>.<format>.json Example: For project "myapp" with format "spdx": .acc/sbom/myapp.spdx.json

Workflow 3: CI/CD Integration

For CI/CD pipelines, separate build and verify steps:

# In CI build stage
docker build -t myapp:${VERSION} .
syft myapp:${VERSION} -o spdx-json=.acc/sbom/myapp.spdx.json

# In CI verify stage
acc verify myapp:${VERSION} --json

# Gate deployment on exit code
if [ $? -eq 0 ]; then
  docker push myapp:${VERSION}
fi
SBOM Troubleshooting

If acc verify reports "SBOM required but not found":

  1. Check SBOM exists: ls .acc/sbom/
  2. Verify filename matches project: Should be <project-name>.spdx.json or <project-name>.cyclonedx.json
  3. Check project name in acc.yaml: Must match SBOM filename prefix
  4. Generate SBOM: syft <image> -o spdx-json=.acc/sbom/<project>.spdx.json

Note: acc will detect ANY .json file in .acc/sbom/ as a fallback if exact match not found.

Commands

Command Description
init Initialize a new acc project
build Build OCI image with SBOM generation
verify Verify SBOM, policy compliance, and attestations
run Verify and run workload locally with security defaults
inspect Inspect artifact trust summary with verification status
attest Create attestation for artifact with build metadata
push Verify and push verified artifacts to registry
promote Re-verify and promote workload to environment
trust status View trust status with profile and violation details
policy explain Explain last verification decision
upgrade Upgrade acc to the latest version with checksum verification
config Get or set configuration values (coming soon)
login Authenticate to registries (coming soon)
version Print version information

Global Flags

--color string       Colorize output (auto|always|never) [default: auto]
--json              Output in JSON format
--quiet, -q         Suppress non-critical output
--no-emoji          Disable emoji in output
--policy-pack path  Path to policy pack
--config path       Path to config file

Policy Profiles

New in v0.2.0: Policy Profiles provide an opt-in configuration layer for post-evaluation violation filtering.

Overview

Profiles allow you to:

  • Filter violations by rule name - Only enforce specific policies
  • Ignore violations by severity - Suppress informational/low severity issues
  • Convert violations to warnings - Display issues without blocking
  • Customize enforcement per environment - Different profiles for dev/staging/prod

Important: Profiles do NOT modify policy evaluation - they filter results AFTER OPA runs. All policies still execute; profiles only control which violations block execution.

Quick Start
# Verify with baseline profile (allows common patterns)
acc verify myapp:latest --profile baseline

# Verify with strict profile (production-ready)
acc verify myapp:prod --profile strict

# View trust status with profile information
acc trust status myapp:latest
Profile Schema (v1)

Profiles are YAML files stored in .acc/profiles/<name>.yaml:

schemaVersion: 1  # Required: must be 1
name: baseline    # Required: profile name
description: Baseline enforcement profile  # Required

# Optional: Only enforce these policies (allowlist)
policies:
  allow:
    - no-root-user
    - no-latest-tag
    - sbom-present

# Optional: Ignore these violations
violations:
  ignore:
    - informational  # By severity
    - low            # By severity
    - missing-healthcheck  # By rule name

# Optional: Warning display
warnings:
  show: true  # Display ignored violations as warnings
Using Profiles

Profile loading:

  • --profile baseline → Loads .acc/profiles/baseline.yaml
  • --profile ./custom.yaml → Loads explicit path
  • No --profile flag → Profiles disabled (v0.1.x behavior)

Exit behavior:

  • With profile: Only active violations cause failure
  • Ignored violations → Displayed as warnings (if warnings.show: true)
  • No state file → Exit code 2
Example Profiles

Baseline Profile (.acc/profiles/baseline.yaml) - Development/Testing:

schemaVersion: 1
name: baseline
description: Baseline enforcement for development

policies:
  allow:
    - no-root-user
    - no-latest-tag
    - sbom-present

violations:
  ignore:
    - informational
    - low

warnings:
  show: true

Strict Profile (.acc/profiles/strict.yaml) - Production:

schemaVersion: 1
name: strict
description: Strict enforcement for production

policies:
  allow:
    - no-root-user
    - no-latest-tag
    - no-privileged
    - sbom-present
    - read-only-rootfs
    - drop-all-capabilities

violations:
  ignore: []  # No exceptions

warnings:
  show: false
Trust Status Command

View verification status with profile information (v0.2.7):

$ acc trust status myapp:latest
Trust Status

Image:          myapp:latest
Last Verified:  2025-01-20T10:30:00Z

Status:         ✓ PASS
Profile:        baseline

Artifacts:
  SBOM:         present
  Attestations: 2 found

Warnings (2 ignored):
  [low] missing-healthcheck: Container lacks health check
  [informational] old-base-image: Base image is 30 days old

Exit codes (PRESERVED - unchanged):

  • 0 - Trust status is pass
  • 1 - Trust status is fail or warn
  • 2 - Trust status is unknown (cannot compute)

JSON output (v0.2.7):

$ acc trust status --json myapp:latest
{
  "schemaVersion": "v0.2",
  "imageRef": "myapp:latest",
  "status": "pass",
  "sbomPresent": true,
  "violations": [],
  "warnings": [
    {
      "rule": "missing-healthcheck",
      "severity": "low",
      "message": "Container lacks health check"
    }
  ],
  "attestations": [
    ".acc/attestations/abc123456789/20250120-103000-attestation.json"
  ],
  "timestamp": "2025-01-20T10:30:00Z"
}

Per-Image Isolation (v0.2.7):

  • Trust status is scoped to specific image digests
  • Attestations shown are only for the requested image
  • No cross-image state leakage between different images
Backward Compatibility

All v0.1.x behavior is preserved when --profile is not used:

  • acc verify myapp:latest → Identical to v0.1.8
  • Profiles are explicit opt-in only
  • No auto-discovery or defaults
  • JSON output unchanged without profile
Migration from v0.1.x

  1. Continue using v0.1.x behavior:

    acc verify myapp:latest  # No changes required

  2. Adopt profiles gradually:

    # Create baseline profile
mkdir -p .acc/profiles
cat > .acc/profiles/baseline.yaml <<EOF
schemaVersion: 1
name: baseline
description: Development profile
violations:
  ignore:
    - informational
warnings:
  show: true
EOF

# Use in CI/CD
acc verify myapp:latest --profile baseline

  3. Different profiles per environment:

    acc verify myapp:dev --profile baseline    # Development
acc verify myapp:prod --profile strict     # Production

Upgrade

acc includes built-in self-update functionality with cryptographic verification to ensure you're always running the latest stable release.

Upgrade to Latest Version
# Upgrade to the latest stable release
acc upgrade

What happens:

  1. Fetches latest release information from GitHub
  2. Checks if you're already running the latest version
  3. Downloads the appropriate binary for your OS/ARCH
  4. Verifies SHA256 checksum against official checksums.txt
  5. Atomically replaces the current binary (with backup on Unix)
  6. Displays upgrade summary with version and checksum

Output:

Current version: v0.1.5
Target version:  v0.1.6
Asset:           acc_0.1.6_linux_amd64.tar.gz
Checksum:        a1b2c3d4e5f6...
Installed to:    /usr/local/bin/acc

Successfully upgraded from v0.1.5 to v0.1.6
Upgrade to Specific Version
# Install a specific version
acc upgrade --version v0.1.5

# Or without the 'v' prefix
acc upgrade --version 0.1.5

Use this to:

  • Pin to a known-good version in CI/CD
  • Downgrade to a previous version if needed
  • Test pre-release versions
Dry Run

Preview what would happen without actually downloading or installing:

acc upgrade --dry-run

# Example output:
# Would upgrade from v0.1.5 to v0.1.6 using acc_0.1.6_linux_amd64.tar.gz
JSON Output

For automation and CI/CD integration:

acc upgrade --json

Output:

{
  "currentVersion": "v0.1.5",
  "targetVersion": "v0.1.6",
  "updated": true,
  "message": "Successfully upgraded from v0.1.5 to v0.1.6",
  "assetName": "acc_0.1.6_linux_amd64.tar.gz",
  "checksum": "a1b2c3d4e5f67890...",
  "installPath": "/usr/local/bin/acc"
}
Platform Support

The upgrade command automatically detects your platform and downloads the correct binary:

OS Architecture Asset Pattern
Linux amd64 acc_<version>_linux_amd64.tar.gz
Linux arm64 acc_<version>_linux_arm64.tar.gz
macOS amd64 (Intel) acc_<version>_darwin_amd64.tar.gz
macOS arm64 (Apple Silicon) acc_<version>_darwin_arm64.tar.gz
Windows amd64 acc_<version>_windows_amd64.zip
Windows Special Handling

On Windows, running executables cannot be replaced directly due to file locking. The upgrade command handles this by:

  1. Downloading the new version to acc.new.exe
  2. Providing manual replacement instructions:
Windows binary downloaded to: C:\path\to\acc.new.exe

To complete upgrade:
1. Close this terminal
2. Rename acc.exe to acc.exe.old
3. Rename acc.new.exe to acc.exe
4. Delete acc.exe.old
Security

The upgrade process includes multiple security checks:

  • Official sources only - Downloads from github.com/cloudcwfranck/acc releases
  • SHA256 verification - All downloads verified against official checksums.txt
  • Checksum mismatch = abort - Installation blocked on verification failure
  • Download failure = abort - No partial or corrupted updates
  • Atomic replacement - Unix systems use atomic rename (non-Windows)
  • Backup/rollback - Failed installations restore previous binary
Enterprise-Grade Verification (v0.2.7+)

For environments requiring stronger supply-chain security, acc upgrade supports optional cosign signature verification and SLSA provenance verification.

Cosign Signature Verification

Verify release signatures using Sigstore cosign:

# Verify with cosign signature (requires cosign in PATH)
acc upgrade --verify-signature

# Verify with specific public key
acc upgrade --verify-signature --cosign-key /path/to/public.key
acc upgrade --verify-signature --cosign-key https://example.com/key.pub

# Keyless verification (uses certificate from release assets)
acc upgrade --verify-signature

What happens:

  1. Downloads release asset and checksums (standard flow)
  2. Verifies SHA256 checksum (standard flow)
  3. Downloads signature file (.sig) from release assets
  4. Runs cosign verify-blob to verify cryptographic signature
  5. Aborts upgrade if signature verification fails

Requirements:

  • cosign must be installed and in PATH
  • Release assets must include .sig signature files
  • For keyless: .pem certificate files must be present

Error handling:

$ acc upgrade --verify-signature
Error: signature verification failed: cosign is required for signature verification
but was not found in PATH. Install cosign: https://docs.sigstore.dev/cosign/installation/
SLSA Provenance Verification

Verify build provenance meets SLSA requirements:

# Verify SLSA provenance
acc upgrade --verify-provenance

What happens:

  1. Downloads release asset and checksums (standard flow)
  2. Verifies SHA256 checksum (standard flow)
  3. Fetches SLSA provenance attestation (.intoto.jsonl) from release assets
  4. Validates provenance structure and builder identity
  5. Ensures build was performed by GitHub Actions from correct repository
  6. Aborts upgrade if provenance validation fails

Provenance checks:

  • ✓ Valid SLSA predicate type (contains "slsa" or "provenance")
  • ✓ Builder identity is GitHub Actions
  • ✓ Build type is GitHub Actions workflow
  • ✓ Source repository is cloudcwfranck/acc

Supported formats:

  • provenance.intoto.jsonl (global)
  • <tag>.intoto.jsonl (per-release)
  • <assetName>.intoto.jsonl (per-asset)

Note: Current implementation performs structural validation only. For full cryptographic verification, integrate slsa-verifier CLI tool.

Combined Enterprise Mode

Use both verifications for maximum supply-chain security:

# Enterprise mode: verify both signature and provenance
acc upgrade --verify-signature --verify-provenance

Output:

Current version: v0.2.6
Target version:  v0.2.7
Asset:           acc_0.2.7_linux_amd64.tar.gz
Checksum:        a1b2c3d4e5f6...
Signature:       ✓ Verified
Provenance:      ✓ Verified
Installed to:    /usr/local/bin/acc

Successfully upgraded from v0.2.6 to v0.2.7

JSON output:

{
  "currentVersion": "v0.2.6",
  "targetVersion": "v0.2.7",
  "updated": true,
  "message": "Successfully upgraded from v0.2.6 to v0.2.7",
  "assetName": "acc_0.2.7_linux_amd64.tar.gz",
  "checksum": "a1b2c3d4e5f67890...",
  "signatureVerified": true,
  "provenanceVerified": true,
  "installPath": "/usr/local/bin/acc"
}
Release Asset Conventions

For verification to work, releases should include:

Required (all releases):

  • Binary assets (.tar.gz, .zip)
  • checksums.txt - SHA256 checksums

Optional (enterprise verification):

  • <asset>.sig - Cosign signature files (for --verify-signature)
  • <asset>.pem - Certificate files (for keyless cosign)
  • provenance.intoto.jsonl - SLSA provenance (for --verify-provenance)

Example release assets for v0.2.7:

acc_0.2.7_linux_amd64.tar.gz
acc_0.2.7_linux_amd64.tar.gz.sig        # cosign signature
acc_0.2.7_linux_amd64.tar.gz.pem        # keyless certificate
acc_0.2.7_darwin_arm64.tar.gz
acc_0.2.7_darwin_arm64.tar.gz.sig
checksums.txt
provenance.intoto.jsonl                  # SLSA provenance
Default Behavior Unchanged

Important: Verification is 100% opt-in. Default upgrade behavior remains unchanged:

# Default: checksum verification only (v0.1.x behavior)
acc upgrade

# Same as before - no signature or provenance checks
acc upgrade --version v0.2.7

Only when explicitly requested with flags does verification occur:

  • Without --verify-signature: No cosign requirement
  • Without --verify-provenance: No provenance requirement
  • Flags can be used independently or together
Already Up-to-Date

If you're already running the latest version:

$ acc upgrade
Already up-to-date (version v0.1.6)

Exit code is 0 (success) when already up-to-date.

CI/CD Usage

Pin versions in CI/CD pipelines for reproducibility:

# GitHub Actions example
- name: Install acc
  run: |
    curl -sSfL https://github.com/cloudcwfranck/acc/releases/download/v0.1.6/acc_0.1.6_linux_amd64.tar.gz | tar xz
    chmod +x acc
    sudo mv acc /usr/local/bin/

# Or use acc upgrade for latest
- name: Upgrade acc
  run: acc upgrade --version 0.1.6
Troubleshooting

Issue: "checksum mismatch"

  • The downloaded binary's checksum doesn't match official checksums.txt
  • This could indicate network corruption or a compromised download
  • Solution: Retry the upgrade, check network connection

Issue: "no release asset found"

  • Your OS/ARCH combination doesn't have a pre-built binary
  • Solution: Build from source (see Installation section)

Issue: Permission denied (Unix)

  • The binary is installed in a protected directory (e.g., /usr/local/bin/)
  • Solution: Run with sudo: sudo acc upgrade

Issue: Cannot replace running executable (Windows)

  • Expected behavior on Windows
  • Solution: Follow the manual replacement instructions provided

Security Model

Verification Chain
  1. Build → OCI artifact + SBOM
  2. Verify → Policy evaluation + SBOM check + state persistence
  3. Inspect → Trust summary with verification status
  4. Attest → Cryptographic attestation of verification results
  5. Push → Push verified artifacts to registry (verification gated)
  6. Promote → Re-verify and promote to environment (verification gated)
  7. Run → Execute workload locally (verification gated)
Runtime Security Defaults

When using acc run, the following security defaults are applied:

  • Network isolation - --network none by default
  • Capability dropping - All Linux capabilities dropped by default
  • No new privileges - Prevents privilege escalation
  • Optional read-only root - Use --read-only flag
Policy Enforcement

Policies are written in Rego and stored in .acc/policy/. The default policy enforces:

  • No root user execution
  • SBOM required for all builds
  • Attestations required for promotion

To customize policies, edit .acc/policy/default.rego or add new .rego files.

Exit Codes

  • 0 - Success
  • 1 - Failure / Blocked
  • 2 - Warnings (allowed in warn mode)

Examples

Build and verify a project
# Initialize
acc init web-app

# Add a Dockerfile to your project
cat > Dockerfile <<EOF
FROM alpine:latest
RUN apk add --no-cache nginx
USER nginx
EXPOSE 8080
EOF

# Build with SBOM
acc build --tag myapp:latest

# Verify
acc verify
Run with custom security settings
# Run with bridge network and specific user
acc run myapp:latest --network bridge --user nginx

# Run with read-only filesystem
acc run myapp:latest --read-only

# Run with specific capabilities
acc run myapp:latest --cap-add NET_BIND_SERVICE --user www-data
JSON output for CI/CD
# Initialize with JSON output
acc init --json my-project

# Build with JSON output
acc build --json --tag myapp:latest

# Verify with JSON output
acc verify --json
Inspect artifact trust
# Inspect an image to see trust summary
acc inspect myapp:latest

# View trust summary with JSON output
acc inspect myapp:latest --json

# Shows:
# - Image digest and reference
# - SBOM presence and location
# - Attestations found
# - Last verification status
# - Policy mode and waivers
Create attestations

Attestations capture verification results as deterministic, auditable artifacts (v0.2.7):

# First, build and verify the image
acc build --tag myapp:latest
acc verify myapp:latest

# Inspect trust summary
acc inspect myapp:latest

# Create attestation (requires verification state)
acc attest myapp:latest

# View attestation in JSON
acc attest myapp:latest --json

# View trust status (shows attestation)
acc trust status myapp:latest

How attestations work (v0.2.7):

  1. Requires verification state - acc attest will fail if .acc/state/last_verify.json doesn't exist
  2. Digest-based matching - Uses image digest comparison (not tag strings) to ensure safety
  3. Image mismatch protection - Prevents attesting wrong image even if tags are reused
  4. Canonical hashing - Creates deterministic hash of verification results with sorted violations
  5. Per-image storage - Saves to .acc/attestations/<digest-prefix>/<timestamp>-attestation.json
  6. State tracking - Updates .acc/state/last_attestation.json pointer
  7. Trust integration - Attestations appear in acc trust status for that specific image only

Attestation schema:

{
  "schemaVersion": "v0.1",
  "command": "attest",
  "timestamp": "2025-01-15T10:30:00Z",
  "subject": {
    "imageRef": "myapp:latest",
    "imageDigest": "sha256:abc123..."
  },
  "evidence": {
    "sbomRef": ".acc/sbom/myapp-latest.spdx.json",
    "policyPack": ".acc/policy",
    "policyMode": "enforce",
    "verificationStatus": "pass",
    "verificationResultsHash": "sha256:def456..."
  },
  "metadata": {
    "tool": "acc",
    "toolVersion": "v0.1.0",
    "gitCommit": "abc123def"
  }
}

The verificationResultsHash is computed using canonical JSON ordering, ensuring that identical verification results always produce the same hash regardless of field order.

Push verified artifacts

Push images to registries with verification gates:

# First, build and verify the image
acc build --tag registry.io/myapp:v1.0.0
acc verify registry.io/myapp:v1.0.0

# Push only if verification passed
acc push registry.io/myapp:v1.0.0

# View push result in JSON
acc push registry.io/myapp:v1.0.0 --json

How push works:

  1. Requires verification state - acc push will fail if .acc/state/last_verify.json doesn't exist
  2. Blocks failed verification - Cannot push if last verification status is "fail"
  3. Image reference validation - Ensures the image matches the last verified digest
  4. Attestation reference - If attestation exists, includes reference in output
  5. Tool detection - Uses nerdctl, docker, or oras (in that order)

Push workflow:

# Complete verified push workflow
acc build --tag myregistry.io/myapp:v1.0.0
acc verify myregistry.io/myapp:v1.0.0
acc inspect myregistry.io/myapp:v1.0.0
acc attest myregistry.io/myapp:v1.0.0
acc push myregistry.io/myapp:v1.0.0

This ensures that only verified, policy-compliant workloads with attestations can be pushed to registries.

Promote workloads to environments
# Promote to production (requires verification to pass)
acc promote myapp:dev --to prod

# Promotion:
# 1. Re-verifies with prod-specific policy
# 2. Blocks if verification fails
# 3. Re-tags image without rebuild
# 4. Verifies digest unchanged
Environment-specific configuration

Add to acc.yaml:

environments:
  prod:
    policy:
      mode: enforce
    registry:
      default: prod.registry.io
  staging:
    policy:
      mode: warn
    registry:
      default: staging.registry.io
Explain policy decisions
# View explanation of last verification
acc policy explain

# Shows:
# - Image and timestamp
# - Pass/fail status
# - Violations with remediation
# - Warnings
# - Policy decision details

# JSON output for automation
acc policy explain --json
Testing policy failures

See examples/intentional-failure/ for a Dockerfile that demonstrates verification gating by intentionally violating security policies.

What acc Does NOT Do

Per the design specification, acc explicitly does NOT:

  • Provide interactive shells into containers
  • Execute into running workloads
  • Perform runtime EDR/monitoring
  • Perform SAST/DAST scanning
  • Scan for secrets
  • Manage Kubernetes clusters

acc focuses exclusively on supply chain security and workload trust.

Development

Running tests

Unit Tests:

# Run all Go unit tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/config -v

CI Test Tiers:

acc uses a tiered CI testing strategy with increasing scope and runtime:

  • Tier 0: CLI Help Matrix (~10-20s, blocks PRs)

    • Validates all commands exist and show help
    • Runs on every PR and push
    bash scripts/cli_help_matrix.sh

  • Tier 1: E2E Smoke Tests (~60-90s, blocks PRs)

    • Offline end-to-end functional tests
    • Tests full workflow: init, build, verify, policy, attest, inspect, trust status
    • Requires: docker, opa, jq, syft
    bash scripts/e2e_smoke.sh

  • Tier 2: Registry Integration (optional, never blocks PRs)

    • Tests push/promote with GitHub Container Registry
    • Runs on schedule/tags/main only
    • Auto-skips if credentials unavailable
    GHCR_REPO="owner/repo" bash scripts/registry_integration.sh

Testing Contract:

See docs/testing-contract.md for:

  • Exit code guarantees
  • JSON output stability
  • Behavioral contracts
  • Script implementation patterns
Building
# Build for current platform
go build -o acc ./cmd/acc

# Build with version info
go build -ldflags "-X main.version=v0.2.4 -X main.commit=$(git rev-parse HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" -o acc ./cmd/acc

Documentation

See AGENTS.md for the complete specification and design principles.

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

  • All tests pass (go test ./...)
  • Code is formatted (gofmt)
  • Security principles are maintained
  • No bypass mechanisms are added

Support

For issues and feature requests, please open an issue on GitHub.

Directories

Path Synopsis
cmd
acc command
internal
attest
build
config
inspect
policy
profile
promote
push
runtime
trust
ui
upgrade
verify
waivers

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.