Attack-surface catalog: schema, tooling, and 70-case bootstrap

[jorgeraad]

Summary

Implements the attack-surface catalog design doc — a per-benchmark attack-surface.json covering every entry point in argus's 70 benchmarks (60 APEX + 10 TM-APP), backed by a schema, validator, and @pensar/surface-driven bootstrapper.

The catalog answers a different question than the existing GT files: "what is every door into this app?" alongside "which vulnerabilities exist?" (expected_results/*vulns.json) and "what threat model should an analyst produce?" (ground-truth.json).

Phase 1 — Schema & tooling

• attack-surface-schema.json — JSON Schema (Draft 2020-12) with a kind discriminator (http, web, asset, grpc, graphql, event_handler) defaulting to "http". Strictly additive: existing apex/argus emissions stay valid as kind: "http" records.
• scripts/validate-attack-surface.ts — CI validator. Implements all seven design checks: schema validation, canary, file resolution, per-kind source-grep, duplicate identity, service refs, and the D3 empty-catalog gate (empty entry_points requires top-level notes ≥ 20 chars).
• scripts/bootstrap-attack-surface.ts — surface map driver with the auto-validate-and-iterate loop from the spec. Maps EndpointInfo[] → EntryPoint[], drops unresolvable entries, merges duplicates, defaults single-service refs. Prints a one-line per-case diagnostic to stdout (frameworks, raw vs. kept counts, auto-fix tallies) as the curator handoff.
• .github/workflows/validate-attack-surface.yml — runs the validator on every PR touching catalogs, the schema, the scripts, or the lockfile.
• package.json + bun.lock + tsconfig.json — pin @pensar/surface@0.2.1 (D4: exact-pin, no ^) plus ajv for schema validation. Bun is the script runner.
• README.md — documents the new ground-truth layer with a comparison table of the three GT artifacts (catalog vs. vulnerability vs. threat-model) and the curator workflow.

Phase 2 — 70-case catalog bootstrap

Every benchmark now has an attack-surface.json. Generated by running bun run bootstrap:attack-surface --all against the repo:

• 62 cases populated with HTTP / web entries that surface successfully extracted (Express, Next.js, Django, Apollo-on-Express, Spring, Gin, …).
• 8 cases ship empty entry_points: [] per the D3 rule (with explanatory notes): APEX-011, APEX-016, APEX-026, APEX-037 (custom PHP / proxy / no-framework cases), and TM-APP-003, TM-APP-004, TM-APP-005, TM-APP-007 (gRPC / Lambda / non-HTTP infrastructure).

These are draft ground truth — schema-valid and source-traceable, not hand-verified. Curators re-run the bootstrap locally to see the per-case diagnostic line and identify gaps to fill (gRPC RPCs, GraphQL operations, Lambda triggers, cloud assets, custom-PHP routes).

CI status: bun run validate:attack-surface reports 70 valid · 0 missing catalog · 0 errors against the bootstrapped corpus.

Out of scope

This PR is argus-side only. The evalgate-side work (matcher kind dispatch, judge integration, suite expansion, submodule bump — phase 3 / T6–T9 in the design doc) lands in evalgate after this merges.

Verification

bun install
bun run validate:attack-surface           # 70 valid · 0 errors
bun run bootstrap:attack-surface --dry-run benchmarks/APEX-019-25
bun run bootstrap:attack-surface benchmarks/APEX-019-25 --force
bunx tsc --noEmit                          # types clean

Manually verified that the validator catches the four common failure modes:

• wrong/missing canary
• duplicate (kind, method-set, path) tuples
• unresolvable file references
• path not appearing in the cited file
• empty entry_points with no rationale

Notes for reviewers

• Per D5 (single PR), the schema, scripts, CI, README, and all 70 catalogs land together. Hand-curation of individual cases is intentionally a follow-up; the bootstrap's stdout diagnostic line is the curator's TODO list for that case.
• The bootstrap drops surface's noise handlers (req, res, <anonymous>) so handler only carries genuine names. Surface-emitted source paths are rewritten with the src/ prefix to match the catalog's "relative to benchmark root" convention.