docker-slsa 0.1.0
Verify SLSA provenance attestations for Docker container images
Requires Python: >=3.10
Keywords: slsa, provenance, sigstore, docker, container, docker-compose, attestation, supply-chain, security

# docker-slsa

Verify [SLSA](https://slsa.dev/) provenance attestations for Docker container images using [Sigstore](https://www.sigstore.dev/).

This library verifies container images built with the [SLSA GitHub Generator for containers](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/container) (`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](https://github.com/slsa-framework/slsa-github-generator/blob/main/.github/workflows/generator_container_slsa3.yml) workflow
- Custom verification policies using sigstore's policy API

## Installation

```bash
pip install docker-slsa
```

## Quick Start

### Verify a single container image

```python
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

```python
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:

```python
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](https://github.com/slsa-framework/slsa-github-generator) `generator_container_slsa3.yml` workflow

## Development

```bash
# 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