coulomb/whitehat-security
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Register whitehat-security and align operating boundaries

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0260c-4067-7052-9647-ad000d576e38
This commit is contained in:
tegwick 2026-08-21 22:52:37 +02:00
parent 0ce9f44ff9
commit 348738ba73
9 changed files with 474 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored Normal file
View file

@ -0,0 +1 @@
.repo-manager/

29
.repo-classification.yaml Normal file
View file

@ -0,0 +1,29 @@
repo_classification:
standard: Repo Classification Standard
version: "1.0"
classified_at: "2026-08-21"
classified_by: codex
category: tooling
domain: infotech
secondary_domains: []
capability_tags:
- access-control
- evidence
- traceability
- compliance
- risk
- audit
- observability
- operations
business_stake:
- technology
- operations
- legal
- automation
business_mechanics:
- control
- operation
- adaptation
notes: >-
NetKingdom offensive-security tooling that produces independently operated,
authorization-bound adversarial evidence and routes findings to risk-nexus.

123
AGENTS.md Normal file
View file

@ -0,0 +1,123 @@
# whitehat-security — Agent instructions
## Repository identity
**Purpose:** Authorization-bound offensive-security tooling that produces
adversarial evidence about security claims and routes findings to the
responsible party.
**Owner:** NetKingdom
**Domain:** infotech
**Repo slug:** `whitehat-security`
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `WHITEHAT-WP-`
## Orient before working
1. Read `INTENT.md` and `SCOPE.md`.
2. Read `docs/rules-of-engagement.md` before designing or executing probes.
3. Read `.custodian-brief.md` when present and scan `workplans/`.
4. Check the repository inbox:
`curl -s "http://127.0.0.1:8000/messages/?to_agent=whitehat-security&unread_only=true"`
5. Check the worktree before editing; preserve unrelated user changes.
## Non-negotiable safety boundary
- The rules of engagement are pending personal operator approval. Until they
are approved, perform only documentation work and non-networked fixture
design. Send no packets to a target.
- Even after approval, no live run starts without a dated engagement record
naming authorization, target owner, exact scope, window, technique,
credentials, rate/concurrency ceiling, abort contact and finding destination.
- Never broaden scope after discovery. Record an adjacent system and stop.
- Never collect real tenant row values or credentials as evidence.
- Never use superuser, owner or `BYPASSRLS` privilege for convenience.
- Never perform destructive, persistence, lateral-movement or denial-of-service
activity outside an explicitly authorized technique and window.
- A pass means only that the attempted attacks did not work. Every probe must
first fail against a known-bad fixture.
- This repository finds and reports; it does not fix targets or assign severity.
## State Hub integration
State Hub is the coordination index; repository files remain authoritative.
| Context | URL |
| --- | --- |
| Local workstation | `http://127.0.0.1:8000` |
| Remote tunnel | `http://127.0.0.1:18000` |
| Optional edge relay | `http://127.0.0.1:18080` |
Use `/state/health` for health checks. After changing workplan files, run:
`statehub fix-consistency`
If the command reports C-06/C-11 because this host is not the identifier
registrar, do not set `STATEHUB_REGISTRAR` manually. Commit and push the
file-backed work, then use the scoped fallback once:
`uv run --project ~/repo-manager rmgr registrar-reconcile --path . --confirm-primary --push`
At session close, ensure file task statuses reflect reality and record
significant progress in State Hub. Actionable residuals from a finished
workplan must become live work records rather than remaining only in prose.
## Credential routing
Before requesting credentials, API keys, SSH access or database passwords:
`warden route find "<describe the need>" --json`
`ops-warden` issues SSH certificates only. Other secret material belongs to the
custody route returned by `warden`. Never put credentials in Git, State Hub,
workplans, logs, evidence or chat.
## Workplan convention
Workplans live at `workplans/WHITEHAT-WP-NNNN-<slug>.md`. Finished plans may
move to
`workplans/archived/YYMMDD-WHITEHAT-WP-NNNN-<slug>.md` without changing their
frontmatter ID.
Required frontmatter:
```yaml
---
id: WHITEHAT-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: whitehat-security
status: proposed | ready | active | blocked | backlog | finished | archived
owner: ...
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by reconciliation; do not edit
---
```
Each task uses one machine-readable block:
````markdown
```task
id: WHITEHAT-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by reconciliation; do not edit
```
````
Use `proposed` for drafts, `ready` after review, `active` once work has begun,
and `finished` only when all required work is complete or residuals have live
owners. Task progression is `todo` → `progress` → `done`; `wait` is for work
that cannot currently proceed and `cancel` is terminal.
Small, low-risk work completed directly may use
`workplans/ADHOC-YYYY-MM-DD.md`. Anything requiring analysis, approval,
dependencies or multiple phases needs a normal workplan.
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Add repository-specific instructions below this marker. -->

