docker-slsa

Verify SLSA provenance attestations for Docker container images using Sigstore.

This library verifies container images built with the SLSA GitHub Generator for containers (generator_container_slsa3.yml).

Features

• Verify SLSA provenance for individual container images
• Batch verification for all images in a docker-compose file
• Built-in support for GitHub Actions SLSA container generator workflow
• Custom verification policies using sigstore's policy API

Installation

pip install docker-slsa

Quick Start

Verify a single container image

from docker_slsa import ContainerSLSAVerifier, build_default_policy

# Create a policy for GitHub Actions SLSA provenance
policy = build_default_policy(
    expected_repo="org/repo",
    expected_commit="abc123def456",  # optional
)

# Verify the image
verifier = ContainerSLSAVerifier()
result = verifier.verify(
    image_ref="ghcr.io/org/repo/image@sha256:...",
    policy=policy,
)

if result.verified:
    print("Verification passed!")
    print(f"Provenance: {result.provenance}")
else:
    print(f"Verification failed: {result.error}")

Verify all images in a docker-compose file

from docker_slsa import verify_docker_compose_provenance, build_default_policy

# Read your docker-compose file
with open("docker-compose.yml") as f:
    docker_compose = f.read()

# Define policies for each service
service_policies = {
    "web": build_default_policy("org/web-app"),
    "api": build_default_policy("org/api-server"),
}

# Verify all services (raises ProvenanceVerificationError on failure)
result = verify_docker_compose_provenance(
    docker_compose=docker_compose,
    service_policies=service_policies,
    ignore=["redis", "postgres"],  # skip third-party images
)

print(f"All {len(result.service_results)} services verified!")

Custom verification policies

For advanced use cases, create custom policies using sigstore's policy API:

from sigstore.verify.policy import AllOf, AnyOf, OIDCIssuer, GitHubWorkflowRepository, Identity

policy = AllOf([
    OIDCIssuer("https://token.actions.githubusercontent.com"),
    GitHubWorkflowRepository("org/repo"),
    AnyOf([
        Identity(
            identity="https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v2.0.0",
            issuer="https://token.actions.githubusercontent.com",
        ),
        Identity(
            identity="https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/v2.1.0",
            issuer="https://token.actions.githubusercontent.com",
        ),
    ]),
])

API Reference

Classes

• ContainerSLSAVerifier - Low-level verifier for individual container images
• DockerComposeProvenanceVerifier - Verifies all images in a docker-compose file

Functions

• build_default_policy(expected_repo, expected_commit=None, expected_workflow_name=None) - Create a verification policy for GitHub Actions SLSA workflows
• verify_docker_compose_provenance(docker_compose, service_policies, ignore=None) - Convenience function to verify a docker-compose file

Result Types

• VerificationResult - Result for a single image verification
• ServiceVerificationResult - Result for a single service in docker-compose
• ProvenanceVerificationResult - Aggregate result for all services

Exceptions

• ProvenanceVerificationError - Raised when verification fails

Requirements

• Python 3.10+
• Network access to container registries and Sigstore services
• Container images must have SLSA provenance attestations generated by the SLSA GitHub Generator generator_container_slsa3.yml workflow

Development

# Install dependencies
uv sync --group dev --group test

# Run tests
make test

# Run tests with coverage (95% required)
make test-coverage

# Format code
make format

# Lint code
make lint

# Run all QA checks
make qa-all

License

MIT