Charon/docs/plans/current_spec.md

# Security Scan (PR) Deterministic Artifact Policy - Supervisor Remediation Plan

## 1. Introduction

### Overview

`Security Scan (PR)` failed because `.github/workflows/security-pr.yml` loaded
an artifact image tag (`pr-718-385081f`) and later attempted extraction with a
different synthesized tag (`pr-718`).

Supervisor conflict resolution in this plan selects Option A:
`workflow_run` artifact handling is restricted to upstream
`pull_request` events only.

### Root-Cause Clarity (Preserved)

The failure was not a Docker load failure. It was a source-of-truth violation in
image selection:

1. Artifact load path succeeded.
2. Extraction path reconstructed an alternate reference.
3. Alternate reference did not exist, causing `docker create ... not found`.

This plan keeps scope strictly on `.github/workflows/security-pr.yml`.

### Objectives

1. Remove all ambiguous behavior for artifact absence on `workflow_run`.
2. Remove `workflow_run` support for upstream `push` events to align with PR
   artifact naming contract (`pr-image-<pr_number>`).
3. Codify one deterministic `workflow_dispatch` policy in SHALL form.
4. Harden image selection so it is not brittle on `RepoTags[0]`.
5. Add CI security hardening requirements for permissions and trust boundary.
6. Expand validation matrix to include `pull_request` and negative paths.

---

## 2. Research Findings

### 2.1 Failure Evidence

Source: `.github/logs/ci_failure.log`

Observed facts:

1. Artifact `pr-image-718` was found and downloaded from run `22164807859`.
2. `docker load` reported: `Loaded image: ghcr.io/wikid82/charon:pr-718-385081f`.
3. Extraction attempted: `docker create ghcr.io/wikid82/charon:pr-718`.
4. Docker reported: `... pr-718: not found`.

### 2.2 Producer Contract

Source: `.github/workflows/docker-build.yml`

Producer emits immutable PR tags with SHA suffix (`pr-<num>-<sha>`). Consumer
must consume artifact metadata/load output, not reconstruct mutable tags.

### 2.3 Current Consumer Gaps

Source: `.github/workflows/security-pr.yml`

Current consumer contains ambiguous policy points:

1. `workflow_run` artifact absence behavior can be interpreted as skip or fail.
2. `workflow_dispatch` policy is not single-path deterministic.
3. Image identification relies on single `RepoTags[0]` assumption.
4. Trust boundary and permission minimization are not explicitly codified as
   requirements.

---

## 3. Technical Specifications

### 3.1 Deterministic EARS Requirements (Blocking)

1. WHEN `security-pr.yml` is triggered by `workflow_run` with
   `conclusion == success` and upstream event `pull_request`, THE SYSTEM SHALL
   require the expected image artifact to exist and SHALL hard fail the job if
   the artifact is missing.

2. WHEN `security-pr.yml` is triggered by `workflow_run` and artifact lookup
   fails, THEN THE SYSTEM SHALL exit non-zero with a diagnostic that includes:
   upstream run id, expected artifact name, and reason category (`not found` or
   `api/error`).

3. WHEN `security-pr.yml` is triggered by `workflow_run` and upstream event is
   not `pull_request`, THEN THE SYSTEM SHALL hard fail immediately with reason
   category `unsupported_upstream_event` and SHALL NOT attempt artifact lookup,
   image load, or extraction.

4. WHEN `security-pr.yml` is triggered by `workflow_dispatch`, THE SYSTEM SHALL
   require `inputs.pr_number` and SHALL hard fail immediately if input is empty.

5. WHEN `security-pr.yml` is triggered by `workflow_dispatch` with valid
   `inputs.pr_number`, THE SYSTEM SHALL resolve artifact `pr-image-<pr_number>`
   from the latest successful `docker-build.yml` run for that PR and SHALL hard
   fail if artifact resolution or download fails.

6. WHEN artifact image is loaded, THE SYSTEM SHALL derive a canonical local
   image alias (`charon:artifact`) from validated load result and SHALL use only
   that alias for `docker create` in artifact-based paths.

7. WHEN artifact metadata parsing is required, THE SYSTEM SHALL NOT depend only
   on `RepoTags[0]`; it SHALL validate all available repo tags and SHALL support
   fallback selection using docker load image ID when tags are absent/corrupt.

8. IF no valid tag and no valid load image ID can be resolved, THEN THE SYSTEM
   SHALL hard fail before extraction.

9. WHEN event is `pull_request` or `push`, THE SYSTEM SHALL build and use
   `charon:local` only and SHALL NOT execute artifact lookup/load logic.

### 3.2 Deterministic Policy Decisions

#### Policy A: `workflow_run` Missing Artifact

Decision: hard fail only.

No skip behavior is allowed for upstream-success `workflow_run`.

#### Policy A1: `workflow_run` Upstream Event Contract

Decision: upstream event MUST be `pull_request`.

If upstream event is `push` or any non-PR event, fail immediately with
`unsupported_upstream_event`; no artifact path execution is allowed.