13
INTENT.md
View file

@ -99,8 +99,10 @@ 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, build mode** — standing estate authorization is necessary
but not sufficient. Every live run still needs the dated engagement record,
target-owner acknowledgement and technique-specific scope required by the
rules of engagement. No live target is pre-authorized by this intent.
- **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.
@ -111,10 +113,9 @@ responsible for it. No exceptions.**
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.
obviously be fine with it". Unauthorized probing may be unlawful 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

12
README.md
View file

@ -11,12 +11,16 @@ true.
It exists because a repo testing its own boundary grades its own homework. The
probes most worth having are the ones an author would not think to write.
- **Independent by construction.** It does not take a declared posture as true,
and it is not owned by the repo whose canon it verifies.
- **Independent in operation.** It does not take a declared posture as true.
NetKingdom owns both the security canon and this facility, so findings leave
through `risk-nexus` under separate ownership rather than being resolved here.
- **It finds; it does not fix.** Findings route to `risk-nexus`, which owns
severity and disclosure. The repo that owns the defect owns the repair.
- **A pass means the attacks we tried did not work** — not that the boundary
holds. Reports say so.
- Intent: `INTENT.md`
- Workplans: `workplans/`
- Intent: [`INTENT.md`](INTENT.md)
- Scope: [`SCOPE.md`](SCOPE.md)
- Workplans: [`workplans/`](workplans/)
- Rules of engagement (pending operator approval):
[`docs/rules-of-engagement.md`](docs/rules-of-engagement.md)

87
SCOPE.md Normal file
View file

