---
name: attack-surface
description: Build and maintain docs/attacksurface.md — a living inventory of everything deployed (sites, APIs, databases, vendors, hosts) with tech, auth, exposure, and known misconfigurations. Use when adding or changing infrastructure, before a security review, or on a scheduled cadence.
---

Maintain `docs/attacksurface.md` as the single running inventory of this project's deployed attack surface. Do not create exploit code or test against systems the user has not authorized.

1. Read `docs/attacksurface.md` (create it from the template below if absent), `docs/ARCHITECTURE.md`, and infra/config sources actually present: IaC, `Dockerfile`/compose, CI configs, `.env.example`, deploy manifests, and dependency manifests. Prefer evidence in the repo over assumption; list unknowns rather than guessing.
2. For each deployed asset, capture: name, type (web property / API / database / queue / job / static site), tech and version, self-hosted vs third-party, how you authenticate into it, audience/exposure (public / internal / VPN / token / OAuth), the defenses in place, and the common misconfigurations and CVE classes for that platform.
3. Update the inventory in place: add new assets, revise changed ones, and mark retired ones. Keep each entry to a scannable row plus notes — this is a control plane, not a report.
4. Recommend a testing/review cadence per asset based on criticality × exposure × change rate (e.g. public auth endpoint = frequent; internal cron = rare).
5. Never write secrets, tokens, credentials, or live keys into the file. Reference where a secret lives, not its value.

## docs/attacksurface.md template

```markdown
# Attack surface

> Living inventory of everything deployed and its exposure. Updated whenever infrastructure changes and before each security review. Contains no secrets — only references to where secrets live.

## Assets

| Asset | Type | Tech / version | Hosted | Auth in | Exposure | Defenses | Review cadence |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [name] | [web/API/db/...] | [stack] | [self/3p] | [OAuth/key/...] | [public/internal/VPN] | [WAF, ratelimit, ...] | [freq] |

## Per-asset notes

### [asset name]
- **Common misconfigs / CVE classes:** [platform-specific]
- **Known exposure:** [what an attacker reaches, from where]
- **Secrets location:** [vault/manager path — not the value]
- **Last reviewed:** [date + result]

## Gaps / unknowns
- [asset or config not yet mapped]
```