code-provenance 0.1.0__py3-none-any.whl

code_provenance/__init__.py

@@ -0,0 +1 @@
+from code_provenance.models import ImageRef, ImageResult

code_provenance/cli.py

@@ -0,0 +1,69 @@
+import argparse
+import sys
+from pathlib import Path
+from code_provenance.compose_parser import parse_compose, parse_image_ref
+from code_provenance.resolver import resolve_image
+from code_provenance.output import format_json, format_table
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="code-provenance",
+        description="Resolve Docker images to their source code commits on GitHub.",
+    )
+    parser.add_argument(
+        "compose_file",
+        nargs="?",
+        default="docker-compose.yml",
+        help="Path to docker-compose file (default: docker-compose.yml)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Output results as JSON",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Show resolution steps",
+    )
+
+    args = parser.parse_args(argv)
+
+    compose_path = Path(args.compose_file)
+    if not compose_path.exists():
+        print(f"Error: {compose_path} not found", file=sys.stderr)
+        return 1
+
+    yaml_content = compose_path.read_text()
+    services = parse_compose(yaml_content)
+
+    if not services:
+        print("No services with images found.", file=sys.stderr)
+        return 0
+
+    results = []
+    for service_name, image_string in services:
+        ref = parse_image_ref(image_string)
+        result = resolve_image(service_name, ref)
+        results.append(result)
+
+    if args.verbose:
+        for result in results:
+            print(f"\nResolving {result.image} ...", file=sys.stderr)
+            for step in result.steps:
+                print(f"  {step}", file=sys.stderr)
+            print(f"  → {result.status}" + (f" ({result.resolution_method}, {result.confidence})" if result.status == "resolved" else ""), file=sys.stderr)
+        print(file=sys.stderr)
+
+    if args.json_output:
+        print(format_json(results))
+    else:
+        print(format_table(results))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

code_provenance/compose_parser.py

@@ -0,0 +1,58 @@
+import yaml
+from code_provenance.models import ImageRef
+
+
+def parse_image_ref(image_string: str) -> ImageRef:
+    """Parse a Docker image string into an ImageRef."""
+    raw = image_string
+
+    # Handle digest references (image@sha256:...)
+    if "@" in image_string:
+        name_part, digest = image_string.split("@", 1)
+        tag = digest
+        image_string = name_part
+    elif ":" in image_string.split("/")[-1]:
+        colon_pos = image_string.rfind(":")
+        tag = image_string[colon_pos + 1:]
+        image_string = image_string[:colon_pos]
+    else:
+        tag = "latest"
+
+    # Determine registry
+    parts = image_string.split("/")
+    if len(parts) >= 2 and ("." in parts[0] or ":" in parts[0]):
+        registry = parts[0]
+        remaining = parts[1:]
+    else:
+        registry = "docker.io"
+        remaining = parts
+
+    # Determine namespace and name
+    if len(remaining) == 1:
+        namespace = "library"
+        name = remaining[0]
+    elif len(remaining) == 2:
+        namespace = remaining[0]
+        name = remaining[1]
+    else:
+        namespace = remaining[0]
+        name = "/".join(remaining[1:])
+
+    return ImageRef(
+        registry=registry,
+        namespace=namespace,
+        name=name,
+        tag=tag,
+        raw=raw,
+    )
+
+
+def parse_compose(yaml_content: str) -> list[tuple[str, str]]:
+    """Parse docker-compose YAML and return list of (service_name, image_string)."""
+    data = yaml.safe_load(yaml_content)
+    services = data.get("services", {}) or {}
+    results = []
+    for service_name, service_config in services.items():
+        if isinstance(service_config, dict) and "image" in service_config:
+            results.append((service_name, service_config["image"]))
+    return results

code_provenance/github.py