@ -0,0 +1,87 @@
# Scope
## One-liner
`whitehat-security` is NetKingdom's authorization-bound offensive-security
tooling for producing adversarial evidence about security claims.
## Core idea
The repository turns stated security properties into dated, reproducible attack
attempts. It remains separate from the systems it tests, reports findings
without grading their severity, and never treats a passing probe as proof that a
boundary always holds.
## In scope
- Attacker models for tenant isolation, credential confinement, noisy-neighbour
behavior and erasure verification.
- Differential probes that compare behavior across controlled tenant contexts.
- Known-bad and known-good fixtures that demonstrate every probe can fail.
- Rules of engagement, target authorization, engagement records, abort
controls and evidence minimization.
- Probe cadence and the resulting assurance/exposure window.
- Delivery of findings and passing-run evidence to `risk-nexus`.
## Out of scope
- Fixing defects in target repositories.
- Assigning severity, disclosure policy or remediation deadlines.
- Replacing mechanical checks owned by a target repository's CI.
- Defining the estate's security model or publishing permanent policy.
- Probing any target without the authorization and engagement records required
by [the rules of engagement](docs/rules-of-engagement.md).
- Blocking build-mode delivery without a separately recorded decision.
## Safety invariants
- Until the rules of engagement receive personal operator approval, only
documentation and non-networked fixture design may proceed.
- No live target is authorized by this scope document.
- Every live run names its authorization, target, owner, window, technique,
credential lane, rate ceiling, abort contact and finding destination.
- A probe stops at the recorded boundary and never follows an adjacent system.
- Evidence records response shape and counts, never real tenant row values or
credentials.
- Findings leave this repository; repairs do not enter it.
## Relevant when
- A service claims a Tenancy Posture evidence level that requires adversarial
rather than mechanical evidence.
- A boundary must be tested using a leaked runtime credential or hostile tenant
context.
- The estate needs to know when a probe last ran, what attacker it modeled, and
whether it was proven against a known-bad fixture.
## Not relevant when
- A repository needs unit, schema or provisioning tests for its own code.
- A finding needs triage, severity or disclosure handling; use `risk-nexus`.
- Permanent policy needs publication; use `policy-nexus`.
- The desired activity falls outside an approved engagement boundary.
## Current state
- Repository status: active.
- Active plan: `WHITEHAT-WP-0001`.
- `T01` is in progress: the rules of engagement are drafted and awaiting
personal operator approval.
- No live probe traffic is authorized yet.
- `T02` through `T07` remain gated by `T01`.
## Relationships
- Owner and security canon: `net-kingdom`.
- Finding intake, severity and disclosure: `risk-nexus`.
- Permanent publication: `policy-nexus`.
- Initial proposed target owners: `tenant-engine`, `audit-core` and
`flex-auth`.
## Getting oriented
1. Read [`INTENT.md`](INTENT.md) for the durable purpose and ownership model.
2. Read [the rules of engagement](docs/rules-of-engagement.md) before any probe
design or execution.
3. Read [`WHITEHAT-WP-0001`](workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md)
for active tasks and sequencing.

18
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,18 @@
# Work Records — whitehat-security
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | WHITEHAT-WP-0001 | active | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T01 | progress | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T02 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T03 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T04 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T05 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T06 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |
| task | WHITEHAT-WP-0001-T07 | wait | — | workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md |

145
docs/rules-of-engagement.md Normal file
View file

