[codex] Add public demo proof artifacts

README.md

@@ -61,6 +61,24 @@ Next step: use least-privilege workflow permissions or document an exception.
 
 Machine-readable artifacts preserve the same evidence for CI, dashboards, proof packs, SARIF, and AI review.
 
+## Public Proof Artifacts
+
+The repository includes sanitized fixture scans so reviewers can inspect real output without running private code:
+
+| Fixture | Status | Purpose |
+| --- | --- | --- |
+| `safe-agent` | `approved` | Shows a clean repository passing the configured agent-access checks. |
+| `risky-ci-agent` | `blocked` | Shows a privileged pull request workflow with write access being stopped. |
+| `risky-mcp-agent` | `needs_review` | Shows an MCP server receiving a credential reference and requiring human review. |
+
+Start with [the public fixture manifest](docs/demo-artifacts/public-fixture-scans/manifest.json), then inspect the blocked CI [summary](docs/demo-artifacts/public-fixture-scans/risky-ci-agent/summary.md), [permit](docs/demo-artifacts/public-fixture-scans/risky-ci-agent/permit.yaml), and [raw findings](docs/demo-artifacts/public-fixture-scans/risky-ci-agent/raw-findings.json).
+
+Regenerate them with:
+
+```bash
+uv run python tools/build_public_demo_artifacts.py
+```
+
 ## What It Checks
 
 - MCP server configuration and tool boundaries
@@ -223,6 +241,7 @@ Developer docs:
 - `docs-site/` - curated Fumadocs site for developers and AI agents
 - `AGENTS.md` - repo guidance for AI agents
 - `llms.txt` - compact AI-readable docs map
+- [Public Demo Artifacts](docs-site/content/docs/public-demo-artifacts.mdx)
 - [AI Analysis Guide](docs/ai-analysis-guide.md)
 - [Artifact Reference](docs/artifact-reference.md)
 

docs-site/content/docs/index.mdx

@@ -46,5 +46,6 @@ Deep Agent reports explain scanner artifacts. They do not replace scanner eviden
 ## Related pages
 
 - [Quickstart](/docs/quickstart)
+- [Public Demo Artifacts](/docs/public-demo-artifacts)
 - [Agent Permit Model](/docs/agent-permit-model)
 - [Evidence and Artifacts](/docs/evidence-and-artifacts)

docs-site/content/docs/meta.json

@@ -5,6 +5,7 @@
     "index",
     "quickstart",
     "first-scan-walkthrough",
+    "public-demo-artifacts",
     "---Core Concepts---",
     "agent-permit-model",
     "finding-statuses",

docs-site/content/docs/public-demo-artifacts.mdx

