diff --git a/.github/scripts/image-policy.py b/.github/scripts/image-policy.py index a0f3008..b1976ca 100644 --- a/.github/scripts/image-policy.py +++ b/.github/scripts/image-policy.py @@ -2,6 +2,8 @@ """Fail-closed source/application and image scans with redacted evidence.""" import argparse +from datetime import datetime, timezone +import hashlib import json import os from pathlib import Path @@ -9,10 +11,63 @@ import subprocess import sys -def check_report(report, image=False, source=False): +def secret_identity(target, finding): + return (target, finding.get("RuleID"), finding.get("Category"), + finding.get("Severity"), finding.get("StartLine"), finding.get("EndLine")) + + +def approve_shared_key(report, source_root, policy, now=None): + """Bind the one reviewed exception to an unchanged file and exact finding.""" + now = now or datetime.now(timezone.utc) + records = policy.get("exceptions") + if not isinstance(records, list) or len(records) != 1: + raise ValueError("Exactly one shared-key exception record is required") + record = records[0] + if not isinstance(record, dict) or record.get("id") != "shared-recording-signing-key": + raise ValueError("Unexpected scan exception") + if record.get("status") != "approved" or not all( + isinstance(record.get(key), str) and record[key].strip() + for key in ("owner", "approved_by", "reason", "approval_url", "expires") + ): + raise ValueError("Shared-key exception lacks approval/owner/reason/evidence/expiry") + if record["approval_url"] != "https://github.com/kerberos-io/agent/pull/350": + raise ValueError("Shared-key exception must reference its reviewed PR record") + expires = datetime.fromisoformat(record["expires"].replace("Z", "+00:00")) + if expires.tzinfo is None or expires <= now: + raise ValueError("Shared-key exception expired or lacks timezone") + if (record.get("target") != "machinery/src/config/main.go" + or record.get("rule_id") != "private-key" + or record.get("category") != "AsymmetricPrivateKey" + or record.get("severity") != "HIGH" + or type(record.get("start_line")) is not int + or record["start_line"] < 1 + or record.get("end_line") != record["start_line"]): + raise ValueError("Shared-key exception has an unexpected finding scope") + root = Path(source_root).resolve() + path = root / record["target"] + if path.resolve() != path or hashlib.sha256(path.read_bytes()).hexdigest() != record.get("file_sha256"): + raise ValueError("Shared-key source file changed or is a symlink; renewed review required") + expected = (record["target"], record["rule_id"], record["category"], + record["severity"], record["start_line"], record["end_line"]) + matches = [ + finding for result in report["Results"] + for finding in result.get("Secrets", []) + if secret_identity(result.get("Target"), finding) == expected + ] + if len(matches) != 1: + raise ValueError("Shared-key exception must match exactly one existing source finding") + return [dict(record)] + + +def check_report(report, image=False, source=False, approved_exceptions=()): if report.get("SchemaVersion") != 2 or not isinstance(report.get("Results"), list): raise ValueError("Missing or unsupported Trivy report") failures = [] + approved_secrets = { + (record["target"], record["rule_id"], record["category"], record["severity"], + record["start_line"], record["end_line"]) + for record in approved_exceptions + } if source and not image else set() for result in report["Results"]: if result.get("Errors"): failures.append(f"Scan errors in {result.get('Target')}: {result['Errors']}") @@ -25,6 +80,8 @@ def check_report(report, image=False, source=False): if kind == "Misconfigurations" and finding.get("Status") != "FAIL": failures.append(f"Unexpected/suppressed misconfiguration status: {finding.get('Status')}") severity = finding.get("Severity", "UNKNOWN") + if kind == "Secrets" and secret_identity(result.get("Target"), finding) in approved_secrets: + continue if severity not in ("LOW", "MEDIUM"): failures.append(f"{result.get('Target')}: {kind}: " f"{finding.get('VulnerabilityID', finding.get('ID', finding.get('RuleID')))} " @@ -120,7 +177,20 @@ def scan(target, output, platform=None): except ValueError: raise ValueError("Invalid scanner JSON; raw output withheld") from None (output / "scan.json").write_text(json.dumps(report, indent=2) + "\n") - failures = check_report(report, image=bool(platform), source=not platform) + approved = [] + exception_failures = [] + if not platform: + try: + policy = json.loads(Path(__file__).with_name("image-scan-exceptions.json").read_text()) + (output / "exception-policy.json").write_text(json.dumps(policy, indent=2) + "\n") + approved = approve_shared_key(report, target, policy) + except (OSError, ValueError, TypeError, KeyError) as error: + exception_failures.append(f"Shared-key exception invalid: {error}") + (output / "exception-decisions.json").write_text(json.dumps({ + "approved_exceptions": approved, "failures": exception_failures, + }, indent=2) + "\n") + failures = exception_failures + check_report( + report, image=bool(platform), source=not platform, approved_exceptions=approved) if not platform: inventory = [{ "target": result.get("Target"), "type": result.get("Type"), @@ -129,7 +199,8 @@ def scan(target, output, platform=None): for pkg in result.get("Packages", [])], } for result in report["Results"] if result.get("Packages")] (output / "application-inventory.json").write_text(json.dumps({ - "policy": "All production and development/build dependencies are gated; no exclusions.", + "policy": "All production and development/build dependencies are gated; " + "only the reviewed, exact shared-key secret exception may apply.", "inventories": inventory, }, indent=2) + "\n") converted = subprocess.run([ @@ -152,13 +223,15 @@ def main(): parser.add_argument("--platform", help="Image platform, e.g. linux/amd64; omit for source/UI scanning") args = parser.parse_args() args.output.mkdir(parents=True, exist_ok=True) + approved = [] try: failures = scan(args.target, args.output, args.platform) + approved = json.loads((args.output / "exception-decisions.json").read_text())["approved_exceptions"] except (OSError, ValueError, subprocess.CalledProcessError) as error: failures = [f"Scanner/evidence error: {error}"] (args.output / "policy.json").write_text(json.dumps({ "target": args.target, "platform": args.platform, "failures": failures, - "approved_exceptions": [], "passed": not failures, + "approved_exceptions": approved, "passed": not failures, }, indent=2) + "\n") for failure in failures: print(failure, file=sys.stderr) diff --git a/.github/scripts/image-scan-exceptions.json b/.github/scripts/image-scan-exceptions.json new file mode 100644 index 0000000..72032b4 --- /dev/null +++ b/.github/scripts/image-scan-exceptions.json @@ -0,0 +1,20 @@ +{ + "exceptions": [ + { + "id": "shared-recording-signing-key", + "status": "approved", + "owner": "@cedricve", + "approved_by": "@cedricve", + "approval_url": "https://github.com/kerberos-io/agent/pull/350", + "expires": "2026-12-05T23:59:59Z", + "reason": "User approved temporary retention of the existing shared recording-signing key to preserve recording verification trust and startup behavior. Anyone possessing this shared private key can forge signatures under that identity.", + "target": "machinery/src/config/main.go", + "file_sha256": "e28a0bf6ae892559709e8ec534cfc7b7cb55180e33415461d966c1afe53ca25b", + "rule_id": "private-key", + "category": "AsymmetricPrivateKey", + "severity": "HIGH", + "start_line": 710, + "end_line": 710 + } + ] +} diff --git a/.github/scripts/test-image-policy.py b/.github/scripts/test-image-policy.py index 3d47ffd..f4a6982 100644 --- a/.github/scripts/test-image-policy.py +++ b/.github/scripts/test-image-policy.py @@ -2,12 +2,15 @@ """Focused release guard tests; no registry, signing, or scanner network access.""" from datetime import datetime, timezone +import copy +import hashlib import importlib.util import json from pathlib import Path import unittest from unittest.mock import patch import subprocess +import tempfile ROOT = Path(__file__).parent @@ -114,7 +117,8 @@ class ScanPolicyTests(unittest.TestCase): directory.__truediv__.return_value.read_text.return_value = json.dumps({ "spdxVersion": "SPDX-2.3", "packages": [{"name": "fixture"}]}) completed = subprocess.CompletedProcess(["trivy"], 0, stdout=json.dumps(report), stderr="") - with patch.object(scanner.subprocess, "run", return_value=completed) as run: + with patch.object(scanner.subprocess, "run", return_value=completed) as run, \ + patch.object(scanner, "approve_shared_key", return_value=[]): self.assertEqual(scanner.scan("fixture", directory), []) command = run.call_args_list[0].args[0] self.assertIn("--include-dev-deps", command) @@ -133,6 +137,116 @@ class ScanPolicyTests(unittest.TestCase): self.assertNotIn(marker, str(directory.mock_calls)) +class SharedKeyExceptionTests(unittest.TestCase): + NOW = datetime(2026, 11, 5, tzinfo=timezone.utc) + + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + self.path = self.root / "machinery/src/config/main.go" + self.path.parent.mkdir(parents=True) + self.path.write_text("non-secret source fixture\n") + self.policy = json.loads((ROOT / "image-scan-exceptions.json").read_text()) + self.record = self.policy["exceptions"][0] + self.record["file_sha256"] = hashlib.sha256(self.path.read_bytes()).hexdigest() + self.finding = { + "RuleID": self.record["rule_id"], "Category": self.record["category"], + "Severity": "HIGH", "StartLine": 710, "EndLine": 710, + } + self.report = {"SchemaVersion": 2, "Results": [ + {"Target": self.record["target"], "Secrets": [self.finding]}, + {"Target": "ui/yarn.lock", "Type": "yarn", "Packages": [{"Name": "react"}]}, + ]} + + def approved(self): + return scanner.approve_shared_key(self.report, self.root, self.policy, self.NOW) + + def test_exact_key_is_approved_but_finding_is_preserved(self): + original = copy.deepcopy(self.report) + approved = self.approved() + self.assertTrue(scanner.check_report(self.report, source=True)) + self.assertEqual(scanner.check_report( + self.report, source=True, approved_exceptions=approved), []) + self.assertEqual(self.report, original) + self.assertEqual(approved[0]["id"], "shared-recording-signing-key") + + def test_other_secrets_and_vulnerabilities_still_block(self): + approved = self.approved() + result = self.report["Results"][0] + result["Secrets"].append(dict(self.finding, StartLine=711, EndLine=711)) + result["Vulnerabilities"] = [{"VulnerabilityID": "fixture", "Severity": "CRITICAL"}] + self.assertEqual(len(scanner.check_report( + self.report, source=True, approved_exceptions=approved)), 2) + + def test_exception_never_applies_to_image_or_non_source_scans(self): + approved = self.approved() + self.assertTrue(scanner.check_report(self.report, approved_exceptions=approved)) + self.assertTrue(scanner.check_report( + self.report, image=True, source=True, approved_exceptions=approved)) + + def test_expiry_is_enforced_at_boundary(self): + expiry = datetime(2026, 12, 5, 23, 59, 59, tzinfo=timezone.utc) + with self.assertRaisesRegex(ValueError, "expired"): + scanner.approve_shared_key(self.report, self.root, self.policy, expiry) + self.record["expires"] = "2026-12-05" + with self.assertRaisesRegex(ValueError, "timezone"): + self.approved() + + def test_incomplete_or_unapproved_metadata_blocks(self): + for field in ("owner", "approved_by", "reason", "approval_url", "expires", "status"): + with self.subTest(field=field): + original = self.record[field] + self.record[field] = "" + with self.assertRaises(ValueError): + self.approved() + self.record[field] = original + self.record["approval_url"] = "https://example.com/unreviewed" + with self.assertRaises(ValueError): + self.approved() + + def test_changed_source_or_symlink_requires_review(self): + self.path.write_text("changed source fixture\n") + with self.assertRaisesRegex(ValueError, "changed"): + self.approved() + target = self.root / "other.go" + self.path.rename(target) + self.path.symlink_to(target) + with self.assertRaisesRegex(ValueError, "symlink"): + self.approved() + + def test_changed_finding_does_not_match(self): + for field, value in (("RuleID", "other"), ("Category", "other"), + ("Severity", "CRITICAL"), ("StartLine", 711), ("EndLine", 711)): + with self.subTest(field=field): + original = self.finding[field] + self.finding[field] = value + with self.assertRaisesRegex(ValueError, "exactly one"): + self.approved() + self.finding[field] = original + + def test_duplicate_missing_or_broadened_records_block(self): + self.policy["exceptions"].append(dict(self.record)) + with self.assertRaises(ValueError): + self.approved() + self.policy["exceptions"].pop() + self.report["Results"][0]["Secrets"].append(dict(self.finding)) + with self.assertRaisesRegex(ValueError, "exactly one"): + self.approved() + self.report["Results"][0]["Secrets"] = [] + with self.assertRaisesRegex(ValueError, "exactly one"): + self.approved() + self.record["target"] = "../other.go" + with self.assertRaisesRegex(ValueError, "scope"): + self.approved() + + def test_checked_in_record_matches_unchanged_source(self): + report = copy.deepcopy(self.report) + policy = json.loads((ROOT / "image-scan-exceptions.json").read_text()) + self.assertEqual(len(scanner.approve_shared_key( + report, ROOT.parent.parent, policy, self.NOW)), 1) + + class ReleasePolicyTests(unittest.TestCase): NOW = datetime(2026, 11, 4, tzinfo=timezone.utc) diff --git a/README.md b/README.md index 316daca..4b0ef4a 100644 --- a/README.md +++ b/README.md @@ -166,11 +166,11 @@ paths, health checks, supported architectures, signature/evidence requirements, and release-policy gaps. Functional remote-shell support remains a **pending policy exception**, so this is not a claim of full image-hardening baseline or CIS compliance. -Release promotion is also blocked by remaining native-library scan findings -and the legacy default recording-signing key; this PR is not release-qualified. -The existing signing key and recording-trust behavior are retained by explicit -user decision. This does not waive the key's security finding or approve a -release exception. +Release promotion is also blocked by remaining native-library scan findings; +this PR is not release-qualified. The existing recording-signing key and trust +behavior are retained under the user's narrowly scoped exception through +December 5, 2026 (23:59:59 UTC), recorded for review in this PR. The finding +remains visible in scan reports; other keys and findings are not exempted. If you want to connect to a USB or Raspberry Pi camera, [you'll need to run our side car container](https://github.com/kerberos-io/camera-to-rtsp) which proxies the camera to an RTSP stream. In that case you'll want to configure the Kerberos Agent container to run in the host network, so it can connect directly to the RTSP sidecar. diff --git a/deployments/docker/README.md b/deployments/docker/README.md index 8d47871..0441701 100644 --- a/deployments/docker/README.md +++ b/deployments/docker/README.md @@ -169,10 +169,25 @@ signing, or scans have already succeeded. Source scans cover UI production **and build/development** dependencies and retain their application inventory/SBOM, because compiled browser assets hide lockfile metadata from final-rootfs scanners. Final-image evidence separately covers native -packages and the Go binary. Current native-library findings and the legacy -embedded default recording-signing private key are still release blockers; the -existing key and recording-trust behavior are retained by explicit user decision. -That decision is not a scanner suppression or an approved release exception. +packages and the Go binary. Current native-library findings remain release +blockers. The existing embedded recording-signing key and trust behavior are +retained under the user's time-limited source-secret exception, recorded for +review in this PR in +[image-scan-exceptions.json](../../.github/scripts/image-scan-exceptions.json). +Owner and approver: `@cedricve`; expiry: **December 5, 2026, 23:59:59 UTC**. +Anyone possessing this shared private key can forge signatures under its +identity; the exception accepts that risk temporarily, it does not fix it. + +The exception matches only that source file's SHA-256, exact scanner rule, +category, HIGH severity and line location, and requires exactly one match. +Changes, missing/incomplete approval, expiry or duplicate findings fail closed. +It cannot exempt an image finding, another secret, a vulnerability or a +misconfiguration. The policy is loaded from the executing workflow's checkout, +not the source directory being scanned. Retained `scan.json` still contains the +redacted HIGH finding; `exception-policy.json`, `exception-decisions.json` and +`policy.json` record the approval/application, without key material. Review the +record in PR #350 before merging; repository owners must enforce required reviews. +This exception does not approve the separate pending remote-terminal policy. The build jobs run compilation and production-image smoke tests before the security gates. A job that fails at **Source/UI dependency and final image gates @@ -193,8 +208,9 @@ adopted to obtain a misleading clean scan. A newer media stack needs matched CGO headers/libraries and validation of codecs, hardware acceleration and supported architectures, not an unreviewed mix of testing-distribution packages. The user has chosen to keep the default recording-signing key; no trust -migration or startup change is implemented. Its source-secret finding remains -an unresolved release blocker. Any future removal would require a separately +migration or startup change is implemented. Its source-secret finding becomes +release-blocking again if the scoped exception expires or no longer matches. +Any future removal would require a separately authorized migration: per-installation keys need verifier/public-key provisioning, while requiring an injected key changes startup for existing keyless installations.