#### Policy B: `workflow_dispatch`

Decision: artifact-only manual replay.

No local-build fallback is allowed for `workflow_dispatch`. Required input is
`pr_number`; missing input is immediate hard fail.

### 3.3 Image Selection Hardening Contract

For step `Load Docker image` in `.github/workflows/security-pr.yml`:

1. Validate artifact file exists and is readable tar.
2. Parse `manifest.json` and iterate all candidate tags under `RepoTags[]`.
3. Run `docker load` and capture structured output.
4. Resolve source image by deterministic priority:
   - First valid tag from `RepoTags[]` that exists locally after load.
   - Else image ID extracted from `docker load` output (if present).
   - Else fail.
5. Retag resolved source to `charon:artifact`.
6. Emit outputs:
   - `image_ref=charon:artifact`
   - `source_image_ref=<resolved tag or image id>`
   - `source_resolution_mode=manifest_tag|load_image_id`

### 3.4 CI Security Hardening Requirements

For job `security-scan` in `.github/workflows/security-pr.yml`:

1. THE SYSTEM SHALL enforce least-privilege permissions by default:
   - `contents: read`
   - `actions: read`
   - `security-events: write`
   - No additional write scopes unless explicitly required.

2. THE SYSTEM SHALL restrict `pull-requests: write` usage to only steps that
   require PR annotations/comments. If no such step exists, this permission
   SHALL be removed.

3. THE SYSTEM SHALL enforce workflow_run trust boundary guards:
   - Upstream workflow name must match expected producer.
   - Upstream conclusion must be `success`.
   - Upstream event must be `pull_request` only.
   - Upstream head repository must equal `${{ github.repository }}` (same-repo
     trust boundary), otherwise hard fail.

4. THE SYSTEM SHALL NOT use untrusted `workflow_run` payload values to build
   shell commands without validation and quoting.

### 3.5 Step-Level Scope in `security-pr.yml`

Targeted steps:

1. `Extract PR number from workflow_run`
2. `Validate workflow_run upstream event contract`
3. `Check for PR image artifact`
4. `Skip if no artifact` (to be converted to deterministic fail paths for
   `workflow_run` and `workflow_dispatch`)
5. `Load Docker image`
6. `Extract charon binary from container`

### 3.6 Event Data Flow (Deterministic)

```text
pull_request/push
  -> Build Docker image (Local)
  -> image_ref=charon:local
  -> Extract /app/charon
  -> Trivy scan

workflow_run (upstream success only)
   -> Assert upstream event == pull_request (hard fail if false)
  -> Require artifact exists (hard fail if missing)
  -> Load/validate image
  -> image_ref=charon:artifact
  -> Extract /app/charon
  -> Trivy scan

workflow_dispatch
  -> Require pr_number input (hard fail if missing)
  -> Resolve pr-image-<pr_number> artifact (hard fail if missing)
  -> Load/validate image
  -> image_ref=charon:artifact
  -> Extract /app/charon
  -> Trivy scan
```

### 3.7 Error Handling Matrix

| Step | Condition | Required Behavior |
|---|---|---|
| Validate workflow_run upstream event contract | `workflow_run` upstream event is not `pull_request` | Hard fail with `unsupported_upstream_event`; stop before artifact lookup |
| Check for PR image artifact | `workflow_run` upstream success but artifact missing | Hard fail with run id + artifact name |
| Extract PR number from workflow_run | `workflow_dispatch` and empty `inputs.pr_number` | Hard fail with input requirement message |
| Load Docker image | Missing/corrupt `charon-pr-image.tar` | Hard fail before `docker load` |
| Load Docker image | Missing/corrupt `manifest.json` | Attempt load-image-id fallback; fail if unresolved |
| Load Docker image | No valid `RepoTags[]` and no load image id | Hard fail |
| Extract charon binary from container | Empty/invalid `image_ref` | Hard fail before `docker create` |
| Extract charon binary from container | `/app/charon` missing | Hard fail with chosen image reference |

### 3.8 API/DB Changes

No backend API, frontend, or database schema changes.

---

## 4. Implementation Plan

### Phase 1: Playwright Impact Check

1. Mark Playwright scope as N/A because this change is workflow-only.
2. Record N/A rationale in PR description.

### Phase 2: Deterministic Event Policies

File: `.github/workflows/security-pr.yml`

1. Convert ambiguous skip/fail logic to hard-fail policy for
   `workflow_run` missing artifact after upstream success.
2. Enforce deterministic `workflow_dispatch` policy:
   - Required `pr_number` input.
   - Artifact-only replay path.
   - No local fallback.
3. Enforce PR-only `workflow_run` event contract:
   - Upstream event must be `pull_request`.
   - Upstream `push` or any non-PR event hard fails with
     `unsupported_upstream_event`.

### Phase 3: Image Selection Hardening

File: `.github/workflows/security-pr.yml`

1. Harden `Load Docker image` with manifest validation and multi-tag handling.
2. Add fallback resolution via docker load image ID.
3. Emit explicit outputs for traceability (`source_resolution_mode`).
4. Ensure extraction consumes only selected alias (`charon:artifact`).

### Phase 4: CI Security Hardening

File: `.github/workflows/security-pr.yml`

1. Reduce job permissions to least privilege.
2. Remove/conditionalize `pull-requests: write` if not required.
3. Add workflow_run trust-boundary guard conditions and explicit fail messages.

### Phase 5: Validation

1. `pre-commit run actionlint --files .github/workflows/security-pr.yml`
2. Simulate deterministic paths (or equivalent CI replay) for all matrix cases.
3. Verify logs show chosen `source_image_ref` and `source_resolution_mode`.

---

## 5. Validation Matrix

| ID | Trigger Path | Scenario | Expected Result |
|---|---|---|---|
| V1 | `workflow_run` | Upstream success + artifact present | Pass, uses `charon:artifact` |
| V2 | `workflow_run` | Upstream success + artifact missing | Hard fail (non-zero) |
| V3 | `workflow_run` | Upstream success + artifact manifest corrupted | Hard fail after validation/fallback attempt |
| V4 | `workflow_run` | Upstream success + upstream event `push` | Hard fail with `unsupported_upstream_event` |
| V5 | `pull_request` | Direct PR trigger | Pass, uses `charon:local`, no artifact lookup |
| V6 | `push` | Direct push trigger | Pass, uses `charon:local`, no artifact lookup |
| V7 | `workflow_dispatch` | Missing `pr_number` input | Hard fail immediately |
| V8 | `workflow_dispatch` | Valid `pr_number` + artifact exists | Pass, uses `charon:artifact` |
| V9 | `workflow_dispatch` | Valid `pr_number` + artifact missing | Hard fail |
| V10 | `workflow_run` | Upstream from untrusted repository context | Hard fail by trust-boundary guard |

---

## 6. Acceptance Criteria

1. Plan states unambiguous hard-fail behavior for missing artifact on
   `workflow_run` after upstream `pull_request` success.
2. Plan states `workflow_run` event contract is PR-only and that upstream
   `push` is a deterministic hard-fail contract violation.
3. Plan states one deterministic `workflow_dispatch` policy in SHALL terms:
   required `pr_number`, artifact-only path, no local fallback.
4. Plan defines robust image resolution beyond `RepoTags[0]`, including
   load-image-id fallback and deterministic aliasing.
5. Plan includes least-privilege permissions and explicit workflow_run trust
   boundary constraints.
6. Plan includes validation coverage for `pull_request` and direct `push` local
   paths plus negative paths: unsupported upstream event, missing dispatch
   input, missing artifact, corrupted/missing manifest.
7. Root cause remains explicit: image-reference mismatch inside
   `.github/workflows/security-pr.yml` after successful artifact load.

---

## 7. Risks and Mitigations

| Risk | Impact | Mitigation |
|---|---|---|
| Overly strict dispatch policy blocks ad-hoc scans | Medium | Document explicit manual replay contract in workflow description |
| PR-only workflow_run contract fails upstream push-triggered runs | Medium | Intentional contract enforcement; document `unsupported_upstream_event` and route push scans through direct push path |
| Manifest parsing edge cases | Medium | Multi-source resolver with load-image-id fallback |
| Permission tightening breaks optional PR annotations | Low | Make PR-write permission step-scoped only if needed |
| Trust-boundary guards reject valid internal events | Medium | Add clear diagnostics and test cases V1/V10 |

---

## 8. PR Slicing Strategy

### Decision

Single PR.

### Trigger Reasons

1. Change is isolated to one workflow (`security-pr.yml`).
2. Deterministic policy + hardening are tightly coupled and safest together.
3. Split PRs would create temporary policy inconsistency.

### Ordered Slice

#### PR-1: Deterministic Policy and Security Hardening for `security-pr.yml`

Scope:

1. Deterministic missing-artifact handling (`workflow_run` hard fail).
2. Deterministic `workflow_dispatch` artifact-only policy.
3. Hardened image resolution and aliasing.
4. Least-privilege + trust-boundary constraints.
5. Validation matrix execution evidence.

Files:

1. `.github/workflows/security-pr.yml`
2. `docs/plans/current_spec.md`

Dependencies:

1. `.github/workflows/docker-build.yml` artifact naming contract unchanged.

Validation Gates:

1. actionlint passes.
2. Validation matrix V1-V10 results captured.
3. No regression to `ghcr.io/...:pr-<num> not found` pattern.

Rollback / Contingency:

1. Revert PR-1 if trust-boundary guards block legitimate same-repo runs.
2. Keep hard-fail semantics; adjust guard predicate, not policy.

---

## 9. Handoff

After approval, implementation handoff to Supervisor SHALL include:

1. Exact step-level edits required in `.github/workflows/security-pr.yml`.
2. Proof logs for each failed/pass matrix case.
3. Confirmation that no files outside plan scope were required.
3. Require explicit evidence that artifact path no longer performs GHCR PR tag
   reconstruction.