infra/license-bot/SECURITY.md

# Verification — AGPL license bot, merge gate and key exposure

Measured on the development VM (Gitea **1.27.2**, runner `alpine-runner`,
label `alpine-latest:docker://node:alpine`) on 2026-10-07. Everything below was
observed, not inferred; each test lists the method, the raw observation and the
verdict. Where a result is version- or host-specific it is called out.

Two questions are answered:

1. **Is the bot's `license-bot / addlicense` status authoritative — can a PR that
   is not supposed to be trusted fake a green?**
2. **Can anyone get a key out?** Masking in logs is not evidence of safety: the
   only question is whether a value is reachable by an actor and can leave the
   host.

---

## Test 1 — authoritativeness / "fake greens"

### T1.1 An untrusted (fork) PR run cannot post a commit status

- **Hypothesis.** A fork PR run's `secrets.GITHUB_TOKEN` has no write access, so
  it cannot create the status the gate depends on.
- **Method.** Workflow on a fork branch (`admin/license-bot-lab:forge-test`)
  running as a fork PR:
  `POST /api/v1/repos/Dcntrlized/license-bot-lab/statuses/<head_sha>` with
  `{"context":"license-bot / addlicense","state":"success"}` using
  `${{ secrets.GITHUB_TOKEN }}`; the same call again against the fork's own repo;
  then `GET /repos/{repo}/commits/{sha}/statuses` read back by the admin API.
- **Observation.** `BASE_HTTP_403` and `FORK_HTTP_403`, body
  `{"message":"user should have a permission to write to a repo"}`; no
  `license-bot / addlicense` status ever appeared on the PR head. The same fork
  run *can* post a comment (`201`).
- **Verdict.** PASS for the platform mechanism: a fork PR cannot produce the
  suffix-free context the bot owns. It can still post *comments*.

### T1.2 A same-repo (in-repo) PR run can post any context

- **Hypothesis.** A contributor with repository write access can forge the bot's
  exact context through their own workflow.
- **Method.** In-repo branch workflow, `POST .../statuses/<head_sha>` with
  `{"context":"license-bot / addlicense","state":"success"}`.
- **Observation.** `FORGE_HTTP_201`; `GET .../statuses` then listed
  `success license-bot / addlicense` with the description the workflow set
  (`forged by a contributor workflow`).
- **Verdict.** FAIL by design: any writer can forge any context. Write access is
  the trust boundary (a writer can equally edit the workflow or push directly);
  the gate protects against *untrusted* actors and honest mistakes, not against
  collaborators.

### T1.3 Required branch-protection checks are enforced on the merge API

- **Hypothesis.** With branch protection requiring a context that nobody posts, a
  normal writer's merge is refused — i.e. required checks are a real gate.
- **Method.** `POST /repos/{r}/branch_protections`
  (`branch_name=main`, `enable_status_check=true`,
  `status_check_contexts=["nobody-posted-this-context"]`), then
  `POST /repos/{r}/pulls/{n}/merge` as the non-admin collaborator `gateuser`
  (`Authorization: token <gateuser>`), `{"Do":"merge"}`.
- **Observation.** `405 {"message":"Not all required status checks successful"}`.
  Removing the requirement and re-merging succeeded (`200`).
- **Verdict.** PASS: branch protection is enforced on the REST merge path for a
  normal writer. Caveat: admins can override, and contexts match by exact string.
- **Re-measured 2026-10-08 on a protected throwaway branch** (`gate-target`,
  context `license-bot / addlicense`), which pins the fail-closed property the
  webhook-only design relies on:
  | State of the required context | `POST /pulls/57/merge` |
  |---|---|
  | **absent** (bot down, never posted) | `405 Not all required status checks successful` |
  | `pending` | `405` |
  | `success` | `200` |
  Cleanup: protection removed, both probe branches deleted, `main` untouched.
  So "the bot is down" means "no status" means "no merge" — an unlicensed pull
  request cannot be merged by accident.

### T1.4 A *required scoped workflow* is NOT enforced on the merge API (1.27.2)

- **Hypothesis.** If a scoped workflow is registered from a source repo and marked
  required, a failing run blocks merges — making it the natural public gate.
