Skip to content

README.md

Latest commit

 

History

History
125 lines (92 loc) · 3.86 KB

README.md

File metadata and controls

125 lines (92 loc) · 3.86 KB
Raw

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

Field Type Description
registry str e.g. "ghcr.io", "docker.io"
namespace str e.g. "myorg", "library"
name str e.g. "traefik", "postgres"
tag str e.g. "v3.6.0", "latest"
raw str original image string from docker-compose

ImageResult

Field Type Description
service str service name from docker-compose
image str original image string
registry str image registry
repo str | None GitHub repository URL
tag str image tag
commit str | None resolved commit SHA
commit_url str | None URL to the commit on GitHub
status str "resolved", "repo_not_found", "repo_found_tag_not_matched", or "no_tag"
resolution_method str | None how the commit was resolved (e.g. "oci_labels", "tag_match")
confidence str | None "exact" or "approximate"
steps list[str] resolution steps taken (useful with --verbose)

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