@@ -0,0 +1,250 @@
+import os
+import re
+import requests
+
+
+def github_headers() -> dict[str, str]:
+    """Build GitHub API headers, with optional token auth."""
+    headers = {"Accept": "application/vnd.github+json"}
+    token = os.environ.get("GITHUB_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _normalize_tag(tag: str) -> str:
+    """Strip leading 'v' for comparison."""
+    return tag.lstrip("v")
+
+
+def _is_prefix_match(image_tag: str, git_tag: str) -> bool:
+    """Check if git_tag is a more specific version of image_tag.
+
+    e.g., image_tag='v2.10' matches git_tag='v2.10.7' but not 'v2.1' or 'v2.100'.
+    """
+    norm_image = _normalize_tag(image_tag)
+    norm_git = _normalize_tag(git_tag)
+    return norm_git.startswith(norm_image + ".")
+
+
+def _parse_version_tuple(tag: str) -> tuple[int, ...] | None:
+    """Parse a version string into a tuple of ints for comparison."""
+    norm = _normalize_tag(tag)
+    # Strip pre-release suffixes like -rc1, -beta2
+    norm = re.split(r"[-+]", norm)[0]
+    parts = norm.split(".")
+    try:
+        return tuple(int(p) for p in parts)
+    except ValueError:
+        return None
+
+
+def resolve_tag_to_commit(owner: str, repo: str, tag: str) -> tuple[str, bool] | None:
+    """Resolve an image tag to a commit SHA by matching against git tags.
+
+    Tries exact match first, then prefix match (e.g., v2.10 -> highest v2.10.x).
+    Returns (commit_sha, is_exact_match) or None.
+    """
+    headers = github_headers()
+    url = f"https://api.github.com/repos/{owner}/{repo}/tags"
+
+    prefix_candidates: list[tuple[tuple[int, ...], str]] = []
+
+    while url:
+        resp = requests.get(url, headers=headers, params={"per_page": 100}, timeout=10)
+        if resp.status_code != 200:
+            return None
+
+        for git_tag in resp.json():
+            name = git_tag["name"]
+            # Exact match (with/without v prefix)
+            if name == tag or name == f"v{tag}" or _normalize_tag(name) == _normalize_tag(tag):
+                return git_tag["commit"]["sha"], True
+
+            # Collect prefix match candidates
+            if _is_prefix_match(tag, name):
+                version = _parse_version_tuple(name)
+                if version is not None:
+                    prefix_candidates.append((version, git_tag["commit"]["sha"]))
+
+        url = resp.links.get("next", {}).get("url")
+
+    # Return the highest version among prefix matches
+    if prefix_candidates:
+        prefix_candidates.sort(reverse=True)
+        return prefix_candidates[0][1], False
+
+    return None
+
+
+def get_latest_release_commit(owner: str, repo: str) -> tuple[str, str] | None:
+    """Get the commit SHA of the latest GitHub release.
+
+    Returns (commit_sha, tag_name) or None.
+    """
+    headers = github_headers()
+    try:
+        resp = requests.get(
+            f"https://api.github.com/repos/{owner}/{repo}/releases/latest",
+            headers=headers,
+            timeout=10,
+        )
+        if resp.status_code != 200:
+            return None
+        tag_name = resp.json().get("tag_name")
+        if not tag_name:
+            return None
+    except requests.RequestException:
+        return None
+
+    # Resolve the release tag to a commit
+    tag_result = resolve_tag_to_commit(owner, repo, tag_name)
+    if tag_result:
+        commit_sha, _ = tag_result
+        return commit_sha, tag_name
+    return None
+
+
+def get_latest_commit(owner: str, repo: str) -> str | None:
+    """Get the latest commit SHA on the default branch."""
+    headers = github_headers()
+    try:
+        resp = requests.get(
+            f"https://api.github.com/repos/{owner}/{repo}/commits",
+            headers=headers,
+            params={"per_page": 1},
+            timeout=10,
+        )
+        if resp.status_code != 200:
+            return None
+        commits = resp.json()
+        if commits:
+            return commits[0]["sha"]
+    except (requests.RequestException, KeyError, IndexError):
+        pass
+    return None
+
+
+def check_github_repo_exists(owner: str, repo: str) -> bool:
+    """Check if a GitHub repo exists."""
+    headers = github_headers()
+    try:
+        resp = requests.get(
+            f"https://api.github.com/repos/{owner}/{repo}",
+            headers=headers,
+            timeout=10,
+        )
+        return resp.status_code == 200
+    except requests.RequestException:
+        return False
+
+
+def _find_ghcr_package_version(
+    owner: str, package_name: str, *, match_digest: str | None = None, match_tag: str | None = None,
+) -> dict | None:
+    """Find a GHCR package version by digest or tag via the GitHub Packages API.
+
+    Requires GITHUB_TOKEN with read:packages scope.
+    Returns {"repo": "owner/repo", "commit": "sha", "tags": [...]} or None.
+    """
+    headers = github_headers()
+    if "Authorization" not in headers:
+        return None
+
+    for entity_type in ["orgs", "users"]:
+        pkg_base = f"https://api.github.com/{entity_type}/{owner}/packages/container/{package_name}"
+
+        # Get package metadata for source repo
+        try:
+            pkg_resp = requests.get(pkg_base, headers=headers, timeout=10)
+            if pkg_resp.status_code == 403:
+                return None
+            if pkg_resp.status_code != 200:
+                continue
+            pkg_data = pkg_resp.json()
+        except requests.RequestException:
+            continue
+
+        repo_info = pkg_data.get("repository", {})
+        full_name = repo_info.get("full_name")
+        if not full_name:
+            continue
+
+        # Search versions
+        url = f"{pkg_base}/versions"
+        try:
+            while url:
+                resp = requests.get(url, headers=headers, params={"per_page": 50}, timeout=10)
+                if resp.status_code != 200:
+                    break
+
+                for version in resp.json():
+                    name = version.get("name", "")
+                    metadata = version.get("metadata", {}).get("container", {})
+                    tags = metadata.get("tags", [])
+
+                    # Match by digest (version name is the digest)
+                    if match_digest and name != match_digest:
+                        if match_tag is None:
+                            continue
+                    # Match by tag
+                    if match_tag and match_tag not in tags:
+                        continue
+
+                    # Found matching version — resolve tags to a commit
+                    repo_owner, repo_name = full_name.split("/", 1)
+                    resolvable_tags = [t for t in tags if t != "latest"]
+                    for tag in resolvable_tags:
+                        tag_result = resolve_tag_to_commit(repo_owner, repo_name, tag)
+                        if tag_result:
+                            commit_sha, _ = tag_result
+                            return {"repo": full_name, "commit": commit_sha, "tags": tags}
+
+                    return {"repo": full_name, "commit": None, "tags": tags}
+
+                url = resp.links.get("next", {}).get("url")
+        except requests.RequestException:
+            continue
+
+    return None
+
+
+def resolve_ghcr_digest_via_packages(owner: str, package_name: str, digest: str) -> dict | None:
+    """Find the commit for a GHCR image by its digest."""
+    return _find_ghcr_package_version(owner, package_name, match_digest=digest)
+
+
+def resolve_ghcr_latest_via_packages(owner: str, package_name: str) -> dict | None:
+    """Find the commit for a GHCR image's :latest tag."""
+    return _find_ghcr_package_version(owner, package_name, match_tag="latest")
+
+
+def infer_repo_from_dockerhub(namespace: str, name: str) -> tuple[str, str] | None:
+    """Try to find the GitHub repo for a Docker Hub image."""
+    # For official images (library/X), try the image name as org/repo directly
+    # e.g., traefik -> traefik/traefik, nginx -> nginx/nginx
+    if namespace == "library":
+        if check_github_repo_exists(name, name):
+            return name, name
+
+    # For namespaced images, try namespace/name on GitHub
+    if namespace != "library":
+        if check_github_repo_exists(namespace, name):
+            return namespace, name
+
+    # Fall back to scraping Docker Hub description for GitHub links
+    url = f"https://hub.docker.com/v2/repositories/{namespace}/{name}"
+    try:
+        resp = requests.get(url, timeout=10)
+        if resp.status_code != 200:
+            return None
+
+        data = resp.json()
+        text = (data.get("full_description") or "") + " " + (data.get("description") or "")
+        match = re.search(r"https?://github\.com/([\w.-]+)/([\w.-]+)", text)
+        if match:
+            return match.group(1), match.group(2)
+    except requests.RequestException:
+        pass
+
+    return None

code_provenance/models.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ImageRef:
+    """A parsed Docker image reference."""
+    registry: str          # e.g. "ghcr.io", "docker.io"
+    namespace: str         # e.g. "myorg", "library"
+    name: str              # e.g. "excalidraw", "postgres"
+    tag: str               # e.g. "v3.4.12", "latest"
+    raw: str               # original string from docker-compose
+
+    @property
+    def full_name(self) -> str:
+        """Registry/namespace/name without tag."""
+        return f"{self.registry}/{self.namespace}/{self.name}"
+
+
+@dataclass
+class ImageResult:
+    """Resolution result for a single image."""
+    service: str
+    image: str             # original image string
+    registry: str
+    repo: str | None = None
+    tag: str = ""
+    commit: str | None = None
+    commit_url: str | None = None
+    status: str = "repo_not_found"
+    resolution_method: str | None = None
+    confidence: str | None = None  # "exact", "approximate", or None if unresolved
+    steps: list[str] = field(default_factory=list)

code_provenance/output.py

@@ -0,0 +1,33 @@
+import json
+from dataclasses import asdict
+from io import StringIO
+from rich.console import Console
+from rich.table import Table
+from code_provenance.models import ImageResult
+
+
+def format_json(results: list[ImageResult]) -> str:
+    """Format results as a JSON array."""
+    return json.dumps([asdict(r) for r in results], indent=2)
+
+
+def format_table(results: list[ImageResult]) -> str:
+    """Format results as a rich table, returned as a string."""
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("SERVICE")
+    table.add_column("IMAGE")
+    table.add_column("REPO")
+    table.add_column("COMMIT")
+    table.add_column("STATUS")
+    table.add_column("CONFIDENCE")
+
+    for r in results:
+        commit_display = r.commit[:12] if r.commit else "-"
+        repo_display = r.repo.replace("https://", "") if r.repo else "-"
+        confidence_display = r.confidence or "-"
+        table.add_row(r.service, r.image, repo_display, commit_display, r.status, confidence_display)
+
+    buf = StringIO()
+    console = Console(file=buf, force_terminal=False, width=160)
+    console.print(table)
+    return buf.getvalue()

code_provenance/registry.py

@@ -0,0 +1,121 @@
+import requests
+from code_provenance.models import ImageRef
+
+
+def get_registry_token(registry: str, repo_path: str) -> str | None:
+    """Get an anonymous pull token from an OCI registry."""
+    if registry == "ghcr.io":
+        url = "https://ghcr.io/token"
+        params = {"scope": f"repository:{repo_path}:pull"}
+    elif registry == "docker.io":
+        url = "https://auth.docker.io/token"
+        params = {
+            "service": "registry.docker.io",
+            "scope": f"repository:{repo_path}:pull",
+        }
+    else:
+        return None
+
+    try:
+        resp = requests.get(url, params=params, timeout=10)
+        resp.raise_for_status()
+        return resp.json()["token"]
+    except (requests.RequestException, KeyError):
+        return None
+
+
+def _registry_base_url(registry: str) -> str:
+    if registry == "docker.io":
+        return "https://registry-1.docker.io"
+    return f"https://{registry}"
+
+
+_MANIFEST_ACCEPT = ", ".join([
+    "application/vnd.docker.distribution.manifest.v2+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.index.v1+json",
+])
+
+_INDEX_MEDIA_TYPES = {
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.index.v1+json",
+}
+
+
+def _resolve_manifest_to_config_digest(
+    base_url: str, repo_path: str, reference: str, token: str,
+) -> str | None:
+    """Resolve a manifest reference to a config blob digest, handling multi-arch indexes."""
+    headers = {"Authorization": f"Bearer {token}", "Accept": _MANIFEST_ACCEPT}
+
+    try:
+        resp = requests.get(
+            f"{base_url}/v2/{repo_path}/manifests/{reference}",
+            headers=headers,
+            timeout=10,
+        )
+        if resp.status_code != 200:
+            return None
+        data = resp.json()
+    except (requests.RequestException, KeyError, ValueError):
+        return None
+
+    media_type = data.get("mediaType", "")
+
+    # If it's an index/manifest list, pick the first amd64/linux manifest
+    if media_type in _INDEX_MEDIA_TYPES:
+        manifests = data.get("manifests", [])
+        platform_digest = None
+        for m in manifests:
+            platform = m.get("platform", {})
+            # Skip attestation manifests
+            if platform.get("os") == "unknown":
+                continue
+            if platform.get("architecture") == "amd64" and platform.get("os") == "linux":
+                platform_digest = m["digest"]
+                break
+        if not platform_digest and manifests:
+            # Fall back to first non-attestation manifest
+            for m in manifests:
+                if m.get("platform", {}).get("os") != "unknown":
+                    platform_digest = m["digest"]
+                    break
+        if not platform_digest:
+            return None
+        # Recursively resolve the platform-specific manifest
+        return _resolve_manifest_to_config_digest(base_url, repo_path, platform_digest, token)
+
+    # Single manifest — extract config digest
+    return data.get("config", {}).get("digest")
+
+
+def fetch_oci_labels(ref: ImageRef) -> dict[str, str]:
+    """Fetch OCI labels from an image's config blob without pulling the image."""
+    repo_path = f"{ref.namespace}/{ref.name}"
+    token = get_registry_token(ref.registry, repo_path)
+    if not token:
+        return {}
+
+    base_url = _registry_base_url(ref.registry)
+    config_digest = _resolve_manifest_to_config_digest(base_url, repo_path, ref.tag, token)
+    if not config_digest:
+        return {}
+
+    # Fetch config blob to read labels
+    try:
+        config_headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.docker.container.image.v1+json",
+        }
+        config_resp = requests.get(
+            f"{base_url}/v2/{repo_path}/blobs/{config_digest}",
+            headers=config_headers,
+            timeout=10,
+            allow_redirects=True,
+        )
+        if config_resp.status_code != 200:
+            return {}
+        return config_resp.json().get("config", {}).get("Labels", {}) or {}
+    except (requests.RequestException, KeyError):
+        return {}

code_provenance/resolver.py

@@ -0,0 +1,160 @@
+import re
+from code_provenance.models import ImageRef, ImageResult
+from code_provenance.registry import fetch_oci_labels
+from code_provenance.github import (
+    resolve_tag_to_commit, infer_repo_from_dockerhub,
+    resolve_ghcr_digest_via_packages, resolve_ghcr_latest_via_packages,
+    get_latest_release_commit, get_latest_commit,
+)
+
+_COMMIT_SHA_RE = re.compile(r"^[0-9a-f]{40,}$")
+_DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _is_resolvable_tag(tag: str) -> bool:
+    """Check if a tag can be matched against git tags."""
+    return bool(tag) and tag != "latest" and not _DIGEST_RE.match(tag)
+
+
+def resolve_image(service: str, ref: ImageRef) -> ImageResult:
+    """Run the resolution chain for a single image."""
+    result = ImageResult(
+        service=service,
+        image=ref.raw,
+        registry=ref.registry,
+        tag=ref.tag,
+    )
+
+    # Step 1: Check OCI labels
+    result.steps.append(f"[1/5] Fetching OCI labels from {ref.registry}/{ref.namespace}/{ref.name}:{ref.tag}")
+    labels = fetch_oci_labels(ref)
+    source = labels.get("org.opencontainers.image.source")
+    revision = labels.get("org.opencontainers.image.revision")
+    if source and revision:
+        result.steps.append(f"[1/5] Found OCI labels: source={source}, revision={revision[:12]}")
+        result.repo = source
+        result.commit = revision
+        result.commit_url = f"{source}/commit/{revision}"
+        result.status = "resolved"
+        result.resolution_method = "oci_labels"
+        result.confidence = "approximate" if ref.tag == "latest" else "exact"
+        return result
+    else:
+        result.steps.append("[1/5] No OCI labels found")
+
+    # Step 2: Infer repo
+    result.steps.append(f"[2/5] Inferring GitHub repo from {ref.registry}/{ref.namespace}/{ref.name}")
+    owner, repo_name = _infer_repo(ref)
+    if owner and repo_name:
+        result.steps.append(f"[2/5] Repo inferred: {owner}/{repo_name}")
+        result.repo = f"https://github.com/{owner}/{repo_name}"
+    else:
+        result.steps.append("[2/5] Could not infer GitHub repo")
+        result.status = "repo_not_found"
+        return result
+
+    # Check if tag is a commit SHA
+    if _COMMIT_SHA_RE.match(ref.tag):
+        result.steps.append("[2/5] Tag is a commit SHA, using directly")
+        result.commit = ref.tag
+        result.commit_url = f"{result.repo}/commit/{ref.tag}"
+        result.status = "resolved"
+        result.resolution_method = "commit_sha_tag"
+        result.confidence = "exact"
+        return result
+
+    # Step 3: Tag-to-commit resolution
+    if _is_resolvable_tag(ref.tag):
+        result.steps.append(f'[3/5] Matching tag "{ref.tag}" against git tags in {owner}/{repo_name}')
+        tag_result = resolve_tag_to_commit(owner, repo_name, ref.tag)
+        if tag_result:
+            commit_sha, is_exact = tag_result
+            if is_exact:
+                result.steps.append(f"[3/5] Exact tag match: {commit_sha[:12]}")
+            else:
+                result.steps.append(f"[3/5] Prefix match (e.g. v2.10 -> v2.10.x): {commit_sha[:12]}")
+            result.commit = commit_sha
+            result.commit_url = f"{result.repo}/commit/{commit_sha}"
+            result.status = "resolved"
+            result.resolution_method = "tag_match"
+            result.confidence = "exact" if is_exact else "approximate"
+            return result
+        result.steps.append("[3/5] No matching git tag found")
+        result.status = "repo_found_tag_not_matched"
+        return result
+
+    # Step 4: For GHCR images, try the packages API for digest or :latest
+    if ref.registry == "ghcr.io":
+        if _DIGEST_RE.match(ref.tag):
+            result.steps.append(f"[4/5] Trying GHCR packages API for digest {ref.tag[:20]}...")
+            pkg_result = resolve_ghcr_digest_via_packages(ref.namespace, ref.name, ref.tag)
+            pkg_confidence = "exact"  # digest is immutable
+        elif ref.tag == "latest" or not ref.tag:
+            result.steps.append("[4/5] Trying GHCR packages API for :latest tag")
+            pkg_result = resolve_ghcr_latest_via_packages(ref.namespace, ref.name)
+            pkg_confidence = "approximate"  # :latest is mutable
+        else:
+            pkg_result = None
+            pkg_confidence = None
+
+        if pkg_result:
+            repo_full = pkg_result["repo"]
+            result.repo = f"https://github.com/{repo_full}"
+            if pkg_result.get("commit"):
+                commit = pkg_result["commit"]
+                result.steps.append(f"[4/5] Packages API: repo={repo_full}, commit={commit[:12]}")
+                result.commit = commit
+                result.commit_url = f"{result.repo}/commit/{result.commit}"
+                result.status = "resolved"
+                result.resolution_method = "packages_api"
+                result.confidence = pkg_confidence
+                return result
+            result.steps.append("[4/5] Packages API: found package but no resolvable tags")
+            tags = pkg_result.get("tags", [])
+            resolvable = [t for t in tags if t != "latest"]
+            result.status = "repo_found_tag_not_matched" if resolvable else "no_tag"
+            return result
+
+    # Step 5: For :latest on any registry, try the latest GitHub release,
+    # then fall back to the latest commit on the default branch
+    if (ref.tag == "latest" or not ref.tag) and owner and repo_name:
+        result.steps.append(f"[5/5] Trying latest GitHub release for {owner}/{repo_name}")
+        release_result = get_latest_release_commit(owner, repo_name)
+        if release_result:
+            commit_sha, tag_name = release_result
+            result.steps.append(f"[5/5] Latest release: tag={tag_name}, commit={commit_sha[:12]}")
+            result.commit = commit_sha
+            result.commit_url = f"{result.repo}/commit/{commit_sha}"
+            result.status = "resolved"
+            result.resolution_method = "latest_release"
+            result.confidence = "approximate"
+            return result
+
+        # No releases — fall back to latest commit on default branch
+        result.steps.append("[5/5] No release found, trying latest commit on default branch")
+        latest_sha = get_latest_commit(owner, repo_name)
+        if latest_sha:
+            result.steps.append(f"[5/5] Latest commit: {latest_sha[:12]}")
+            result.commit = latest_sha
+            result.commit_url = f"{result.repo}/commit/{latest_sha}"
+            result.status = "resolved"
+            result.resolution_method = "latest_commit"
+            result.confidence = "approximate"
+            return result
+
+    result.steps.append("[5/5] Could not resolve to a commit")
+    result.status = "no_tag"
+    return result
+
+
+def _infer_repo(ref: ImageRef) -> tuple[str | None, str | None]:
+    """Infer the GitHub owner and repo name from an image reference."""
+    if ref.registry == "ghcr.io":
+        return ref.namespace, ref.name
+
+    if ref.registry == "docker.io":
+        hub_result = infer_repo_from_dockerhub(ref.namespace, ref.name)
+        if hub_result:
+            return hub_result
+
+    return None, None

code_provenance-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: code-provenance
+Version: 0.1.0
+Summary: Resolve Docker images to their source code commits on GitHub
+Author: SCRT Labs
+License: MIT
+Project-URL: Homepage, https://github.com/scrtlabs/code-provenance
+Project-URL: Repository, https://github.com/scrtlabs/code-provenance
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# code-provenance
+
+Resolve Docker images in a docker-compose file to their exact source code commits on GitHub.
+
+## Installation
+
+```bash
+pip install code-provenance
+```
+
+Requires Python 3.10+.
+
+## CLI Usage
+
+```bash
+code-provenance [compose-file] [--json] [--verbose]
+```
+
+- `compose-file` -- path to a docker-compose file (default: `docker-compose.yml`)
+- `--json` -- output results as JSON
+- `--verbose`, `-v` -- show resolution steps for each image
+
+### Example
+
+```bash
+code-provenance docker-compose.yml
+```
+
+```
+┌─────────┬────────────────┬────────────────────────────┬──────────────┬──────────┬────────────┐
+│ SERVICE │ IMAGE          │ REPO                       │ COMMIT       │ STATUS   │ CONFIDENCE │
+├─────────┼────────────────┼────────────────────────────┼──────────────┼──────────┼────────────┤
+│ web     │ traefik:v3.6.0 │ github.com/traefik/traefik │ 06db5168c0d9 │ resolved │ exact      │
+└─────────┴────────────────┴────────────────────────────┴──────────────┴──────────┴────────────┘
+```
+
+## Library Usage
+
+```python
+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):
+
+```bash
+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