- **Method.** Source repo `Dcntrlized/ci-workflows` with
  `.gitea/scoped_workflows/gate.yml` (a job that always exits 1). Registered on
  `/org/Dcntrlized/settings/actions/scoped-workflows` via
  `POST .../add` `repo_name=ci-workflows` (bare name only — `owner/name` and the
  numeric id are rejected `400 Repository not found.`), then marked required via
  `POST .../required` with `repo_id`, `workflow_ids=gate.yml`,
  `required_workflow_ids=gate.yml`,
  `required_patterns[gate.yml]="Dcntrlized/ci-workflows: Gate / *"`. Consumer:
  throwaway `Dcntrlized/gate-lab`, PR with a real failing status
  `Dcntrlized/ci-workflows: Gate / check (pull_request) = failure` on the head.
- **Observation.** The PR page showed *"Some required checks failed"*, but
  `POST /pulls/{n}/merge` returned **200** — both for the site admin (PR B) and
  for the non-admin writer `gateuser` (PR 4, head `7c00336c`). A required pattern
  that never posts does not block either.
- **Verdict.** FAIL: on 1.27.2 required scoped workflows are a UI-only signal,
  not an API-enforced gate. Do not rely on them. (Upstream 28.1.0 not tested.)

### T1.5 Scoped workflows do not leak consumer secrets to fork PRs

- **Hypothesis.** A scoped workflow sourced from another repo might receive the
  consumer's repo/org secrets even on a fork PR.
- **Method.** A scoped `secret-probe.yml` registered from `ci-workflows` tested
  presence of the consumer's repo secret, an org secret and `secrets.GITHUB_TOKEN`
  on a fork PR and on an in-repo PR (presence via `[ -n "$VAR" ]`, so no value is
  needed).
- **Observation.** Fork PR: `PROBE_secret=[]`,
  `PROBE_org_secret_present=[false]`, `PROBE_token_present=[true]`. In-repo PR:
  `PROBE_secret=[***]`, `PROBE_org_secret_present=[true]` (values masked in the
  log).
- **Verdict.** PASS: scoped workflows inherit the consumer's secret rules; forks
  get none. (Masking of the in-repo log is cosmetic — see Test 2.)

### T1.6 Positive control — the bot's own status

- **Method.** The real bot (own account token) posts
  `POST /repos/{r}/statuses/<sha>` with its context in the same lab and the status
  is read back via the API.
- **Observation.** Context is exactly `license-bot / addlicense`, no `(event)`
  suffix, description `license headers added by the bot`.
- **Verdict.** The context the gate should require is the one T1.1 shows forks
  cannot create.

### Test 1 conclusions

| Test | Result |
|---|---|
| T1.1 fork cannot post a status | 403 — PASS |
| T1.2 in-repo writer can forge any context | 201 — FAIL by design (write = trust) |
| T1.3 required branch-protection check blocks a writer's merge | 405 — PASS |
| T1.4 required scoped workflow blocks a merge | 200 — FAIL (UI-only on 1.27.2) |
| T1.5 scoped fork runs get no consumer secrets | no secret present — PASS |
| T1.6 bot context identifier | `license-bot / addlicense` (suffix-free) |

**Gate to use:** branch protection on the default branch requiring the exact
context `license-bot / addlicense`, plus at least one approval so an author cannot
self-merge. It is enforced on the merge API (T1.3) and unforgeable by fork PRs
(T1.1); it does not stop a collaborator (T1.2) or an admin.

**Not covered by Test 1:** whether a run *without* write access can reach secrets
by other means — that is Test 2, and the answer changes the conclusion above,
because an attacker who obtains the admin token can forge any status.

---

## Test 2 — key exposure (reachability and egress, not masking)

Methodology: unique canary values are planted as a repo secret and an org secret,
a workflow prints their **lengths** and posts them **base64-encoded to the PR as a
comment** through the run token (a real outbound HTTP POST, the "malicious site"
model). The same probe runs from an in-repo PR and from a fork PR. A control step
proves the network path and the runner's capabilities, so a "nothing received"
result means "nothing to send", not "no channel".

### T2.1 An in-repo PR exfiltrates a repo secret and an org secret

- **Observation.** `REPO_CANARY_LEN=23 ORG_CANARY_LEN=26 BOT_TOKEN_LEN=0
  RUN_TOKEN_LEN=40`; the log lines `REPO_CANARY_B64=***` /
  `ORG_CANARY_B64=***` (masked) but `EXFIL_POST_HTTP=201`; the created comment
  body decoded to exactly `CANARY-61ca3f58dd2d9ae3` and
  `ORGCANARY-d0c7e3ad5b14af5d`.
