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. evidence/offline-calibration.json is calibration evidence, not target assurance.

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:

   PYTHONPATH=src python3 -m whitehat_security.cli validate-engagement engagements/<record>.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. 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.