whitehat-security/docs/reporting.md

# Reporting contract

Every target run—pass, finding, inconclusive or abort—uses
`schemas/run-report.schema.json`. Reports include authorization and engagement
ids, target revision, posture/model, timestamps, sanitized observations,
cleanup and credential disposition. They never include response bodies,
credentials or severity.

A finding is routed to `risk-nexus` with supported facts and provenance. A
passing report is routed too because its date and target revision define the
freshness of the limited assurance. Generate the message body with:

```sh
PYTHONPATH=src python3 -m whitehat_security.cli risk-message evidence/<run>.json
```

The reporter does not edit risk-nexus grading fields. `risk-nexus` decides
whether an observation is a finding or note, and owns severity, disclosure,
review cadence and escalation.

Queue a target report without assigning severity:

```sh
PYTHONPATH=src python3 -m whitehat_security.cli deliver evidence/<run>.json --outbox outbox
```

Gate House ASM returns use a separate envelope. Render it with:

```sh
PYTHONPATH=src python3 -m whitehat_security.cli conformance-message evidence/<run>.json \
  --spec asm-assurance-targets.v1 --test-id T-01 --component access-engine
```

That command does not send the message. Subject form:
`[GH-CONFORMANCE] <test> <outcome> <target>@<revision>`. Implementation
findings still go to `risk-nexus`.

Offline calibration stays in this repository and is plainly labeled
`evidence_class: fixture`; it is not sent as if it were a target result. The
deliver command refuses fixture evidence.