- **Verdict.** FAIL (severe). Log masking protects nothing; the values left the
  host. Any collaborator who can open an in-repo PR reads every repo/org secret.

### T2.2 A fork PR gets no repo/org secrets

- **Observation.** `LEN repo=0 org=0 run_token=40`,
  `EXFIL_POST_HTTP=201`, comment
  `FORK EXFIL probe: repo_canary_len=0 org_canary_len=0 run_token_len=40`.
- **Verdict.** PASS for direct secret access: the platform withholds repo/org
  secrets from fork runs; the run token present is base-repo read-only.

### T2.3 CRITICAL — a fork PR escapes the runner sandbox through the Docker socket

- **Hypothesis.** Untrusted builds might still reach host resources through the
  runner.
- **Method.** From the *fork* PR job: `ls -l /var/run/docker.sock`;
  `apk add --no-cache docker-cli`; `docker ps --format '{{.Names}}'`; then
  `docker run --rm -v /:/host alpine sh -c 'echo HOST_READ_OK;
  cat /host/etc/hostname; ls /host | head -5'`.
- **Observation.** Socket present: `srw-rw---- 1 root 969 /var/run/docker.sock`.
  `docker ps` listed `GITEA-ACTIONS-TASK-…` (the job), `gitea_runner-runner-1`
  and **`gitea`**. The host-root bind mount worked: `HOST_READ_OK`,
  `dcntrlized_dev`, `bin boot dev etc home`.
- **Verdict.** CRITICAL FAIL. A fork PR — no write access, no secrets — has
  root-equivalent access to the runner host: read/write the host filesystem
  (including Gitea's data directory and database, i.e. every org/repo secret and
  admin token), `docker exec` any container (including `gitea`) and start
  privileged containers. This defeats T2.2 in practice: secrets are reachable
  indirectly, and the T1.1 "forks cannot fake a status" property is moot once the
  attacker steals an admin token.
- **Remediation (required before opening the repos).** In the runner config
  (`/home/admin/gitea_runner/config.yaml` on the dev VM) set
  `container.docker_host: "-"`. Upstream documents this exact value as "runner
  will find an available docker host automatically, but won't mount it into the
  job and action containers" (gitea runner `config.example.yaml`, and
  `run_context.go`: the socket bind is skipped when `containerDaemonSocket()`
  returns `-`). Keep `container.valid_volumes: []` (an empty list means no
  workflow-declared volume can be mounted) and leave `container.privileged:
  false`. Then restart the runner and re-run T2.3: `ls /var/run/docker.sock` must
  fail and a `docker` CLI in the job must not reach a daemon. Until that holds,
  no other mitigation matters. A rootless/DIND or VM-isolated runner is the
  stronger option for public repositories.
- **Status: FIXED and verified 2026-10-07.** The hardened runner configs are
  versioned in the root repo at `infra/gitea-runner/` and deployed on the dev VM
  (`container.docker_host: "-"`, an `--internal` job network with Gitea as its
  only attached service, `privileged: false`, `valid_volumes: []`, and a job
  image with the tools baked in so no workflow needs egress). Measured from a
  job after the change: `SOCKET_ABSENT`; `example.com` does not even resolve;
  the host (`192.168.122.183:3000`) is `Network unreachable`; `gitea:3000`
  answers `200`; the job route is only `172.31.240.0/24 dev eth0 scope link`;
  and workflows declaring `--network host`, `--privileged` or `--volume /etc/...`
  are ignored by the runner. The runner was re-registered so the job context URL
  is `gitea:3000` (the host address is unreachable by design). The fork probe
  that previously read the host now finds neither the socket nor a network path.
  Verification runs on the lab repo: isolation probe run 179; scoped
  `license-check.yml` run 180 and repo `.gitea/workflows/license.yml` run 201
  both succeed with `SERVER: http://gitea:3000`. The two advisory files share
  `concurrency.group: license-headers-<PR>`, so exactly one of them runs per PR
  (the scoped one normally wins; the repo file takes over if the scoped workflow
  is unregistered) — a `cancelled` repo run is the expected dedup, not a
  failure.

### T2.4 CRITICAL — the org `TOKEN` secret is the admin/bot token

- **Hypothesis.** The token the bot uses might also sit in Actions secrets, where
  any PR workflow can read it.
- **Method.** An in-repo PR workflow printed `len` and `sha256` of
  `secrets.TOKEN` (no plaintext); the same hash was computed locally for the
  token in `Maestro/.env` that drives the bot.
- **Observation.** `ORG_TOKEN_LEN=40 SHA=fd539c2ffd50376f6747a05424d4e5fa6e02c67da35cebf3001a2a19524418ad`;
  local bot token: `len=40
  sha=fd539c2ffd50376f6747a05424d4e5fa6e02c67da35cebf3001a2a19524418ad` —
  identical. (`BOT_TOKEN_LEN=0`: it is not duplicated under another name.)
- **Verdict.** CRITICAL FAIL. The site-admin token that authenticates the bot is
  readable by every in-repo PR workflow, and by any fork PR through T2.3.
- **Remediation.** Rotate it; give the bot a dedicated least-privilege account
  (`write:repository` + `read:issue` + `write:issue`, scoped to the five repos);
  stop storing that token as an org/repo Actions secret (release publishing needs
  a separate, approval-gated or push-only path).
- **Update 2026-10-08.** The bot no longer has any Actions dependency: it is the
  webhook-only service described below, and its token lives only in the
  container's environment on the Gitea host. The org `TOKEN` secret is now used
  by nothing except `release.yaml`'s registry auth, so it can be deleted once
  that workflow gets its own `write:package` token. The remaining work is the
  **rotation** of the bot token onto a dedicated non-admin account.

### T2.5 Egress and runner capability control

- **Observation.** From the job: `NET_GITEA=200`, `NET_INTERNET=200`
  (`http://example.com` reachable), `HAS_DOCKER=none` before installing the CLI.
- **Verdict.** A working outbound channel exists, so the negative result in T2.2
  is meaningful, and the positive results in T2.1/T2.4 are exfiltration, not a
  logging artifact.

### Test 2 conclusions

| Test | Reachable | Left the host | Result |
|---|---|---|---|
| T2.1 in-repo PR, repo+org secrets | yes | yes (HTTP 201, comment) | FAIL — masking is cosmetic |
| T2.2 fork PR, repo/org secrets | no | n/a (channel worked, 201) | PASS for direct access |
| T2.3 fork PR, Docker socket / host root | yes | yes (host FS read) | CRITICAL — runner sandbox escape |
| T2.4 org `TOKEN` == bot/admin token | yes (in-repo) | yes | CRITICAL — rotate and relocate |
| T2.5 egress control | yes | — | confirms the tests above |

**Net:** the bot's design is right (separate revertable commit, exact suffix-free
status context, no token in the repo), but on this host an untrusted pull request
can read the whole machine, so no claim of "no key leakage" or "unforgeable gate"
holds until the runner is fixed. Order of work: **T2.3 remediation → token
rotation/T2.4 → branch protection on `license-bot / addlicense` → re-test.**

---

## Update 2026-10-08 — webhook-only v0.0.1

The service was folded down to one trigger and one process, which removes the
last piece of the exposure story that lived in Actions:

- **Webhooks are the only trigger.** Gitea delivers HMAC-signed `pull_request`
  events to `http://license-bot:8080/hook`; the bot verifies
  `X-Gitea-Signature` and ignores duplicate `X-Gitea-Delivery` ids. A check that
  did not run therefore means the service was down, not that some other
  component failed.
- **Startup reconciliation replaces polling.** On boot the bot scans the open
  pull requests of every allowlisted repository and processes those whose head
  does not already carry a successful `license-bot / addlicense` status. The
  commit status is the durable record of what the bot has resolved, so a
  delivery lost while it was down, or a `pending` left by a crash, is repaired
  without a cursor file and without a polling loop.
- **No arguments.** The binary takes no flags; everything is environment driven
  (`v0.0.1`).
- **Reachability, measured on this instance.** A job/pod on the runner's
  `--internal` job network reached a sidecar published under a name alias
  (`HEALTH=ok`) and an unauthenticated request was rejected (`401`), while the
  host IP and the internet stayed unreachable — so a sidecar/service on Gitea's
  own Docker network is reachable by Gitea without widening the job network's
  egress.
- **Advisory workflows are gone.** The read-only per-repository
  `.gitea/workflows/license.yml` and the scoped `license-check.yml` were
  removed: they were never the gate (T1.4) and the status is what branch
  protection enforces (T1.3).
- **The gate** is still branch protection requiring the exact context
  `license-bot / addlicense`; the absent-status case measured above is what makes
  it fail-closed. Required approvals are configured separately by the operator.