|
| 1 | +"""Container image signature / pin verification. |
| 2 | +
|
| 3 | +Two complementary supply-chain checks are run for every image argus |
| 4 | +pulls: |
| 5 | +
|
| 6 | + * **Argus-owned images** (``ghcr.io/huntridge-labs/argus/*``) are |
| 7 | + cosign-signed at publish time via keyless Sigstore. We verify |
| 8 | + each pull against the expected certificate identity (our publish |
| 9 | + workflow URI) and OIDC issuer (GitHub Actions). Verification |
| 10 | + failure is fatal — refuse to run the scanner. |
| 11 | +
|
| 12 | + * **Third-party images** (Trivy, Grype, Checkov, OSV, ZAP, |
| 13 | + Hadolint, ESLint, etc.) are not in our signing surface. Two |
| 14 | + sub-paths: |
| 15 | + - ``image@sha256:...`` (digest pin): trust by content hash. |
| 16 | + Docker enforces digest match at pull time, so the pull |
| 17 | + itself *is* the verification — we report this and move on. |
| 18 | + - tag-only (``image:tag``): no cryptographic guarantee. We |
| 19 | + let the scan proceed but emit a single WARNING listing the |
| 20 | + tag-pinned images, with a hint to migrate to digest pins. |
| 21 | +
|
| 22 | +The combined policy is documented in ``docs/security.md`` and is |
| 23 | +the implementation of items (3) + (4) from the |
| 24 | +*Secret Handling & Credential Surface Hardening* roadmap section. |
| 25 | +
|
| 26 | +Stdlib + ``cosign`` binary only — no Python sigstore dependency to |
| 27 | +keep the install lean. |
| 28 | +""" |
| 29 | + |
| 30 | +from __future__ import annotations |
| 31 | + |
| 32 | +import logging |
| 33 | +import shutil |
| 34 | +import subprocess |
| 35 | +from dataclasses import dataclass |
| 36 | +from enum import Enum |
| 37 | +from typing import Iterable |
| 38 | + |
| 39 | +logger = logging.getLogger("argus") |
| 40 | + |
| 41 | + |
| 42 | +# The Fulcio certificate's ``subject`` field for keyless sigstore |
| 43 | +# signatures captures the URI of the GitHub workflow that performed |
| 44 | +# the signing. We anchor verification to *our* publish workflow plus |
| 45 | +# *our* OIDC issuer; the certificate-identity regexp is permissive |
| 46 | +# across refs (tags, branches) so a workflow-internal change doesn't |
| 47 | +# force a security-policy update. |
| 48 | +ARGUS_OWNED_PREFIX = "ghcr.io/huntridge-labs/argus/" |
| 49 | +ARGUS_CERT_IDENTITY_REGEXP = ( |
| 50 | + r"^https://github\.com/huntridge-labs/argus/" |
| 51 | + r"\.github/workflows/publish-release\.yml@" |
| 52 | +) |
| 53 | +ARGUS_OIDC_ISSUER = "https://token.actions.githubusercontent.com" |
| 54 | + |
| 55 | + |
| 56 | +class VerifyStatus(Enum): |
| 57 | + """Outcome of a single image verification attempt.""" |
| 58 | + |
| 59 | + VERIFIED_COSIGN = "verified_cosign" |
| 60 | + VERIFIED_DIGEST_PIN = "verified_digest_pin" |
| 61 | + SKIPPED_TAG_PIN = "skipped_tag_pin" |
| 62 | + SKIPPED_BY_CONFIG = "skipped_by_config" |
| 63 | + FAILED_COSIGN = "failed_cosign" |
| 64 | + FAILED_COSIGN_BINARY_MISSING = "failed_cosign_binary_missing" |
| 65 | + |
| 66 | + |
| 67 | +@dataclass(frozen=True) |
| 68 | +class VerifyResult: |
| 69 | + """The result of verifying a single image reference.""" |
| 70 | + |
| 71 | + status: VerifyStatus |
| 72 | + image: str |
| 73 | + message: str |
| 74 | + |
| 75 | + @property |
| 76 | + def is_fatal(self) -> bool: |
| 77 | + """True if the scanner using this image must NOT run.""" |
| 78 | + return self.status in ( |
| 79 | + VerifyStatus.FAILED_COSIGN, |
| 80 | + VerifyStatus.FAILED_COSIGN_BINARY_MISSING, |
| 81 | + ) |
| 82 | + |
| 83 | + |
| 84 | +def is_argus_owned(image: str) -> bool: |
| 85 | + """Return True if ``image`` is published from this repository.""" |
| 86 | + return image.startswith(ARGUS_OWNED_PREFIX) |
| 87 | + |
| 88 | + |
| 89 | +def has_digest_pin(image: str) -> bool: |
| 90 | + """Return True if ``image`` has a content-addressable ``@sha256:`` pin.""" |
| 91 | + return "@sha256:" in image |
| 92 | + |
| 93 | + |
| 94 | +def verify_image( |
| 95 | + image: str, |
| 96 | + *, |
| 97 | + verify_signatures: bool = True, |
| 98 | + cosign_runner=None, |
| 99 | +) -> VerifyResult: |
| 100 | + """Verify a single image reference. |
| 101 | +
|
| 102 | + ``cosign_runner`` is an optional callable for tests; it receives |
| 103 | + the argv list and must return a ``subprocess.CompletedProcess``- |
| 104 | + shaped object with ``returncode``, ``stdout``, ``stderr``. The |
| 105 | + default uses ``subprocess.run`` with cosign on PATH. |
| 106 | + """ |
| 107 | + if not image: |
| 108 | + return VerifyResult( |
| 109 | + status=VerifyStatus.SKIPPED_BY_CONFIG, |
| 110 | + image=image, |
| 111 | + message="empty image reference — nothing to verify", |
| 112 | + ) |
| 113 | + |
| 114 | + if not verify_signatures: |
| 115 | + return VerifyResult( |
| 116 | + status=VerifyStatus.SKIPPED_BY_CONFIG, |
| 117 | + image=image, |
| 118 | + message="signature verification disabled via " |
| 119 | + "execution.verify_image_signatures: false", |
| 120 | + ) |
| 121 | + |
| 122 | + # Argus-owned: cosign verify, fail-on-failure. |
| 123 | + if is_argus_owned(image): |
| 124 | + return _verify_cosign(image, cosign_runner=cosign_runner) |
| 125 | + |
| 126 | + # Third-party with digest pin: Docker enforces content-hash match |
| 127 | + # at pull. No additional verification needed. |
| 128 | + if has_digest_pin(image): |
| 129 | + return VerifyResult( |
| 130 | + status=VerifyStatus.VERIFIED_DIGEST_PIN, |
| 131 | + image=image, |
| 132 | + message="verified via @sha256 digest pin (Docker enforces " |
| 133 | + "content-hash match at pull)", |
| 134 | + ) |
| 135 | + |
| 136 | + # Third-party with tag-only pin: no crypto guarantee. Let the scan |
| 137 | + # proceed but report so the caller can warn once per run. |
| 138 | + return VerifyResult( |
| 139 | + status=VerifyStatus.SKIPPED_TAG_PIN, |
| 140 | + image=image, |
| 141 | + message="third-party image is tag-pinned (mutable). Pull " |
| 142 | + "succeeds but no signature or digest guarantee. " |
| 143 | + "Migrate to image@sha256:... for content-addressable " |
| 144 | + "trust.", |
| 145 | + ) |
| 146 | + |
| 147 | + |
| 148 | +def _verify_cosign(image: str, *, cosign_runner=None) -> VerifyResult: |
| 149 | + """Run ``cosign verify`` against an argus-owned image.""" |
| 150 | + if cosign_runner is None: |
| 151 | + if not shutil.which("cosign"): |
| 152 | + return VerifyResult( |
| 153 | + status=VerifyStatus.FAILED_COSIGN_BINARY_MISSING, |
| 154 | + image=image, |
| 155 | + message=( |
| 156 | + "cosign binary not on PATH but signature verification " |
| 157 | + "is enabled. Install cosign (https://docs.sigstore.dev/cosign/installation/) " |
| 158 | + "or set execution.verify_image_signatures: false in " |
| 159 | + "argus.yml to opt out." |
| 160 | + ), |
| 161 | + ) |
| 162 | + cosign_runner = _default_cosign_runner |
| 163 | + |
| 164 | + cmd = [ |
| 165 | + "cosign", "verify", image, |
| 166 | + "--certificate-identity-regexp", ARGUS_CERT_IDENTITY_REGEXP, |
| 167 | + "--certificate-oidc-issuer", ARGUS_OIDC_ISSUER, |
| 168 | + ] |
| 169 | + try: |
| 170 | + result = cosign_runner(cmd) |
| 171 | + except FileNotFoundError: |
| 172 | + return VerifyResult( |
| 173 | + status=VerifyStatus.FAILED_COSIGN_BINARY_MISSING, |
| 174 | + image=image, |
| 175 | + message=( |
| 176 | + "cosign binary not on PATH but signature verification " |
| 177 | + "is enabled. Install cosign or set " |
| 178 | + "execution.verify_image_signatures: false." |
| 179 | + ), |
| 180 | + ) |
| 181 | + |
| 182 | + if result.returncode == 0: |
| 183 | + return VerifyResult( |
| 184 | + status=VerifyStatus.VERIFIED_COSIGN, |
| 185 | + image=image, |
| 186 | + message="cosign keyless verify passed " |
| 187 | + "(identity=argus publish workflow, " |
| 188 | + "issuer=token.actions.githubusercontent.com)", |
| 189 | + ) |
| 190 | + |
| 191 | + # Cosign failure — surface stderr so the user can act. Be careful |
| 192 | + # not to log credential-shaped strings; cosign output is the |
| 193 | + # canonical Sigstore/Fulcio error path and doesn't carry secrets. |
| 194 | + stderr = (result.stderr or "").strip() |
| 195 | + return VerifyResult( |
| 196 | + status=VerifyStatus.FAILED_COSIGN, |
| 197 | + image=image, |
| 198 | + message=( |
| 199 | + f"cosign verify FAILED for argus-owned image. " |
| 200 | + f"cosign output: {stderr[:500]}" |
| 201 | + ), |
| 202 | + ) |
| 203 | + |
| 204 | + |
| 205 | +def _default_cosign_runner(cmd: list[str]) -> subprocess.CompletedProcess: |
| 206 | + """Production cosign runner — captures output, never raises on rc != 0.""" |
| 207 | + return subprocess.run( |
| 208 | + cmd, capture_output=True, text=True, |
| 209 | + encoding="utf-8", errors="replace", |
| 210 | + ) |
| 211 | + |
| 212 | + |
| 213 | +def report_tag_pinned_summary(results: Iterable[VerifyResult]) -> None: |
| 214 | + """Emit one WARNING summarizing third-party tag-pinned images. |
| 215 | +
|
| 216 | + Called once per scan run after all verification has occurred so |
| 217 | + users don't get N separate warnings for N scanners pointing at the |
| 218 | + same registry. Silent if nothing was tag-pinned. |
| 219 | + """ |
| 220 | + tag_pinned = [ |
| 221 | + r.image for r in results |
| 222 | + if r.status == VerifyStatus.SKIPPED_TAG_PIN |
| 223 | + ] |
| 224 | + if not tag_pinned: |
| 225 | + return |
| 226 | + # Deduplicate but preserve order (Python 3.7+ dict ordering). |
| 227 | + unique = list(dict.fromkeys(tag_pinned)) |
| 228 | + logger.warning( |
| 229 | + "%d third-party image(s) pulled with mutable tag pins " |
| 230 | + "(no cryptographic guarantee): %s. Migrate to " |
| 231 | + "@sha256:... digest pins in argus/containers.py for " |
| 232 | + "content-addressable trust. See docs/security.md for the " |
| 233 | + "supply-chain policy.", |
| 234 | + len(unique), |
| 235 | + ", ".join(unique), |
| 236 | + ) |
0 commit comments