Capture audit evidence from your admin screens

# Assemble the Decosa evidence runner on our side

You are setting up the evidence runner: once per admin console an agent finds each named settings screen (read-only)
and code reads the settings we name; we approve those values as the baseline. Every quarter after that it runs with no
model: it opens each screen from its saved route, re-reads every setting, captures a stamped screenshot on a fresh load
and signs a certificate. It must run on our side, because our consoles sit behind single sign-on, conditional access,
device checks and IP allow-lists. Work step by step, show me each command before you run anything with `sudo`, and stop
to ask if a check fails.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/evidence-runner.zip (1 KB, 10 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py evidence-runner` (the api image carries the same bundle under /app/rehearsal/evidence-runner/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py evidence-runner --bundle evidence-runner.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the hosted service offers the made-up consoles only", "nine screens are captured", "exactly the four planted screens changed"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## 0. Ground rules and licences
- Runner: decosa-api (AGPL-3.0-or-later), CPU only. Browser automation: Playwright (Apache-2.0) with Chromium
  (BSD-3-Clause). Images: Pillow (MIT-CMU). Model for setup and repairs only: Qwen3.8-27B (Apache-2.0) on vLLM, or the
  hosted Decosa gateway with a `dk_` key (one receipt per call).
- Read-only by construction: the runner's browser tab blocks every write at the network level (no approval can release
  one), refuses toggles, pickers and save-like clicks, and captures each screen on a fresh load.
- Use a view-only admin role for the account the runner works under. Never give the runner a password: I sign in myself.
- Where a console's own read-only API covers a setting (Google Workspace Policy API, Microsoft Graph with
  Policy.Read.All, AWS SecurityAudit role, Okta `okta.policies.read`), prefer the API. For Microsoft 365 / Entra admin
  centers use witnessed capture (step 5) instead of agent navigation: Microsoft's Product Terms bar "scrape or ...
  other data extraction" (read 28 Sep 2026). Our own product's admin screens are fine for the agent.

## 1. Check the machine
1. Python 3.12 and `git`. For setup and repairs, either a GPU box running Qwen3.8-27B (one 96 GB card, or a 32 GB card
   with the FP8 weights) or a Decosa API key for the hosted gateway. Quarterly runs need no GPU.
2. Google Chrome (or Chromium) on the machine where I sign in to the consoles.
3. Disk: about 400 MB for the runner and Chromium, and 1-3 MB per quarterly evidence pack.

## 2. Install the runner (local helper)
```bash
git clone <decosa-api source: on request at https://decosa.ai/contact?topic=self-host>   # access required; a release with decosa_api/verticals/evidence/
cd decosa-api && python3 -m venv .venv && .venv/bin/pip install ".[testruns]"
.venv/bin/python -m playwright install chromium chromium-headless-shell
```
Model access for setup (pick one, in `~/.decosa/evidence.env`, mode 0600):
- hosted: `DECOSA_LLM_ROUTE=gateway`, `DECOSA_GATEWAY_URL=<gateway url>`, `DECOSA_GATEWAY_API_KEY=<dk_ key>`;
- our own GPU: `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://127.0.0.1:8114/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b`
  (vLLM: `vllm/vllm-openai:v0.29.0 --model nvidia/Qwen3.8-27B-NVFP4 --served-model-name qwen3.8-27b`).

## 3. Attach to the browser I already use
1. Turn on remote debugging in my normal Chrome profile: open `chrome://inspect/#remote-debugging` and tick the box.
   Chrome writes the port to the `DevToolsActivePort` file in the profile directory (macOS:
   `~/Library/Application Support/Google/Chrome/DevToolsActivePort`); its first line is the port. Chrome asks me to
   Allow each new connection: I click Allow. (Recent Chrome versions ignore `--remote-debugging-port` for the default
   profile, so don't use that flag on it.) The port listens on 127.0.0.1 only; never forward it.
2. I sign in to the console in a normal tab (SSO, MFA, device check as usual).
3. The helper opens ONE tab of its own, gates only that tab and closes it at the end. It never reads my other tabs.
   If the console signs me out mid-run, the helper stops and asks me to sign in again in its tab.

## 4. Set up once, then run each quarter
1. Write `screens.json` with me, one entry per screen we screenshot today:
   `[{"id": "mfa", "name": "2-step verification settings", "controls": ["SOC 2 CC6.1"], "settings": ["Enforcement", "New user enrollment period"]}]`.
2. Setup (add `--hosts <sso host>` if the console redirects through a sign-in host): `set -a; . ~/.decosa/evidence.env; set +a; .venv/bin/python -m decosa_api.verticals.evidence.cli setup --cdp http://127.0.0.1:<port> --origin https://<console host> --screens screens.json --user <my admin email> --out spec.json`.
   Show me every screen's `status` and `readings` in `spec.json`. I approve the values (or fix the screen list and run
   setup again). Screens marked `not_found` or flagged (page text aimed at AI agents) stay with me.
3. Every quarter: `.venv/bin/python -m decosa_api.verticals.evidence.cli certify --cdp http://127.0.0.1:<port> --spec spec.json --user <my admin email> --out evidence-<quarter>.zip`.
   Exit 0 = every screen matches the baseline; exit 1 = something changed (the manifest lists what) or a screen was not
   reached (the console changed: run setup again for that screen and approve the new baseline).
4. Unzip the pack and check `manifest.csv`; `certificate.json` verifies with `POST /testruns/verify` on any Decosa API
   (or our own, step 6), and the CMMC evidence map reads it as a test-run certificate.

## 5. Witnessed capture (consoles whose terms bar agents)
`.venv/bin/python -m decosa_api.verticals.evidence.cli witness --cdp http://127.0.0.1:<port> --origin https://<console host> --user <me> --out witnessed.zip`:
I click to each screen myself and press Enter; it captures that tab, stamps URL, UTC time and "witnessed", and signs.

## 6. Optional: inside the network as a service
Run the decosa-api image (`docker build -f docker/api/Dockerfile --build-arg WITH_BROWSER=1 -t decosa-api:local .`) on a
host inside our network with `DECOSA_HOST=127.0.0.1`, a named data volume, and the model settings above; the same routes
(`/evidence/info`, `/testruns/verify`) are then available to our team. Bind to 127.0.0.1 or put it behind our SSO proxy.

## 7. Smoke test
1. `.venv/bin/python -m pytest -q tests/test_evidence.py tests/test_cu_readonly.py tests/test_cuharness.py`: all pass
   (made-up consoles, no network, no model).
2. Tell me the setup time per screen, the quarterly run time, and the certificate check summary you saw.