Security Graph API

F2: AI Agent Security Graph endpoints for visualizing agent relationships, detecting MITRE ATT&CK risk paths, and exporting compliance reports.

All endpoints require authentication via JWT or API key and enforce tenant isolation via organization_id.

Endpoints

GET /api/v1/graph/nodes

Return all graph nodes (agents, MCP servers, external systems) and edges for visualization.

Query Parameters:

Parameter	Type	Default	Description
time_range	string	7d	24h, 7d, or 30d
risk_level	string	all	all, medium, high, or critical
include_mcp	boolean	true	Include MCP server nodes
include_discovered	boolean	true	Include discovered agent nodes

Response: 200 OK

{
  "nodes": [
    {
      "id": "agent:mcp-trade-executor",
      "node_type": "mcp_server",
      "label": "Meridian Trade Executor",
      "agent_type": "autonomous",
      "status": "active",
      "risk_level": "medium",
      "avg_risk_score": 45.2,
      "action_count": 14,
      "size": 24,
      "color": "#8B5CF6"
    }
  ],
  "edges": [
    {
      "id": "edge:mcp-trade-executor->execute_order",
      "source": "agent:mcp-trade-executor",
      "target": "system:execute_order",
      "weight": 14,
      "action_types": ["trade.execute"],
      "avg_risk_score": 55.0
    }
  ],
  "metadata": {
    "time_range": "7d",
    "cache_hit": true,
    "node_count": 7,
    "edge_count": 5
  }
}

Performance: < 200ms p99 (cache hit), < 2s (cache miss)

GET /api/v1/graph/risk-paths

Return all detected MITRE ATT&CK risk path sequences.

Query Parameters:

Parameter	Type	Default	Description
time_range	string	7d	24h, 7d, or 30d
severity	string	all	all, HIGH, or CRITICAL
pattern_type	string	null	Filter by pattern (e.g., prompt_injection)
status	string	active	active, acknowledged, resolved, all

Response: 200 OK

{
  "risk_paths": [
    {
      "detection_id": "RPD-44-prompt_injection-1712750400",
      "pattern_type": "prompt_injection",
      "pattern_name": "Prompt Injection",
      "severity": "CRITICAL",
      "confidence_score": 0.85,
      "mitre_technique_ids": ["T1190"],
      "mitre_tactic_ids": ["TA0001"],
      "involved_agent_ids": ["mcp-trade-executor"],
      "involved_action_ids": [123, 124],
      "evidence": {
        "matched_keywords": ["ignore previous"],
        "detection_reasoning": "Prompt injection markers in action 123"
      },
      "status": "active",
      "created_at": "2026-04-10T12:00:00Z"
    }
  ],
  "summary": {
    "total_active": 2,
    "critical_count": 1,
    "high_count": 1,
    "patterns_detected": ["prompt_injection", "credential_abuse"]
  }
}

GET /api/v1/graph/summary

Aggregated statistics for dashboard header cards.

Response: 200 OK

{
  "total_registered_agents": 3,
  "active_agents": 3,
  "total_mcp_servers": 3,
  "total_discovered_agents": 0,
  "total_actions_in_range": 45,
  "risk_distribution": {"medium": 30, "high": 10, "critical": 5},
  "active_risk_paths": 2,
  "critical_risk_paths": 1,
  "top_mitre_techniques": [
    {"id": "T1190", "count": 3}
  ]
}

POST /api/v1/graph/risk-paths/acknowledge

Mark a risk path detection as acknowledged, resolved, or false positive. JWT only (human action, no API key).

Request Body:

{
  "detection_id": "RPD-44-prompt_injection-1712750400",
  "action": "acknowledge",
  "notes": "Reviewed — legitimate test activity"
}

Actions: acknowledge, resolve, mark_false_positive

Response: 200 OK

{
  "detection_id": "RPD-44-prompt_injection-1712750400",
  "status": "acknowledged",
  "acknowledged_by": "sarah.chen@meridian-capital.com",
  "acknowledged_at": "2026-04-10T14:30:00Z",
  "audit_log_id": 456
}

GET /api/v1/graph/export

Export graph data in structured format for PDF generation.

Query Parameters:

Parameter	Type	Default	Description
time_range	string	7d	24h, 7d, or 30d
include_risk_paths	boolean	true	Include risk path detections

Response: 200 OK — Full report structure with executive summary, agent table, risk paths, MITRE coverage, and compliance mapping.

WebSocket — /api/v1/graph/ws/:org_id

Real-time graph update stream.

Connection:

wss://pilot.owkai.app/api/v1/graph/ws/:org_id?token=:jwt_access_token

Events pushed:

• risk_path_detected — New MITRE ATT&CK risk path detected
• node_update — Agent status or risk level changed
• edge_update — New agent-to-system connection observed

Ping/Pong:

// Send
{"type": "ping"}
// Receive
{"type": "pong"}

Auth: JWT access token required as ?token= query parameter. Organization ID in the path must match the token's organization.