code-provenance

Resolve Docker images in a docker-compose file to their exact source code commits on GitHub.

Installation

pip install code-provenance

Requires Python 3.10+.

CLI Usage

code-provenance [machine-url] [--workload FILE] [--image IMAGE] [--json] [--verbose]

• machine-url -- SecretVM machine URL or hostname (e.g. secretai-jedi.scrtlabs.com); the docker-compose is fetched from it over port 29343, falling back to 21434 for GPU machines
• --workload FILE -- resolve a local docker-compose file instead of a machine URL
• --image IMAGE -- resolve a single image reference
• --secretvm URL -- SecretVM machine URL (same as passing it positionally; kept for backward compatibility)
• --json -- output results as JSON
• --verbose, -v -- show resolution steps for each image

Examples

Resolve all images running on a SecretVM machine (default mode):

code-provenance secretai-jedi.scrtlabs.com

Resolve all images in a local docker-compose file:

code-provenance --workload docker-compose.yml

web: traefik:v3.6.0
  repo:       github.com/traefik/traefik
  commit:     06db5168c0d9
  status:     resolved
  confidence: exact
  url:        https://github.com/traefik/traefik/commit/06db5168c0d9...

Resolve a single image:

code-provenance --image ollama/ollama:0.12.3

image: ollama/ollama:0.12.3
  repo:       github.com/ollama/ollama
  commit:     b04e46da3ebc
  status:     resolved
  confidence: exact
  url:        https://github.com/ollama/ollama/commit/b04e46da3ebc...

Library Usage

from code_provenance.compose_parser import parse_compose, parse_image_ref
from code_provenance.resolver import resolve_image

yaml_content = open("docker-compose.yml").read()
for service, image in parse_compose(yaml_content):
    ref = parse_image_ref(image)
    result = resolve_image(service, ref)
    print(f"{result.service}: {result.commit} ({result.confidence})")

API Reference

Functions

• parse_compose(yaml_content: str) -> list[tuple[str, str]] -- parse a docker-compose YAML string and return (service_name, image_string) pairs
• parse_image_ref(image: str) -> ImageRef -- parse a Docker image string into its components
• resolve_image(service: str, ref: ImageRef) -> ImageResult -- resolve an image reference to its source code commit

ImageRef

ImageResult

Authentication

Set GITHUB_TOKEN for full functionality (digest resolution, :latest on GHCR, higher rate limits):

export GITHUB_TOKEN=ghp_your_token_here

Create a classic token at https://github.com/settings/tokens with read:packages scope. If using the gh CLI, run gh auth refresh -h github.com -s read:packages first.

The run.sh wrapper auto-detects the token from gh CLI if available.

License

MIT