Skip to content

feat(web-security): add structured findings via produces item types#74

Merged
GangGreenTemperTatum merged 1 commit into
mainfrom
ads/cap-1135-add-structured-findings-to-the-web-security-agent
Jul 7, 2026
Merged

feat(web-security): add structured findings via produces item types#74
GangGreenTemperTatum merged 1 commit into
mainfrom
ads/cap-1135-add-structured-findings-to-the-web-security-agent

Conversation

@GangGreenTemperTatum

Copy link
Copy Markdown
Contributor

Summary

Enable the platform structured items subsystem (produces) for the web-security capability. This gives every agent session running under web-security the report_item / update_item / link_items tools automatically, with items landing in the project Items UI for triage, filtering, and cross-session tracking.

Changes

capability.yaml

Added produces config:

produces:
  values: [finding, asset]
  web_vulnerability: items:WebVulnerability
  web_endpoint: items:WebEndpoint

items.py (new)

Two domain-specific Pydantic models alongside the platform built-ins:

WebVulnerability (20 fields) — full-lifecycle vulnerability record designed for bug bounty and professional pentest workflows:

  • CVSS 3.1 and 4.0 scoring (vector + numeric score)
  • CWE / OWASP Top 10 classification
  • Affected endpoint, parameter, and component
  • Evidence and reproduction steps (markdown, supports HTTP request/response blocks)
  • Attacker model (capability, prerequisites)
  • Validation verdict (mirrors the finding-validator agent vocabulary)
  • Chain suggestions for multi-step exploits
  • Confidence ladder: confirmed / firm / tentative (PTES-style)

WebEndpoint (10 fields) — discovered attack surface for recon output:

  • URL, method, technology fingerprint
  • Endpoint type (api, admin_panel, graphql, webhook, etc.)
  • Auth requirement, parameters, response fingerprint

Design rationale

Models were designed by studying the existing capability surface:

  • record_finding tool fields → vulnerability classification, evidence, attacker model
  • report-writer skill template → CVSS 3.1 + 4.0, CWE, reproduction steps format
  • exploit-verifier Triple-Check → validation verdict vocabulary
  • ooda-discipline → confidence = gadget → lead → vulnerability progression
  • vuln-critic → severity calibration from evidence quality

Only 3 fields are required (title, severity, affected_endpoint, description) — a black-box tester may not have CVSS or source-level detail.

What this enables

  1. Platform-native item tracking — findings/assets appear in the project Items view, persistent across sessions
  2. Triage workflow — open → triaged → verified → resolved / dismissed
  3. Relationship graphlink_items connects findings to the endpoints they affect
  4. Schema-validated agent output — Pydantic validation at emit time with immediate error feedback
  5. Dual-write durability — OTEL span backup + direct POST, never loses data

Refs: CAP-1135

Enable the platform items subsystem for the web-security capability.
Adds two domain-specific Pydantic models alongside the built-in
finding and asset types:

- WebVulnerability: full-lifecycle vulnerability record with CVSS 3.1
  and 4.0 scoring, CWE/OWASP classification, affected endpoint and
  parameter, evidence, reproduction steps, attacker model, chain
  suggestions, and validation verdict. Designed for bug bounty
  triage and professional pentest reporting.

- WebEndpoint: discovered attack surface record for endpoints,
  services, and API surfaces — URL, method, technology fingerprint,
  auth requirement, parameters, and response characteristics.

The produces config in capability.yaml wires these into the runtime's
report_item / update_item / link_items tools automatically. Items
land in the project Items UI with severity filtering, triage
workflow, and cross-item linking.

Refs: CAP-1135
@GangGreenTemperTatum GangGreenTemperTatum merged commit e9d3a84 into main Jul 7, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant