# BCX Pentest Reports

Permanent release pentest reports go here after a tag candidate has passed.

Root `PENTEST.md` is temporary scratch input and must not be committed.

Required fields:

```text
Tag: vX.Y.Z
Commit: <full git commit hash>
Status: PASS
Tester: <name or team>
Date: YYYY-MM-DD
Scope: <short scope summary>
```

`scripts/validate-release-readiness.sh <tag>` checks that the report exists,
that it names the current `HEAD` or the first parent when the current commit is
only the pentest evidence commit, that `Status: PASS` is present, that `Tester`
and `Scope` are non-blank, that `Date` is present, that matching release notes
exist, that no root `PENTEST.md` scratch findings file remains, and that the
tag does not already exist locally.

## Working Flow

When implementation criteria for a version are complete, the implementation
owner stops and asks for pentest.

The maintainer runs pentest and writes temporary findings to:

```text
PENTEST.md
```

The implementation owner reviews the findings, fixes release-scope issues, and
records the scratch report into the permanent release report:

```bash
scripts/record_pentest_report.py \
  --version X.Y.Z \
  --tester "<tester>" \
  --scope "<scope>" \
  --date YYYY-MM-DD
```

Root `PENTEST.md` is deleted after the permanent digest report is reviewed.
The maintainer then decides whether to run another pentest pass or to commit
the changes and wait for GitHub.

When GitHub CI and CodeQL default setup are green, tagging is a separate
operation:

```bash
scripts/finalize_release.py --version X.Y.Z
```

The finalizer does not digest `PENTEST.md` and does not create a report. It only
runs the release gate and creates the tag.
