whitehat-security/INTENT.md

# INTENT — whitehat-security

## Why this repo exists

`whitehat-security` is **NetKingdom's offensive security facility**. It attacks
IT infrastructure and surfaces we choose to point it at — our own estate among
them — and reports what it finds to whoever is responsible for fixing it.

The discipline is offensive because offence is how you find out. A control is
believed until someone tries it. Everything else in the estate's security work
describes what should be true; this repo establishes what is.

It was seeded to close a specific gap, which remains its first job. 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.

## Owner: NetKingdom

`whitehat-security` is a NetKingdom capability, alongside the IAM Profile,
SSO/MFA and the canonical security architecture. Offensive security is security
work, and it belongs with the repo that owns security.

**Separation of concerns still applies, one level down.** 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 — good work, and still the author checking their own work. The
probes most worth having are the ones an author would not think to write,
because the assumption that produced the defect produces the blind spot. So:

- This facility does not take a repo's declared posture as true. It tests it.
- It does not decide how bad its own findings are. Severity and disclosure are
  `risk-nexus`'s, which is `the-custodian`'s, not NetKingdom's.

**One residual tension, recorded rather than argued away.** NetKingdom owns the
Tenancy Posture framework *and* this facility. When whitehat tests conformance
to that framework, NetKingdom is assessing NetKingdom. The mitigation is the
routing above: findings leave for `risk-nexus` under separate ownership rather
than being resolved inside NetKingdom. That is proportionate, not perfect, and
worth revisiting if conformance findings ever start getting quietly closed.

## 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.
- **Target selection and authorization.** Which infrastructure or surface the
  facility is pointed at, and the authorization that permits it. See the
  targeting rule below — this is the repo's most important control.
- **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.
- **Findings delivery to the responsible party.** For our own estate that is
  `risk-nexus`, which routes to the owning repo. For any other target it is
  whoever is responsible for that infrastructure, on the terms agreed in the
  engagement.

## 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.

## The targeting rule

The facility can be pointed at infrastructure we do not own. That is the point
of it, and it is also the single thing that could turn this repo from an asset
into a liability, so the rule is structural rather than cultural.

**No target is probed without recorded authorization from whoever is
responsible for it. No exceptions.**

- **Our own estate, build mode** — standing authorization, within the declared
  scope. This is the current situation.
- **Our own estate, production** — a separate recorded authorization. Build-mode
  standing consent does not carry across; the blast radius is different and so
  is the decision.
- **Anything we do not own** — written authorization from the responsible party,
  per engagement, recorded in this repo *before a packet is sent*. Scope,
  window, permitted techniques, and named contacts on both sides.

Three things that do **not** constitute authorization, written down because
each is a way teams talk themselves into it: a commercial relationship with the
target; the target being publicly reachable; and a belief that the owner "would
obviously be fine with it". Unauthorized probing of someone else's
infrastructure is a criminal matter in most jurisdictions regardless of intent,
and a white-hat facility that gets this wrong is simply an attacker with better
paperwork.

**The authorization record is part of the finding.** A report that cannot name
the authorization it ran under is not a finding — it is an incident, and it
gets treated as one.

**Scope creep during an engagement is prohibited.** A probe that discovers an
adjacent system stops at the boundary and reports what it saw. Following the
interesting thing is exactly how an authorized test becomes an unauthorized
one.

## 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)
```

For our own estate it reads posture claims and canon from the repos that own
them, attacks the running systems those claims describe, and hands findings to
`risk-nexus`. For any other target, findings go to that infrastructure's
responsible party on the engagement's agreed terms; `risk-nexus` still records
that the engagement happened and what it means for us.

It publishes nothing directly and fixes nothing, in either case.

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.