whitehat-security/docs/operator-runbook.md

Operator runbook

This runbook does not authorize a target. Read and follow 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.

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 and evidence/offline-capacity-calibration.json. Those files are calibration evidence, not target assurance.

Test plane

Live execution is gated by docs/test-plane.md. Before any target run:

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, approved and owner-acknowledged engagement ID. A proposed record and a record with pending target-owner acknowledgement fail closed. 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:

   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 --receipt <custody-receipt.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.