README
¶
epack is a CLI for creating, signing, and verifying Evidence Packs, cryptographically sealed bundles of compliance evidence. Collect security posture from cloud providers, identity systems, and SaaS tools. Sign with Sigstore. Share verifiable evidence with auditors and customers.
Why epack?
| Problem | epack Solution |
|---|---|
| Evidence scattered across tools | Bundle everything into one portable pack |
| "Trust me" screenshots | Cryptographic signatures prove who collected what, when |
| Manual evidence collection | Automated collectors gather evidence from APIs |
| Comparing audit periods | epack diff shows exactly what changed |
| Sharing evidence securely | Push to registries, pull with verification |
Install
# Homebrew (macOS/Linux)
brew install locktivity/tap/epack
# Go
go install -tags components github.com/locktivity/epack/cmd/epack@latest
# Binary releases (with SLSA Level 3 provenance)
# → github.com/locktivity/epack/releases
Quick Start
Option A: Build from files you already have
epack build evidence.pack ./reports/*.json --stream myorg/security
epack sign evidence.pack
epack verify evidence.pack
Option B: Automated collection pipeline
epack new my-pipeline && cd my-pipeline
# Edit epack.yaml to add collectors (GitHub, AWS, Okta, etc.)
export GITHUB_TOKEN=ghp_...
epack collect # Lock deps → sync binaries → run collectors → build pack
epack sign *.pack
Core Commands
| Command | What it does |
|---|---|
epack build |
Create a pack from files |
epack sign |
Sign with Sigstore (keyless or key-based) |
epack verify |
Verify integrity and signatures |
epack inspect |
Show pack contents and metadata |
epack diff |
Compare two packs (what changed?) |
epack collect |
Run collectors and build a pack |
What's in a Pack?
evidence.pack/
├── manifest.json # Metadata + SHA-256 digests
├── artifacts/ # Your evidence files
│ ├── github-posture.json
│ ├── aws-config.json
│ └── soc2-report.pdf
└── attestations/ # Sigstore signatures
└── manifest.json.sigstore.json
Components
epack is extensible through a component system:
| Component | Purpose | Scope | Example |
|---|---|---|---|
| Collectors | Gather evidence from APIs | Project | epack-collector-github |
| Tools | Analyze pack contents | Project | epack-tool-policy |
| Remotes | Push/pull to registries | Project | epack-remote-s3 |
| Utilities | Standalone helper apps | User | epack-util-viewer |
# Search the catalog
epack catalog search github
# Install a collector (project-scoped)
epack install collector github
# Install a utility (user-scoped, global)
epack utility install viewer
# Run an installed utility
epack utility viewer evidence.pack
When to Use epack
Good fit:
- Multi-source evidence collection (GitHub + AWS + Okta + ...)
- Audit trails requiring cryptographic proof
- Sharing evidence between organizations
- Comparing security posture over time
- CI/CD evidence pipelines
Consider alternatives if:
- Simple file archiving (use tar/zip)
- Real-time monitoring (use observability tools)
- Single-file attestations (use cosign directly)
Two Binaries, Two Security Profiles
| Variant | Use Case |
|---|---|
epack |
Full features: collectors, tools, remotes, utilities |
epack-core |
Pack operations only (no subprocess execution) |
Use epack-core for verification-only workflows (CI, auditors) where you don't need component orchestration.
Documentation
Getting Started
User Guides
Reference
For Component Authors
Security
Specification
Library Usage
import (
"github.com/locktivity/epack/pack"
"github.com/locktivity/epack/pack/builder"
)
// Build
b := builder.New("myorg/stream")
b.AddFile("./config.json")
b.Write("evidence.pack")
// Read and verify
p, _ := pack.Open("evidence.pack")
defer p.Close()
p.VerifyIntegrity()
Contributing
git clone https://github.com/locktivity/epack.git
cd epack
make test-all
See CONTRIBUTING.md for development setup and guidelines.
License
Apache License 2.0
Built by Locktivity
Locktivity builds tools for third-party security. We're developing epack in the open because portable, verifiable security evidence is a problem bigger than any one vendor.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
epack
command
Command epack is a CLI for creating, signing, and verifying evidence packs.
|
Command epack is a CLI for creating, signing, and verifying evidence packs. |
|
epack/cmd
Package cmd implements the epack command-line interface.
|
Package cmd implements the epack command-line interface. |
|
Package componentsdk provides a framework for building epack components (collectors, tools, remote adapters, and utilities) that are conformant with the epack component specification.
|
Package componentsdk provides a framework for building epack components (collectors, tools, remote adapters, and utilities) that are conformant with the epack component specification. |
|
fixtures/collector
command
Minimal collector fixture for SDK conformance testing.
|
Minimal collector fixture for SDK conformance testing. |
|
fixtures/remote
command
Minimal remote adapter fixture for SDK conformance testing.
|
Minimal remote adapter fixture for SDK conformance testing. |
|
fixtures/tool
command
Minimal tool fixture for SDK conformance testing.
|
Minimal tool fixture for SDK conformance testing. |
|
Package errors provides typed error handling for evidence pack operations.
|
Package errors provides typed error handling for evidence pack operations. |
|
internal
|
|
|
boundedio
Package boundedio provides IO utilities with security limits.
|
Package boundedio provides IO utilities with security limits. |
|
catalog
Package catalog provides tool catalog schema, caching, and search operations.
|
Package catalog provides tool catalog schema, caching, and search operations. |
|
catalog/resolve
Package resolve provides dependency resolution for tool installation.
|
Package resolve provides dependency resolution for tool installation. |
|
catalog/schema
Package schema provides the component catalog schema types and parsing.
|
Package schema provides the component catalog schema types and parsing. |
|
cli/exitmap
Package exitmap provides centralized error-to-exit-code mapping for the CLI.
|
Package exitmap provides centralized error-to-exit-code mapping for the CLI. |
|
cli/output
Package output provides formatted output for the epack CLI.
|
Package output provides formatted output for the epack CLI. |
|
cli/sigstore
Package sigstore provides shared utilities for Sigstore verification in CLI commands.
|
Package sigstore provides shared utilities for Sigstore verification in CLI commands. |
|
cmdutil
Package cmdutil provides shared CLI helpers for epack commands.
|
Package cmdutil provides shared CLI helpers for epack commands. |
|
collector
Package collector provides collector execution and workflow orchestration.
|
Package collector provides collector execution and workflow orchestration. |
|
collector/exec
Package exec provides process execution utilities for collectors.
|
Package exec provides process execution utilities for collectors. |
|
component
Package component provides unified types and utilities for both collectors and tools.
|
Package component provides unified types and utilities for both collectors and tools. |
|
component/config
Package config provides configuration parsing for epack.yaml files.
|
Package config provides configuration parsing for epack.yaml files. |
|
component/github
Package github provides a GitHub API client for fetching releases and assets.
|
Package github provides a GitHub API client for fetching releases and assets. |
|
component/lockfile
Package lockfile provides lockfile parsing, serialization, and management.
|
Package lockfile provides lockfile parsing, serialization, and management. |
|
component/semver
Package semver provides semantic version parsing and constraint matching.
|
Package semver provides semantic version parsing and constraint matching. |
|
component/sigstore
Package sigstore provides Sigstore signature verification for epack components.
|
Package sigstore provides Sigstore signature verification for epack components. |
|
component/sync
Package sync provides component synchronization and locking operations.
|
Package sync provides component synchronization and locking operations. |
|
componentsdk
Package componentsdk provides tools for component SDK authors.
|
Package componentsdk provides tools for component SDK authors. |
|
componenttypes
Package componenttypes defines shared types for component management.
|
Package componenttypes defines shared types for component management. |
|
conformance
Package conformance implements test vector runners for Evidence Pack spec conformance testing.
|
Package conformance implements test vector runners for Evidence Pack spec conformance testing. |
|
detach
Package detach provides background process management for CLI operations.
|
Package detach provides background process management for CLI operations. |
|
digest
Package digest provides a type-safe SHA256 digest implementation.
|
Package digest provides a type-safe SHA256 digest implementation. |
|
dispatch
Package dispatch implements TOCTOU-safe tool execution with verification.
|
Package dispatch implements TOCTOU-safe tool execution with verification. |
|
execsafe
Package execsafe provides TOCTOU-safe binary execution primitives.
|
Package execsafe provides TOCTOU-safe binary execution primitives. |
|
exitcode
Package exitcode defines unified exit codes for epack CLI operations.
|
Package exitcode defines unified exit codes for epack CLI operations. |
|
intoto
Package intoto defines in-toto statement types for evidence pack attestations.
|
Package intoto defines in-toto statement types for evidence pack attestations. |
|
jcsutil
Package jcsutil provides JSON Canonicalization Scheme (JCS) per RFC 8785.
|
Package jcsutil provides JSON Canonicalization Scheme (JCS) per RFC 8785. |
|
jobs
Package jobs provides background job tracking for CLI operations.
|
Package jobs provides background job tracking for CLI operations. |
|
jsonutil
Package jsonutil provides hardened JSON decoding helpers for untrusted input.
|
Package jsonutil provides hardened JSON decoding helpers for untrusted input. |
|
limits
Package limits provides helper functions for enforcing resource limits.
|
Package limits provides helper functions for enforcing resource limits. |
|
netpolicy
Package netpolicy provides URL and host validation for network requests.
|
Package netpolicy provides URL and host validation for network requests. |
|
packpath
Package packpath defines path constants and validation for evidence packs.
|
Package packpath defines path constants and validation for evidence packs. |
|
platform
Package platform provides platform identification utilities.
|
Package platform provides platform identification utilities. |
|
platformpath
Package platformpath provides OS-specific path safety helpers.
|
Package platformpath provides OS-specific path safety helpers. |
|
progress
Package progress provides progress tracking for I/O operations.
|
Package progress provides progress tracking for I/O operations. |
|
project
Package project provides utilities for finding and working with epack project roots.
|
Package project provides utilities for finding and working with epack project roots. |
|
push
Package push implements the push workflow for uploading packs to remote registries.
|
Package push implements the push workflow for uploading packs to remote registries. |
|
redact
Package redact provides structured redaction for output in CI environments.
|
Package redact provides structured redaction for output in CI environments. |
|
remote
Package remote implements the Remote Adapter Protocol for epack push/pull operations.
|
Package remote implements the Remote Adapter Protocol for epack push/pull operations. |
|
safefile
Package safefile provides secure filesystem operations with symlink protection.
|
Package safefile provides secure filesystem operations with symlink protection. |
|
safejson
Package safejson provides secure JSON parsing with mandatory size validation.
|
Package safejson provides secure JSON parsing with mandatory size validation. |
|
safeyaml
Package safeyaml provides secure YAML parsing with mandatory pre-validation.
|
Package safeyaml provides secure YAML parsing with mandatory pre-validation. |
|
security
Package security provides security policy types and enforcement for epack operations.
|
Package security provides security policy types and enforcement for epack operations. |
|
testutil/importguard
Package importguard provides test helpers for enforcing import boundaries.
|
Package importguard provides test helpers for enforcing import boundaries. |
|
timestamp
Package timestamp provides a type-safe timestamp implementation for evidence packs.
|
Package timestamp provides a type-safe timestamp implementation for evidence packs. |
|
toolcap
Package toolcap provides capability probing for epack tools.
|
Package toolcap provides capability probing for epack tools. |
|
toolprotocol
Package toolprotocol implements the epack Tool Protocol v1.
|
Package toolprotocol implements the epack Tool Protocol v1. |
|
userconfig
Package userconfig manages user-level epack configuration and utilities.
|
Package userconfig manages user-level epack configuration and utilities. |
|
validate
Package validate provides centralized security validation functions.
|
Package validate provides centralized security validation functions. |
|
verify
Package verify provides verification workflows for evidence packs.
|
Package verify provides verification workflows for evidence packs. |
|
version
Package version provides shared version information for epack.
|
Package version provides shared version information for epack. |
|
yamlpolicy
Package yamlpolicy provides security-focused YAML parsing primitives.
|
Package yamlpolicy provides security-focused YAML parsing primitives. |
|
yamlutil
Package yamlutil provides utilities for deterministic YAML serialization.
|
Package yamlutil provides utilities for deterministic YAML serialization. |
|
ziputil
Package ziputil validates and safely reads ZIP archives used by evidence packs.
|
Package ziputil validates and safely reads ZIP archives used by evidence packs. |
|
Package pack provides APIs to open, validate, and read evidence packs.
|
Package pack provides APIs to open, validate, and read evidence packs. |
|
builder
Package builder creates evidence packs.
|
Package builder creates evidence packs. |
|
diff
Package diff provides comparison utilities for evidence packs.
|
Package diff provides comparison utilities for evidence packs. |
|
merge
Package merge combines multiple evidence packs into a single merged pack.
|
Package merge combines multiple evidence packs into a single merged pack. |
|
verify
Package verify validates Sigstore attestations in evidence packs.
|
Package verify validates Sigstore attestations in evidence packs. |
|
Package packspec defines the canonical types for evidence pack manifests.
|
Package packspec defines the canonical types for evidence pack manifests. |
|
Package sign creates Sigstore attestations for evidence packs.
|
Package sign creates Sigstore attestations for evidence packs. |
|
sigstore
Package sigstore provides Sigstore-based signing for evidence packs.
|
Package sigstore provides Sigstore-based signing for evidence packs. |
|
testsupport
Package testsupport provides test-only helpers for the sign package.
|
Package testsupport provides test-only helpers for the sign package. |
Click to show internal directories.
Click to hide internal directories.