Appearance
Insider Risk API
All endpoints require authentication via API key or session cookie. Requests are scoped to the authenticated user’s organization.
Base path: /api/insider-risk
IOC definitions
Create IOC rule
Creates a new indicator-of-compromise (IOC) definition.
POST /api/insider-risk/iocsAuthentication: Required.
Query parameters: None.
Request body (JSON)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
name | string | Yes | Max 200 characters | Display name |
description | string | No | Max 2000 characters | Optional description |
ioc_type | string | Yes | — | One of: volume_spike, off_hours, geo_anomaly, data_exfil, access_pattern, custom |
pattern | string | Yes | — | JSON-encoded pattern definition |
severity | string | No | Default medium | One of: low, medium, high, critical |
enabled | boolean | No | Default true | Whether the rule is active |
alert_channels | string[] | No | Default ["webhook"] | Channels: webhook (SIEM event), email |
metadata | object | No | — | Optional metadata; e.g. {"notification_emails": ["security@acme.com"]} |
Response: 201 Created with an IOCResponse object.
IOCResponse
| Field | Type | Description |
|---|---|---|
id | string | IOC definition ID |
organization_id | string | Owning organization |
name | string | Name |
description | string | Description |
ioc_type | string | IOC type |
pattern | string | Pattern JSON |
severity | string | Severity |
enabled | boolean | Enabled flag |
alert_channels | string[] | Alert channels |
metadata | object | Metadata |
created_by | string | User ID of creator |
created_at | string | ISO 8601 timestamp |
updated_at | string | ISO 8601 timestamp |
Example
bash
curl -X POST "$BASE_URL/api/insider-risk/iocs" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Off-hours volume",
"description": "Alert on unusual after-hours activity",
"ioc_type": "off_hours",
"pattern": "{\"window_utc\": [22, 6]}",
"severity": "high",
"enabled": true,
"alert_channels": ["webhook", "email"],
"metadata": {"notification_emails": ["security@acme.com"]}
}'List IOC rules
Lists IOC definitions for the organization.
GET /api/insider-risk/iocsAuthentication: Required.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ioc_type | string | No | Filter by IOC type |
enabled_only | boolean | No | If true, only enabled rules |
Response: JSON array of IOCResponse.
Update IOC rule
Partially updates an IOC definition. Only supplied fields are changed.
PUT /api/insider-risk/iocs/{ioc_id}Authentication: Required.
Query parameters: None.
Request body (JSON): all fields optional.
| Field | Type | Description |
|---|---|---|
name | string | Max 200 characters |
description | string | Max 2000 characters |
pattern | string | JSON-encoded pattern |
severity | string | low, medium, high, critical |
enabled | boolean | Enabled flag |
alert_channels | string[] | Alert channels |
metadata | object | Metadata |
Response: 200 OK with IOCResponse.
Delete IOC rule
DELETE /api/insider-risk/iocs/{ioc_id}Authentication: Required.
Query parameters: None.
Request body: None.
Response: 204 No Content.
IOC match history
List matches
Returns IOC match events for the organization.
GET /api/insider-risk/ioc-matchesAuthentication: Required.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
ioc_id | string | No | — | Filter by IOC definition ID |
limit | integer | No | 50 | Page size, 1–500 |
unacknowledged_only | boolean | No | — | Only unacknowledged matches |
Response: JSON array of IOCMatchResponse.
| Field | Type | Description |
|---|---|---|
id | integer | Match record ID |
ioc_definition_id | string | IOC definition ID |
ioc_name | string | null | Resolved IOC name |
user_id | string | null | User if applicable |
session_id | string | null | Session if applicable |
event_type | string | Event type |
event_data | object | Event payload |
matched_at | string | ISO 8601 timestamp |
acknowledged | boolean | Acknowledgement state |
acknowledged_by | string | null | User who acknowledged |
acknowledged_at | string | null | ISO 8601 timestamp |
Example
bash
curl -G "$BASE_URL/api/insider-risk/ioc-matches" \
-H "Authorization: Bearer $GHOSTAI_API_KEY" \
--data-urlencode "limit=100" \
--data-urlencode "unacknowledged_only=true"Acknowledge match
Marks a match as acknowledged.
POST /api/insider-risk/ioc-matches/{match_id}/acknowledgeAuthentication: Required.
Query parameters: None.
Request body: None.
Response: 200 OK
json
{
"status": "acknowledged",
"match_id": 12345
}Baselines
List baseline summaries
Returns one summary row per user that has baseline data.
GET /api/insider-risk/baselinesAuthentication: Required.
Query parameters: None.
Request body: None.
Response: JSON array of BaselineSummary.
| Field | Type | Description |
|---|---|---|
user_id | string | User ID |
metrics_count | integer | Number of metrics |
latest_period | string | null | Latest period end (ISO 8601) |
risk_score | number | Risk score |
Get user baseline detail
Returns detailed baseline metrics for a single user.
GET /api/insider-risk/baselines/{target_user_id}Authentication: Required.
Path parameters
| Parameter | Description |
|---|---|
target_user_id | User whose baselines to load |
Query parameters: None.
Request body: None.
Response: JSON array of BaselineResponse (up to 100 rows, ordered by period_end descending).
| Field | Type | Description |
|---|---|---|
user_id | string | User ID |
metric_type | string | Metric type |
metric_name | string | Metric name |
baseline_value | number | Baseline value |
stddev | number | Standard deviation |
sample_count | integer | Sample count |
period_start | string | Period start (ISO 8601) |
period_end | string | Period end (ISO 8601) |
Compute baselines (admin)
Computes user activity baselines from audit logs for the organization.
POST /api/insider-risk/baselines/computeAuthentication: Required (admin operation).
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
period_days | integer | No | 7 | Baseline period length in days, 1–30 |
lookback_days | integer | No | 30 | Historical lookback in days, 7–90 |
Request body: None.
Response: 200 OK with BaselineComputeResponse.
| Field | Type | Description |
|---|---|---|
organization_id | string | Organization ID |
users_processed | integer | Users processed |
metrics_written | integer | Metrics written |
errors | integer | Error count |
period_start | string | Period start |
period_end | string | Period end |
Example
bash
curl -X POST "$BASE_URL/api/insider-risk/baselines/compute?period_days=7&lookback_days=30" \
-H "Authorization: Bearer $GHOSTAI_API_KEY"Anomaly detection
Scan for anomalies (admin)
Runs anomaly detection against baselines and emits events to SIEM as configured.
POST /api/insider-risk/anomalies/scanAuthentication: Required (admin operation).
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
warning_threshold | float | No | 2.5 | Warning deviation threshold, 1.0–5.0 |
critical_threshold | float | No | 3.5 | Critical deviation threshold, 2.0–10.0 |
Request body: None.
Response: 200 OK with AnomalyScanResponse.
| Field | Type | Description |
|---|---|---|
anomalies_found | integer | Count detected |
emitted_to_siem | integer | Events emitted to SIEM |
anomalies | array | List of AnomalyResponse |
Each AnomalyResponse object:
| Field | Type | Description |
|---|---|---|
id | string | Anomaly ID |
user_id | string | User ID |
metric_type | string | Metric type |
metric_name | string | Metric name |
current_value | number | Observed value |
baseline_value | number | Baseline |
stddev | number | Standard deviation |
deviation | number | Deviation score |
severity | string | Severity |
detected_at | string | ISO 8601 timestamp |
details | object | Additional details |
List anomalies
Returns recent anomaly detections.
GET /api/insider-risk/anomaliesAuthentication: Required.
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer | No | 50 | Max rows, 1–200 |
Request body: None.
Response: JSON array of AnomalyResponse.
Batch IOC evaluation (admin)
Evaluates IOC rules over a recent time window and persists matches.
POST /api/insider-risk/ioc-evaluateAuthentication: Required (admin operation).
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
since_hours | integer | No | 1 | Lookback window in hours, 1–24 |
Request body: None.
Response: 200 OK
json
{
"matches_found": 0,
"matches_persisted": 0,
"alerts_dispatched": 0,
"since": "2026-04-03T12:00:00+00:00"
}Secret vault mappings
Create mapping
Registers where a hashed secret is stored in an external vault.
POST /api/insider-risk/vault-mappingsAuthentication: Required.
Query parameters: None.
Request body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
secret_hash | string | Yes | Hash of the secret |
vault_provider | string | Yes | hashicorp_vault, aws_secrets_manager, or 1password |
vault_path | string | Yes | Path or identifier in the vault |
Response: 201 Created with SecretVaultMappingResponse.
| Field | Type | Description |
|---|---|---|
id | string | Mapping ID |
org_id | string | Organization ID |
secret_hash | string | Secret hash |
vault_provider | string | Provider |
vault_path | string | Vault path |
created_at | string | ISO 8601 timestamp |
last_used | string | null | Last use time if tracked |
List mappings
GET /api/insider-risk/vault-mappingsAuthentication: Required.
Query parameters: None.
Request body: None.
Response: JSON array of SecretVaultMappingResponse.
Delete mapping
DELETE /api/insider-risk/vault-mappings/{mapping_id}Authentication: Required.
Query parameters: None.
Request body: None.
Response: 204 No Content.
Event catalog
List event types
Returns audit event types for building access-pattern IOCs (same catalog semantics as the admin SIEM catalog, exposed here without the siem_integration feature flag).
GET /api/insider-risk/event-catalogAuthentication: Required.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
category | string | No | Filter by category |
Request body: None.
Response: JSON array of objects:
| Field | Type | Description |
|---|---|---|
event_type | string | Event type key |
name | string | null | Display name |
description | string | null | Description |
category | string | null | Category |
default_severity | string | null | Default severity |
TIP
The event catalog powers the IOC Access Pattern picker in the admin UI. It exposes the same data as GET /api/admin/siem/catalog without requiring the siem_integration feature flag.