whitehat-security/INTENT.md

# INTENT — whitehat-security

## Why this repo exists

`whitehat-security` is the estate's **adversarial evidence facility**. It
attacks the estate's own systems, on a schedule, to find out whether the
security properties they claim are actually true.

It exists because of a specific gap. NetKingdom's *Tenancy Posture* standard
splits evidence into two kinds: **mechanical** — a structural assertion a
machine can make, which belongs in each repo's own CI — and **adversarial** —
a semantic claim that requires setting up hostile conditions and observing what
happens. Every repo can produce the first. **No repo can honestly produce the
second about itself**, and the framework's most severe open question has been
sitting unowned for exactly that reason: who verifies that a consumer's tenant
boundary actually holds.

Two repos were asked and both correctly declined, on the grounds that a service
which grows fleet responsibilities because it happened to be nearby is how
boundaries erode. They were right. The work needed a home of its own.

## Independence is the point

A repo testing its own boundary grades its own homework.

`rapp-postgres` wrote fifteen adversarial probes against its own isolation
model and found four real defects in its own provisioning SQL. That is good
work and it is still the author checking their own homework — the probes most
worth having are the ones an author would not think to write, because the same
assumption that produced the defect produces the blind spot.

So this repo is **independent by construction**:

- It does not take a repo's declared posture as true. It tests the claim.
- It is not owned by the repo whose canon it verifies. NetKingdom owns the
  tenancy framework; a facility verifying conformance to that framework must
  not report to it, or the self-grading problem simply moves up one level.
- It reports findings to `risk-nexus`, which owns severity and disclosure. It
  does not decide how bad its own findings are, for the same reason.

**Proposed owner: `the-custodian`**, consistent with `policy-nexus` and
`risk-nexus`, and deliberately not NetKingdom. To be confirmed.

## What it owns

- **Adversarial evidence artifacts.** The tests that produce the evidence the
  Tenancy Posture ladders require but no repo can self-certify:
  cross-tenant read and write attempts (E2), row-level-security conformance
  under attack (E3), per-tenant credential confinement (E4),
  noisy-neighbour characterisation (P1/P2), erasure verification (R4).
- **The attacker model.** What an adversary is assumed to hold at each level —
  a leaked runtime credential, SQL execution, a compromised process — written
  down, so a probe can be judged against a threat rather than against taste.
- **Cadence.** How often each probe runs. This is not a scheduling detail: for
  any control whose guarantee is *detection rather than prevention*, the
  interval between runs **is** the exposure window. `rapp-postgres` ADR-0003
  says so explicitly and leaves the number to be set here.
- **Differential testing between tenant contexts.** Running the same request as
  two tenants and comparing responses is the mechanically reproducible core of
  cross-tenant testing, and it is this repo's principal technique.
- **Rules of engagement.** What may be probed, where, with what credentials,
  and what must never be done. An automated facility without this is
  indistinguishable from the threat it models.

## What it does not own

- **Fixing anything.** A finding routes through `risk-nexus` to the repo that
  owns the defect. A security facility that fixes things becomes a second
  engineering team with no boundary and no reviewer.
- **Severity, disclosure and timing.** `risk-nexus`. This repo says what is
  true; that repo says how much it matters and who hears about it.
- **Mechanical CI evidence.** Schema assertions, unit tests and provisioning
  checks stay with the repo that owns the code. This repo does not take over
  anyone's test suite.
- **Deciding what the security model should be.** NetKingdom's canon says what
  good looks like. This repo says whether we have it.
- **Blocking delivery.** In build mode a finding is information. If that
  changes it will be a recorded decision, not a habit that accretes.

## Honest limits on "automated"

The word in the repo's description is *automated*, and it must not be oversold
— overclaiming is the failure this estate keeps catching in itself.

External testing practice is consistent that the highest-impact cross-tenant
findings concentrate in access control, business logic and tenant isolation:
precisely the categories that need someone who understands what the data
*means* to recognise that a response is wrong. A response can be well-formed,
200, fast, and contain another tenant's rows.

So:

- **Automate the reproducible.** Structural conformance, differential responses
  between tenant contexts, credential confinement, resource saturation. This is
  most of the surface and it should run without anyone remembering to run it.
- **Flag the irreducible.** Where a finding requires semantic judgement, the
  facility's job is to set up the conditions, capture the evidence, and mark it
  for review with a date — not to return green.
- **A passing suite is not proof of isolation.** It is proof that the attacks
  we thought of did not work. State it that way in every report, because the
  gap between those two sentences is where breaches live.

## The failure this repo must avoid

**A probe that has only ever passed is not evidence.** `rapp-postgres` verified
its own drift check by deliberately breaking the thing it watched and
confirming the check failed. Every probe here inherits that obligation: it must
be shown to fail against a known-bad fixture before it is trusted against a
real system.

The second failure is subtler. A probe that starts passing because it was
weakened is worse than a deleted probe, because it reports safety. Probe
changes are therefore reviewed as security changes, and a probe that begins
passing after a change to *itself* rather than to the system is treated as a
finding.

## Relationship to the rest of the estate

```
whitehat-security  →  risk-nexus  →  policy-nexus
   finds                triages         publishes
                     (severity,      (permanent,
                      disclosure)     addressable)
```

It reads posture claims and canon from the repos that own them, attacks the
running systems those claims describe, and hands what it finds to `risk-nexus`.
It publishes nothing directly and fixes nothing.

The first work is already specified and waiting: the E2 cross-tenant evidence
artifact, which is Tenancy Posture's highest-severity unowned gap, and the
noisy-neighbour characterisation, which the framework had to reword once
already because its first draft asserted something shared infrastructure cannot
provide.

## What good looks like

The estate knows which of its security claims have been tested, when, and by
what attacker model — and can tell the difference between a property that has
been verified and one that has merely never failed.