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 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:

---
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:

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