whitehat-security/docs/operator-runbook.md

# Operator runbook

This runbook does not authorize a target. Read and follow
[`rules-of-engagement.md`](rules-of-engagement.md) first.

## Offline calibration

The calibration is safe to run without target authorization. It opens no
socket and uses only synthetic in-process services created by this repository.

```sh
make check
make fixture-evidence
```

Success requires every read/write probe to pass against the enforcing fixture
and to produce a finding against the fixture with its tenant predicate removed.
`make fixture-evidence` also writes `evidence/offline-e3-calibration.json`.
Both files are calibration evidence, not target assurance.

## Test plane

Live execution is gated by [`docs/test-plane.md`](test-plane.md). Before any
target run:

```sh
PYTHONPATH=src python3 -m whitehat_security.cli validate-targets targets
PYTHONPATH=src python3 -m whitehat_security.cli kill-switch
```

`admit-plane` must succeed against a **new** engagement ID. The default live
broker is unconnected and fails closed without requesting a credential.
Create `plane/KILL` to abort independently of the runner.

Cancelled IDs `WH-ENG-20260821-AUDIT-E2` and `WH-ENG-20260821-TENANT-E2` are
retired.

## Prepare a target run

1. Select the target's probe pack and review every route with its owner.
2. Copy `engagements/template.json` to a dated record. Resolve every field;
   placeholders are invalid.
3. Record operator approval and a target-owner acknowledgement after approval.
4. Provision only the two disposable tenants/objects named in the record.
5. Obtain the ordinary modeled credential through its custody lane. Do not put
   its value in the record or shell history.
6. Validate within the approved window, then admit the plane:

   ```sh
   PYTHONPATH=src python3 -m whitehat_security.cli validate-engagement engagements/<record>.json
   PYTHONPATH=src python3 -m whitehat_security.cli admit-plane engagements/<record>.json targets/<target>.json
   ```

7. Confirm target identity/revision and probe attribution before the first
   hostile operation. If either is uncertain, abort.

## Execute

Execution adapters are target-specific because identity binding is part of
the property under test. An adapter must implement the `DifferentialProbe`
contract: owner request, attacker request, absent-object reference, fixture
markers, and (for writes) a tenant-B state oracle. It must call
`Engagement.permits()` immediately before each route and obey the recorded
rate/concurrency limit.

Run owner and absent controls before the attacker request. Keep response bodies
only in memory. Persist the observation produced by `execute()`: status,
content type, count, schema paths, run-local digest and fixture-match count.

Stop immediately on any abort condition in the rules. Do not investigate an
unexpected response by broadening routes, identities, discovery, or privilege.

## Close and report

- Delete only recorded fixtures and verify their absence.
- Revoke the lease or record its bounded expiry.
- Set the overall outcome to `finding` if any probe finds exposure or mutation;
  `aborted` on an abort; `inconclusive` when controls or cleanup cannot be
  proven; otherwise `pass`.
- Validate the record against `schemas/run-report.schema.json`.
- Route both passing and finding target reports to `risk-nexus`; never assign
  severity. Queue the delivery with `whitehat deliver <report.json>` (fixture
  calibration is refused). The message formatter is
  `whitehat risk-message <report.json>`.
- Schedule the next run from the target's declared cadence.

No target run is complete until its dated report and risk-nexus delivery are
both recorded.