@@ -0,0 +1,94 @@
+---
+title: Public Demo Artifacts
+description: Sanitized scan outputs that show PermitGraph working on safe fixture repositories.
+---
+
+## What this is
+
+Public demo artifacts are committed examples of real scanner output.
+
+They come from test fixtures, not private repositories. The generator runs PermitGraph, strips machine-local paths, and publishes selected artifacts under `docs/demo-artifacts/public-fixture-scans/`.
+
+## When to use it
+
+Use these artifacts when you need to show what PermitGraph produces before running it on a new repository.
+
+They are useful for:
+
+- README and documentation examples
+- sales or investor demos
+- issue reports about scanner behavior
+- AI agents trying to understand artifact shape
+
+Do not treat them as customer audit evidence. They are fixture scans.
+
+## Command or example
+
+Regenerate the examples from the repository root:
+
+```bash
+uv run python tools/build_public_demo_artifacts.py
+```
+
+The current demo set includes:
+
+| Fixture | Permit status | What it proves |
+| --- | --- | --- |
+| `safe-agent` | `approved` | A repository with no configured agent-access risk passes. |
+| `risky-ci-agent` | `blocked` | A privileged pull request workflow with write access is stopped. |
+| `risky-mcp-agent` | `needs_review` | A local MCP server receiving a credential reference requires human review. |
+
+## Output to expect
+
+The generator writes:
+
+```text
+docs/demo-artifacts/public-fixture-scans/manifest.json
+docs/demo-artifacts/public-fixture-scans/<fixture>/cli-output.txt
+docs/demo-artifacts/public-fixture-scans/<fixture>/summary.md
+docs/demo-artifacts/public-fixture-scans/<fixture>/permit.yaml
+docs/demo-artifacts/public-fixture-scans/<fixture>/raw-findings.json
+docs/demo-artifacts/public-fixture-scans/<fixture>/graph-paths.json
+docs/demo-artifacts/public-fixture-scans/<fixture>/controls.json
+docs/demo-artifacts/public-fixture-scans/<fixture>/run-metrics.json
+```
+
+Open the manifest first:
+
+[Public fixture scan manifest](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/manifest.json)
+
+Then compare the blocked CI example:
+
+- [CLI output](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/risky-ci-agent/cli-output.txt)
+- [Summary](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/risky-ci-agent/summary.md)
+- [Permit](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/risky-ci-agent/permit.yaml)
+- [Raw findings](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/risky-ci-agent/raw-findings.json)
+- [Graph paths](https://github.com/IntelIP/agent-permit-office/blob/main/docs/demo-artifacts/public-fixture-scans/risky-ci-agent/graph-paths.json)
+
+## How to interpret it
+
+Read the artifacts in this order:
+
+1. `cli-output.txt`: fast proof that the command ran and what status it returned.
+2. `summary.md`: human-readable decision summary.
+3. `permit.yaml`: the allow, forbid, and approval conditions.
+4. `raw-findings.json`: exact scanner findings with evidence locations.
+5. `graph-paths.json`: source-to-sink paths, such as credential to MCP server.
+6. `controls.json`: review controls that must pass before approval.
+7. `run-metrics.json`: counts used by dashboards and CI.
+
+The important pattern: scanner output owns the decision. Deep Agent review may explain these artifacts later, but it should not invent a different permit status.
+
+## Common mistakes
+
+- Presenting fixture artifacts as customer evidence.
+- Editing the artifacts by hand instead of regenerating them.
+- Publishing raw `.agent-permit/` folders from private repos.
+- Showing only `summary.md` without `raw-findings.json` and `graph-paths.json`.
+
+## Related pages
+
+- [Quickstart](./quickstart)
+- [Evidence and Artifacts](./evidence-and-artifacts)
+- [Review Findings](./review-findings)
+- [Artifact Reference](./artifact-reference)

docs/demo-artifacts/public-fixture-scans/README.md

@@ -0,0 +1,15 @@
+# Public Fixture Scans
+
+These sanitized artifacts are generated from test fixtures with:
+
+```bash
+uv run python tools/build_public_demo_artifacts.py
+```
+
+They are safe demo evidence, not customer audit records.
+
+| Fixture | Status | Findings | Graph paths | Controls |
+| --- | --- | ---: | ---: | ---: |
+| safe-agent | approved | 0 | 0 | 0 |
+| risky-ci-agent | blocked | 4 | 1 | 5 |
+| risky-mcp-agent | needs_review | 2 | 1 | 3 |

docs/demo-artifacts/public-fixture-scans/manifest.json

@@ -0,0 +1,37 @@
+{
+  "description": "Sanitized scanner outputs generated from repository fixtures. These files show real PermitGraph decisions without publishing private repositories or generated local state.",
+  "fixtures": [
+    {
+      "artifact_dir": "docs/demo-artifacts/public-fixture-scans/safe-agent",
+      "controls": 0,
+      "findings": 0,
+      "graph_paths": 0,
+      "id": "safe-agent",
+      "label": "Approved repository",
+      "permit_status": "approved",
+      "why": "No configured agent-access risk matched."
+    },
+    {
+      "artifact_dir": "docs/demo-artifacts/public-fixture-scans/risky-ci-agent",
+      "controls": 5,
+      "findings": 4,
+      "graph_paths": 1,
+      "id": "risky-ci-agent",
+      "label": "Blocked CI automation",
+      "permit_status": "blocked",
+      "why": "A pull_request_target workflow grants write permissions and references a token."
+    },
+    {
+      "artifact_dir": "docs/demo-artifacts/public-fixture-scans/risky-mcp-agent",
+      "controls": 3,
+      "findings": 2,
+      "graph_paths": 1,
+      "id": "risky-mcp-agent",
+      "label": "MCP credential review",
+      "permit_status": "needs_review",
+      "why": "A local MCP server receives a credential reference and uses an unpinned package command."
+    }
+  ],
+  "generator": "tools/build_public_demo_artifacts.py",
+  "name": "PermitGraph public fixture scans"
+}

docs/demo-artifacts/public-fixture-scans/risky-ci-agent/cli-output.txt

@@ -0,0 +1,22 @@
+Agent Permit Office
+Status: scan_complete
+Target: tests/fixtures/risky-ci-agent
+Run ID: public-demo-risky-ci-agent
+Artifacts: tests/fixtures/risky-ci-agent/.agent-permit/runs/public-demo-risky-ci-agent
+Files indexed: 5
+High signal files: 2
+Skipped files/dirs: 1
+MCP servers: 0
+Credential refs: 0
+Prompt findings: 0
+CI findings: 4
+Findings: 4
+Graph nodes: 6
+Graph edges: 1
+Graph paths: 1
+Controls: 5
+Permit status: blocked
+Summary: tests/fixtures/risky-ci-agent/.agent-permit/runs/public-demo-risky-ci-agent/summary.md
+Metrics: tests/fixtures/risky-ci-agent/.agent-permit/runs/public-demo-risky-ci-agent/run-metrics.json
+Events: tests/fixtures/risky-ci-agent/.agent-permit/analytics-events.jsonl
+Next: review summary.md and risk-report.md

docs/demo-artifacts/public-fixture-scans/risky-ci-agent/controls.json

@@ -0,0 +1,144 @@
+{
+  "controls": [
+    {
+      "evidence": [
+        {
+          "command": null,
+          "config_key": null,
+          "context_note": null,
+          "line_end": 4,
+          "line_start": 4,
+          "package": null,
+          "path": ".github/workflows/agent.yml",
+          "permission_scope": null,
+          "redacted_snippet": "pull_request_target:",
+          "secret_name": null,
+          "workflow_event": null,
+          "workflow_job": null
+        },
+        {
+          "command": null,
+          "config_key": null,
+          "context_note": "pull_request_target",
+          "line_end": 7,
+          "line_start": 7,
+          "package": null,
+          "path": ".github/workflows/agent.yml",
+          "permission_scope": "write-all",
+          "redacted_snippet": "permissions: write-all",
+          "secret_name": null,
+          "workflow_event": "pull_request_target",
+          "workflow_job": null
+        }
+      ],
+      "id": "control:ci-least-privilege:finding:ci-pr-target-write-token:.github/workflows/agent.yml:7",
+      "name": "CI least-privilege workflow control",
+      "rationale": "Workflow trigger, token, or secret use is privileged.",
+      "recommendation": "Use trusted PR context and least-privilege workflow permissions.",
+      "related_finding_ids": [
+        "finding:ci-pr-target-write-token:.github/workflows/agent.yml:7"
+      ],
+      "related_path_ids": [],
+      "status": "missing",
+      "target_id": "workflow:.github/workflows/agent.yml:4:ci-pr-target-write-token"
+    },
+    {
+      "evidence": [
+        {
+          "command": null,
+          "config_key": null,
+          "context_note": "pull_request_target",
+          "line_end": 4,
+          "line_start": 4,
+          "package": null,
+          "path": ".github/workflows/agent.yml",
+          "permission_scope": null,
+          "redacted_snippet": "pull_request_target:",
+          "secret_name": null,
+          "workflow_event": "pull_request_target",
+          "workflow_job": null
+        }
+      ],
+      "id": "control:ci-least-privilege:finding:ci-pull-request-target:.github/workflows/agent.yml:4",
+      "name": "CI least-privilege workflow control",
+      "rationale": "Workflow trigger, token, or secret use is privileged.",
+      "recommendation": "Use trusted PR context and least-privilege workflow permissions.",
+      "related_finding_ids": [
+        "finding:ci-pull-request-target:.github/workflows/agent.yml:4"
+      ],
+      "related_path_ids": [],
+      "status": "missing",
+      "target_id": "workflow:.github/workflows/agent.yml:4:ci-pull-request-target"
+    },
+    {
+      "evidence": [
+        {
+          "command": null,
+          "config_key": null,
+          "context_note": "events=pull_request_target; job=agent-review",
+          "line_end": 16,
+          "line_start": 16,
+          "package": null,
+          "path": ".github/workflows/agent.yml",
+          "permission_scope": null,
+          "redacted_snippet": "GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}",
+          "secret_name": "GITHUB_TOKEN",
+          "workflow_event": "pull_request_target",
+          "workflow_job": "agent-review"
+        }
+      ],
+      "id": "control:ci-least-privilege:finding:ci-secret-reference:.github/workflows/agent.yml:16",
+      "name": "CI least-privilege workflow control",
+      "rationale": "Workflow trigger, token, or secret use is privileged.",
+      "recommendation": "Use trusted PR context and least-privilege workflow permissions.",
+      "related_finding_ids": [
+        "finding:ci-secret-reference:.github/workflows/agent.yml:16"
+      ],
+      "related_path_ids": [],
+      "status": "missing",
+      "target_id": "workflow:.github/workflows/agent.yml:16:ci-secret-reference"
+    },
+    {
+      "evidence": [
+        {
+          "command": null,
+          "config_key": null,
+          "context_note": "events=pull_request_target",
+          "line_end": 7,
+          "line_start": 7,
+          "package": null,
+          "path": ".github/workflows/agent.yml",
+          "permission_scope": "write-all",
+          "redacted_snippet": "permissions: write-all",
+          "secret_name": null,
+          "workflow_event": "pull_request_target",
+          "workflow_job": null
+        }
+      ],
+      "id": "control:ci-least-privilege:finding:ci-write-all-permissions:.github/workflows/agent.yml:7",
+      "name": "CI least-privilege workflow control",
+      "rationale": "Workflow trigger, token, or secret use is privileged.",
+      "recommendation": "Use trusted PR context and least-privilege workflow permissions.",
+      "related_finding_ids": [
+        "finding:ci-write-all-permissions:.github/workflows/agent.yml:7"
+      ],
+      "related_path_ids": [],
+      "status": "missing",
+      "target_id": "workflow:.github/workflows/agent.yml:7:ci-write-all-permissions"
+    },
+    {
+      "evidence": [],
+      "id": "control:path-ci-privilege-boundary:path:a87e710d72ed",
+      "name": "Privileged CI boundary control",
+      "rationale": "Workflow file defines a privileged CI execution path.",
+      "recommendation": "Remove write permissions or privileged PR context before running agent workflows.",
+      "related_finding_ids": [],
+      "related_path_ids": [
+        "path:a87e710d72ed"
+      ],
+      "status": "missing",
+      "target_id": "workflow:.github/workflows/agent.yml"
+    }
+  ],
+  "scan_run_id": "public-demo-risky-ci-agent"
+}