{ "openapi": "3.1.0", "info": { "title": "GPSS ONE API", "version": "1.0.0", "description": "Multi-tenant security operations API. Every token is scoped to one organization and to a set of abilities." }, "servers": [ { "url": "https://app.gpssone.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Service health and API version.", "operationId": "get_health", "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } } } }, "/posture": { "get": { "tags": [ "Posture" ], "summary": "Security posture summary (score, vulnerabilities, incidents, SLA).", "operationId": "get_posture", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Posture" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List incidents (cursor paginated). Filters: status, severity, category, source, q, since.", "operationId": "get_incidents", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentPage" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" }, "post": { "tags": [ "Incidents" ], "summary": "Open an incident manually.", "operationId": "post_incidents", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentCreate" } } } } } }, "/incidents/{id}": { "get": { "tags": [ "Incidents" ], "summary": "Incident detail with linked alerts, IOCs, tasks and timeline. Supports ETag / If-None-Match.", "operationId": "get_incidents_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/incidents/{id}/status": { "patch": { "tags": [ "Incidents" ], "summary": "Transition incident status.", "operationId": "patch_incidents_id_status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusChange" } } } } } }, "/incidents/{id}/notes": { "post": { "tags": [ "Incidents" ], "summary": "Append a timeline note.", "operationId": "post_incidents_id_notes", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } } } }, "/alerts": { "get": { "tags": [ "Alerts" ], "summary": "Live SIEM alerts aggregated from the organization connectors. Filter: severity.", "operationId": "get_alerts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertList" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/vulnerabilities": { "get": { "tags": [ "Vulnerabilities" ], "summary": "List findings (cursor paginated). Filters: status, severity, category, cve, target, priority_min, kev.", "operationId": "get_vulnerabilities", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingPage" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/vulnerabilities/{id}": { "get": { "tags": [ "Vulnerabilities" ], "summary": "Finding detail with evidence and validation. Supports ETag.", "operationId": "get_vulnerabilities_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Finding" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/vulnerabilities/{id}/status": { "patch": { "tags": [ "Vulnerabilities" ], "summary": "Set finding status (open, remediated, false_positive, accepted).", "operationId": "patch_vulnerabilities_id_status", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Finding" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusChange" } } } } } }, "/scans": { "get": { "tags": [ "Scans" ], "summary": "List scans (cursor paginated).", "operationId": "get_scans", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanPage" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" }, "post": { "tags": [ "Scans" ], "summary": "Queue a scan on a verified target.", "operationId": "post_scans", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.run", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanCreate" } } } } } }, "/scans/{id}": { "get": { "tags": [ "Scans" ], "summary": "Scan detail with result.", "operationId": "get_scans_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/targets": { "get": { "tags": [ "Targets" ], "summary": "List scan targets and their verification status.", "operationId": "get_targets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetList" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" }, "post": { "tags": [ "Targets" ], "summary": "Register a target; it must be verified (DNS TXT or signed agreement) before scanning.", "operationId": "post_targets", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Target" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "targets.manage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetCreate" } } } } } }, "/targets/{id}/verification": { "get": { "tags": [ "Targets" ], "summary": "Verification status and the DNS TXT challenge to publish.", "operationId": "get_targets_id_verification", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetVerification" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/iocs/lookup": { "get": { "tags": [ "Indicators" ], "summary": "Enrich an indicator (type: ip, domain, hash, cve) with local and intelligence context.", "operationId": "get_iocs_lookup", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ip", "domain", "hash", "cve" ] } }, { "name": "value", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IocEnrichment" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/response/actions": { "get": { "tags": [ "Response" ], "summary": "List containment actions. Approval is only possible from the UI with re-authentication.", "operationId": "get_response_actions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseActionList" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" }, "post": { "tags": [ "Response" ], "summary": "Request a containment action (pending human approval).", "operationId": "post_response_actions", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseAction" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "422": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "response.request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseActionCreate" } } } } } }, "/reports": { "get": { "tags": [ "Reports" ], "summary": "List generated reports.", "operationId": "get_reports", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportList" } } } }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } }, "/reports/{id}/download": { "get": { "tags": [ "Reports" ], "summary": "Download a generated report (integrity verified).", "operationId": "get_reports_id_download", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Problem" }, "403": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" } }, "x-required-ability": "scans.view" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token format sntl__, created in API & SSO." } }, "schemas": { "Health": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "organization": { "type": "string", "nullable": true } } }, "Posture": { "type": "object", "properties": { "score": { "type": "integer" }, "vulnerabilities": { "type": "object" }, "alerts": { "type": "object" }, "incidents": { "type": "object" }, "coverage": { "type": "object" } } }, "Incident": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "category": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "asset": { "type": "string", "nullable": true }, "attacker": { "type": "string", "nullable": true }, "alert_count": { "type": "integer" }, "mitre": { "type": "array", "items": { "type": "string" } }, "iocs": { "type": "array", "items": { "type": "object" } }, "detected_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "nis2_significant_at": { "type": "string", "format": "date-time", "nullable": true } } }, "IncidentPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "category": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "asset": { "type": "string", "nullable": true }, "attacker": { "type": "string", "nullable": true }, "alert_count": { "type": "integer" }, "mitre": { "type": "array", "items": { "type": "string" } }, "iocs": { "type": "array", "items": { "type": "object" } }, "detected_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "nis2_significant_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "meta": { "type": "object" }, "links": { "type": "object" } } }, "IncidentCreate": { "type": "object", "required": [ "title", "severity" ], "properties": { "title": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "asset": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" } } }, "StatusChange": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" }, "note": { "type": "string" } } }, "Note": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "AlertList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object" } } }, "Finding": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "target": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "category": { "type": "string", "nullable": true }, "status": { "type": "string" }, "cve_id": { "type": "string", "nullable": true }, "cwe": { "type": "string", "nullable": true }, "cvss_score": { "type": "number", "nullable": true }, "epss_score": { "type": "number", "nullable": true }, "priority_score": { "type": "integer", "nullable": true }, "validation_status": { "type": "string", "nullable": true }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "FindingPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "target": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "info" ] }, "category": { "type": "string", "nullable": true }, "status": { "type": "string" }, "cve_id": { "type": "string", "nullable": true }, "cwe": { "type": "string", "nullable": true }, "cvss_score": { "type": "number", "nullable": true }, "epss_score": { "type": "number", "nullable": true }, "priority_score": { "type": "integer", "nullable": true }, "validation_status": { "type": "string", "nullable": true }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "meta": { "type": "object" }, "links": { "type": "object" } } }, "Scan": { "type": "object", "properties": { "id": { "type": "integer" }, "runner": { "type": "string" }, "target": { "type": "string" }, "status": { "type": "string" }, "result": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ScanPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "type": "object" }, "links": { "type": "object" } } }, "ScanCreate": { "type": "object", "required": [ "runner", "target" ], "properties": { "runner": { "type": "string" }, "target": { "type": "string" } } }, "Target": { "type": "object", "properties": { "id": { "type": "integer" }, "host": { "type": "string" }, "label": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "verified": { "type": "boolean" }, "verification_method": { "type": "string", "nullable": true } } }, "TargetList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "TargetCreate": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string" }, "label": { "type": "string" } } }, "TargetVerification": { "type": "object", "properties": { "verified": { "type": "boolean" }, "method": { "type": "string", "nullable": true }, "dns_txt_record": { "type": "string" }, "dns_txt_value": { "type": "string" } } }, "IocEnrichment": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "verdict": { "type": "string" }, "data": { "type": "object" }, "fetched_at": { "type": "string", "format": "date-time" } } }, "ResponseAction": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "target": { "type": "string" }, "status": { "type": "string" }, "requested_by": { "type": "string" }, "approved_by": { "type": "string", "nullable": true }, "incident_id": { "type": "integer", "nullable": true } } }, "ResponseActionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "ResponseActionCreate": { "type": "object", "required": [ "type", "target", "connector_id" ], "properties": { "type": { "type": "string" }, "target": { "type": "string" }, "connector_id": { "type": "integer" }, "incident_id": { "type": "integer" }, "reason": { "type": "string" }, "ttl_minutes": { "type": "integer" } } }, "ReportList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } } }, "responses": { "Problem": { "description": "Error (RFC 7807)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }