code-provenance 0.1.0__tar.gz

code_provenance-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,98 @@
+# 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/code_provenance/__init__.py

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

code_provenance-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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()