code_provenance-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+code_provenance/__init__.py,sha256=QXuTuB3BUwFyeHy-1C344W90AwTq_sylBVcfoq-eGuw,57
+code_provenance/cli.py,sha256=mv1HbSP1NmaN08Pr-_8-jHyKo88kTLnoVAPWXdAn66Q,2061
+code_provenance/compose_parser.py,sha256=KYi8rQsKHgjHxAKCX9lE-aXjnMmhuaXBeCnpfG31TaU,1747
+code_provenance/github.py,sha256=TdUH7d__CaC_5si-APzGH9SnSdA0eQcpF3HpXonx-8A,8721
+code_provenance/models.py,sha256=Ajst43R3AMTlGSZ8m03LoUjJukr5NdL-86u-qQdWB9E,1048
+code_provenance/output.py,sha256=ntIlGAQIJRePpX9T4jEAZzANjL20opogRWUBFUUhTyM,1143
+code_provenance/registry.py,sha256=1Y0H7sxZOXIy9fpQRzVF2fUVgECcd1W1xI6VBx7QZ1U,4195
+code_provenance/resolver.py,sha256=MD23eZFm9VZ0ftqzNBzMkzKS4Ggo3OG8CSAyUErsiYE,7084
+code_provenance-0.1.0.dist-info/METADATA,sha256=GjZskUG-1V5UutExejROe1Q59giRfsX65W2IJRkg5mE,4885
+code_provenance-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_provenance-0.1.0.dist-info/entry_points.txt,sha256=iAIV7fGMBwmskCD1Vn15yrQt4VM52di9xjYf3cPC4jI,61
+code_provenance-0.1.0.dist-info/top_level.txt,sha256=TJ3A2kuZ0yVRV3rQYBZ6-1ILu_umwN8m7lmdYnhT2ak,16
+code_provenance-0.1.0.dist-info/RECORD,,

code_provenance-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

code_provenance-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+code-provenance = code_provenance.cli:main

code_provenance-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_provenance