@ -0,0 +1,145 @@
# Rules of engagement for tenancy evidence
Status: **pending personal operator approval**
Version: 0.1
Date: 2026-08-18
Owner: NetKingdom / whitehat-security
These rules authorize nothing outside their recorded scope. A probe without a
matching authorization record is prohibited, even if technically possible.
## 1. Authorization classes
| Target class | Required authorization |
| --- | --- |
| Offline known-good/known-bad fixtures created by this repo | This reviewed document |
| Estate build environment, non-destructive API differential probe | Standing estate authorization plus a dated engagement record naming the target owner |
| Any live Kubernetes workload, database credential, recovery or saturation probe | Separate operator approval for the named target, namespace, window and technique |
| Production | Production-specific written authorization; build-mode consent never carries over |
| Infrastructure not owned by the estate | Written authorization from its responsible party, per engagement, before any packet |
Public reachability, a commercial relationship, and an assumption that an
owner would agree are never authorization.
## 2. Engagement record
Every run begins with a committed or operator-approved record containing:
- engagement id, authorizer, approval timestamp and expiry
- target service, responsible repo/party, environment and namespace
- source location and network position of the probe
- exact API routes or database names in scope
- tenant fixtures and object identifiers created for the run
- credential lane, audience, role and maximum TTL (never the value)
- permitted techniques, prohibited techniques and concurrency/rate ceilings
- start/end window, operator contact and abort contact
- posture axis/claim and attacker model being tested
- finding destination in `risk-nexus`
An expired, incomplete or mismatched record fails closed. Discovery of an
adjacent target is recorded and not followed.
## 3. Initial authorized target envelope
After personal approval of this document, offline fixtures may be built. No
live target is pre-authorized by this section. The first proposed live
engagements are:
- `tenant-engine`: HTTP read/write differential using two disposable tenants
- `audit-core`: HTTP append/read differential using two disposable tenants
- `flex-auth`: decision differential for relationship inheritance across two
disposable tenants
Each still needs its own dated engagement record and target-owner
acknowledgement. `databases/platform-pg` and `databases/apps-pg` are not in the
initial API-probe envelope; RLS, recovery and saturation work require separate
operator windows.
## 4. Hard prohibitions
- no destructive operation against data not created for the engagement
- no collection or exfiltration of real tenant row values; record only count,
schema shape, stable test-fixture ids and salted/one-run digests
- no denial-of-service, saturation, lock exhaustion, connection exhaustion or
large payload against shared substrate outside an explicitly approved window
- no superuser, `BYPASSRLS`, owner credential or standing privilege unless the
specific attacker model is testing detection of that misgrant
- no credential reuse outside its named audience/target and no credential
value in Git, evidence, State Hub, logs or chat
- no persistence, implant, account creation, lateral movement, vulnerability
chaining or follow-on discovery beyond the recorded technique
- no weakening alerting, backup, audit or retention controls to make a test pass
## 5. Credentials and attribution
Credentials are short-lived and obtained through the sanctioned custody lane.
The engagement records only the catalog/role reference, TTL and lease id if it
is safe metadata. The facility holds the same privilege as the modelled
workload—never broader privilege for convenience.
HTTP probes send `User-Agent: whitehat-security/<engagement-id>` and a stable
correlation id. Database probes set `application_name` to the engagement id.
The operator must be able to identify and terminate a probe from access logs or
`pg_stat_activity` without asking whether it is hostile traffic.
## 6. Rate, concurrency and data controls
API differential runs default to one in-flight request and at most 60 requests
per minute. A target owner may set a lower number. Test data uses two newly
created disposable tenants and deterministic synthetic values. Responses are
evaluated in memory; evidence stores status, count, content type, schema keys
and a salted run-local digest—not bodies.
Database conformance defaults to one connection. Noisy-neighbour work has no
default: its connection/query/CPU ceiling must be written in the individual
operator-approved window.
## 7. Abort and cleanup
Any of these immediately aborts a run:
- target latency/error rate crosses the engagement threshold
- a response appears to contain non-fixture tenant data
- scope, authorization, credential audience or target identity is uncertain
- operator/target owner requests stop
- audit attribution is absent
- an unexpected adjacent system responds
The runner stops issuing work, closes HTTP/database sessions, revokes or lets
the bounded lease expire, and records the abort without attempting further
diagnosis. Cleanup deletes only fixtures whose ids are in the engagement
record. If cleanup cannot be proven, it becomes a finding; the runner does not
broaden privilege to force it.
## 8. Evidence and reporting
Every attempted run—pass, fail or abort—records:
- authorization and engagement ids
- target revision/digest where observable without privilege escalation
- start/end timestamps and attacker model
- attempted operation count and response-shape comparison
- outcome: `pass`, `finding`, `inconclusive`, or `aborted`
- cleanup and credential-revocation outcome
- the statement: “Pass means only that the attacks attempted in this run did
not work; it is not proof that the tenant boundary always holds.”
Findings route unchanged to `risk-nexus`; this repo assigns no severity and
does not fix the target.
## 9. Change control
Probe logic is security-sensitive. A change that makes a previously failing
known-bad fixture pass is a finding until independently explained. Every live
probe must first fail against its known-bad fixture and pass against the
known-good fixture in the same revision.
## 10. Approval
Personal operator approval is still required. Record approver, date and scope
in this section or an immutable linked decision before changing the status to
accepted. Until then, only documentation and non-networked test-fixture design
may proceed; no target packets are authorized by this draft.

62
workplans/WHITEHAT-WP-0001-cross-tenant-evidence.md
View file

@ -4,11 +4,11 @@ type: workplan
title: "Produce the adversarial evidence the Tenancy Posture ladders require"
domain: infotech
repo: whitehat-security
status: proposed
status: active
owner: net-kingdom
topic_slug: whitehat-security
created: "2026-08-17"
updated: "2026-08-17"
updated: "2026-08-21"
---
# WHITEHAT-WP-0001 — cross-tenant evidence
@ -45,10 +45,12 @@ not paperwork.
- **Target authorization**, the control that matters most now the facility is
scoped to any surface we choose rather than only our own. No target without a
recorded authorization from its responsible party. Our estate in build mode
has standing authorization; production needs its own; anything we do not own
needs written per-engagement authorization recorded here before a packet is
sent. A commercial relationship, public reachability, and "they would
obviously be fine with it" are each explicitly not authorization.
has standing authorization only as a prerequisite: every live run still
needs the dated engagement record and target-owner acknowledgement defined in
the rules of engagement. Production needs its own authorization; anything we
do not own needs written per-engagement authorization recorded here before a
packet is sent. A commercial relationship, public reachability, and "they
would obviously be fine with it" are each explicitly not authorization.
- **Scope.** Which systems, which namespaces, which credentials — and a hard
stop at the engagement boundary. A probe that discovers an adjacent system
reports what it saw and does not follow it.
@ -75,8 +77,26 @@ This is exactly the class of thing `risk-nexus`'s escalation duty exists for.
### T01 — Rules of engagement
As above. Gates everything.
```task
id: WHITEHAT-WP-0001-T01
status: progress
priority: high
```
Drafted in `docs/rules-of-engagement.md` on 2026-08-18 with authorization
classes, per-run records, initial target envelope, hard prohibitions,
credential/attribution rules, rate defaults, abort/cleanup and evidence
schema. It authorizes no live traffic until the operator personally approves
§10. T01 remains progress and continues to gate every later task.
### T02 — The attacker model per axis
```task
id: WHITEHAT-WP-0001-T02
status: wait
priority: high
```
What the adversary is assumed to hold, so a probe is judged against a threat
rather than against taste. Drawn from *Tenancy Posture* §4.3, which already
distinguishes them:
@ -95,6 +115,12 @@ only tested accident would report a strength E3 does not have.
### T03 — Differential cross-tenant harness (the E2 artifact)
```task
id: WHITEHAT-WP-0001-T03
status: wait
priority: high
```
The core technique: run the same request as two tenants and compare.
- Provision two disposable tenants against a target service.
@ -111,6 +137,12 @@ currently claim `E2`. The artifact is the run record, not a green tick.
### T04 — Prove the probes fail
```task
id: WHITEHAT-WP-0001-T04
status: wait
priority: high
```
A probe that has only ever passed is not evidence.
Build known-bad fixtures — a service with a deliberately missing tenant
@ -123,6 +155,12 @@ trusted passing.
### T05 — RLS conformance under attack (the E3 artifact)
```task
id: WHITEHAT-WP-0001-T05
status: wait
priority: medium
```
`rapp-postgres` ADR-0003 supplies an `rls_conformance` view and a template, and
states plainly that the platform's guarantee is **detection, not prevention** —
a table created by a later migration ships without a policy until something
@ -141,6 +179,12 @@ the number to this repo. Set it, and state the resulting window in the record.
### T06 — Noisy-neighbour characterisation (the P1/P2 artifact)
```task
id: WHITEHAT-WP-0001-T06
status: wait
priority: medium
```
The framework had to reword this artifact once already: its first draft
required proof that a saturating consumer "does not breach" another's
allowance, which shared infrastructure cannot provide.
@ -156,6 +200,12 @@ consumer connection ceiling, a saturation probe is an outage if run carelessly.
### T07 — Reporting into risk-nexus
```task
id: WHITEHAT-WP-0001-T07
status: wait
priority: medium
```
Findings leave this repo in one direction. A run produces: what was attempted,
under which attacker model, when, against which posture claim, and the outcome.
It carries no severity — that is `risk-nexus`'s.