whitehat-security/AGENTS.md

# 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 accepted, but that acceptance authorizes no live
  target. Without a complete, target-specific engagement record and every
  approval required by the rules of engagement §1, 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 (railiance01, in-cluster) | `http://10.43.68.154:8000` |
| 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. -->