findings.v1

The shared wire format every Capframe module emits or consumes. View raw JSON Schema →

Top-level envelope

Every findings.v1 document is an object with these required fields. Anything else is rejected by the schema.

Scanner

Identifies the tool that emitted the document.

Target

Describes the artefact under scan.

TargetKind enum

• mcp_server — An MCP server (stdio or HTTP)
• openai_function — An OpenAI function-calling tool spec
• anthropic_tool — An Anthropic tool_use block
• langgraph_node — A LangGraph node definition
• custom — Anything else; the scanner attaches its own shape

Tool

One entry per tool in the scanned surface. Same shape regardless of TargetKind.

SideEffect enum

• read — Reads bounded state
• write — Mutates state inside the bounded scope
• network — Egresses to the network
• filesystem — Touches the host filesystem
• execute — Runs code or shell commands
• money — Moves funds, charges, refunds
• irreversible — Destructive — delete, drop, send

Finding

One rule firing on one tool (or, occasionally, server-level). Findings are the unit of cross-tool exchange — the same Finding object can flow from mcp-recon → capnagent for caveat issuance, or → capframe-report for OWASP/NIST/ATLAS reporting.

Severity enum

• info — Informational; no action required
• low — Worth noting; doesn't block
• medium — Should be remediated; typical for unconstrained_input
• high — Blocks production for security-sensitive deployments
• critical — Maximal authority leak (e.g. arbitrary code execution surface — see R7)

Category enum

• indirect_injection — Tool fetches/forwards untrusted content
• excessive_agency — Tool has more power than its caveats declare
• unconstrained_input — String / object parameter with no bound
• missing_authz — Side-effect tool with no auth claim
• insecure_output_handling — Output not sanitised back to the agent
• secret_exposure — Schema implies leaking credentials
• tool_naming_conflict — Two tools with overlapping names
• deserialization — Accepts opaque blobs that could be exploits
• ssrf_surface — URL parameter with no host allowlist
• filesystem_egress — Reads outside its declared scope
• network_egress — Egresses without rate limit / domain bound
• untrusted_dependency — Pulls in a dep we can't vouch for
• other — Doesn't fit the above; subject to taxonomy change

Mappings — compliance IDs

Each finding can carry compliance-framework references. Patterns are enforced by the schema, so consumers can trust the strings.

Summary

Aggregated counts. Computed by the scanner; consumers should not recompute. The fields are flat and stable for diffing across scans.

SeverityCounts

All five severity keys present, default 0. Sum equals summary.total.

Example envelope

Minimal but valid. Strip the tools and findings arrays empty and you have the empty-scan shape that mcp-recon emits when its input can't be parsed.

{
  "schema_version": "capframe.findings.v1",
  "scanned_at": "2026-05-30T13:47:37Z",
  "scan_id": "0c81b6d2-7a91-4c52-9c1e-aa8e90e3f6b1",
  "scanner": { "name": "mcp-recon", "version": "0.2.0" },
  "target":  { "kind": "mcp_server", "name": "shopify-mcp", "transport": "stdio" },
  "tools": [
    {
      "name": "order.refund",
      "description": "Issue a refund on an order",
      "side_effects": ["write", "money", "irreversible"],
      "auth_required": true
    }
  ],
  "findings": [
    {
      "id": "f-order-refund-unbounded",
      "severity": "high",
      "category": "excessive_agency",
      "title": "order.refund has no monetary cap",
      "description": "Accepts arbitrary amount with no policy-side cap.",
      "tool": "order.refund",
      "remediation": "Bind a capability with --max-refund.",
      "mappings": {
        "owasp_llm":   ["LLM08"],
        "nist_rmf":    ["MANAGE-2.2"],
        "mitre_atlas": ["T0051"]
      }
    }
  ],
  "summary": {
    "total": 1,
    "by_severity": { "info": 0, "low": 0, "medium": 0, "high": 1, "critical": 0 },
    "by_category": { "excessive_agency": 1 }
  }
}