Investigations - SoCMate

Investigations are the core workflow in SoCMate. You ask a security question in natural language, and SoCMate’s investigation engine queries Microsoft Sentinel and produces a structured report.

Starting an Investigation

From the UI

Click New Investigation from the dashboard or sidebar. Select a persona and type your query in the chat interface.

From the API

curl -X POST https://api.socmate.yourcompany.com/api/v1/investigations/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Investigate failed sign-in attempts for user john@example.com in the last 7 days",
    "persona": "soc_analyst",
    "provider": "sentinel"
  }'

Response:

{
  "session_id": "sess_abc123",
  "status": "active"
}

How Investigations Work

Every query is processed by SoCMate’s investigation engine. Each stage is visible in the UI as a real-time progress indicator.

Entity Extraction

SoCMate extracts security entities from your query — IP addresses, usernames, hostnames, domains, file hashes, email addresses, and more. Each entity is tagged with a type and confidence score.

Intent Determination

The system classifies your investigation type: triage (quick assessment), investigation (deep dive), hunting (proactive threat search), or compliance (audit-focused).

Query Planning

Based on the entities and intent, SoCMate selects relevant Sentinel tables (e.g., SigninLogs, CommonSecurityLog, DeviceNetworkEvents) and defines a query strategy with time ranges.

Query Generation

SoCMate generates optimized KQL queries using table metadata and schema information. Queries include proper filtering, projection, and sorting.

Execution

Each query runs against Microsoft Sentinel via the Azure Monitor API. Results are collected and cross-referenced.

Evidence Assessment

SoCMate evaluates whether the collected evidence adequately answers the original question. It checks question coverage, entity coverage, temporal coverage, and evidence quality. If gaps are found, additional queries are generated automatically.

Report Generation

A persona-aware report is generated. SOC Analyst reports include technical IOCs, KQL queries, and MITRE ATT&CK mappings. CISO reports include executive summaries and business impact assessments.

Knowledge Graph Update

Extracted entities and relationships are persisted to the knowledge graph. The session is marked as completed and indexed for search.

Personas

Personas control the tone, detail level, and structure of investigation reports.

SOC Analyst
CISO

Technical reports tailored for hands-on analysts:

Full technical details and raw data
IOCs with copy-paste values
KQL queries for manual verification
MITRE ATT&CK technique IDs and descriptions
Step-by-step remediation recommendations
Timeline of observed events

Follow-Up Questions

You can ask follow-up questions in the same session. SoCMate retains full context from all prior queries, results, and entities.

curl -X POST https://api.socmate.yourcompany.com/api/v1/investigations/sess_abc123/followup \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Were there any successful logins from the same IP after the failed attempts?"
  }'

Follow-ups benefit from:

All previously extracted entities are known
Prior query results are available for cross-referencing
The knowledge graph grows with each follow-up

Real-Time Streaming

Subscribe to investigation events via Server-Sent Events (SSE) or WebSocket:

SSE
WebSocket

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer <token>" \
  https://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123/stream

Events are sent as they occur:

event: run.started
data: {"type":"run.started","session_id":"sess_abc123","run_id":"run_001"}

event: agent.event
data: {"type":"agent.event","data":{"message":"Extracting entities..."}}

event: tool.call
data: {"type":"tool.call","data":{"tool_name":"kql_query","parameters":{"query":"SigninLogs | where ..."}}}

event: agent.message
data: {"type":"agent.message","data":{"content":"## Investigation Report\n..."}}

event: run.completed
data: {"type":"run.completed","data":{"result":{"risk_score":7.5,"entities":[...]}}}

const ws = new WebSocket(
  "wss://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123/ws?run_id=run_001"
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Event: ${data.type}`, data);
};

Event Types

Event	Description
`run.started`	Investigation has begun
`agent.event`	Progress update (entity extraction, planning, etc.)
`agent.delta`	Streaming report tokens (partial content)
`agent.message`	Complete report response
`tool.call`	Query execution with parameters and results
`entity.diagram`	Entity relationship diagram generated
`clarification.needed`	Investigation needs user input to continue
`error`	Error during investigation
`run.completed`	Investigation finished with final results

Session Management

List Sessions

curl -X GET "https://api.socmate.yourcompany.com/api/v1/sessions/?status=completed&limit=10" \
  -H "Authorization: Bearer <token>"

Pin a Session

curl -X PATCH https://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123/pin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Fork a Session

Create a copy of a session to explore a different line of investigation:

curl -X POST https://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123/fork \
  -H "Authorization: Bearer <token>"

Delete a Session

curl -X DELETE https://api.socmate.yourcompany.com/api/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer <token>"

Investigation Results

The final investigation result includes:

{
  "entities": [
    { "value": "203.0.113.50", "type": "ip", "confidence": 0.95 }
  ],
  "relationships": [
    { "source": "john@example.com", "target": "203.0.113.50", "type": "SIGNED_IN_FROM" }
  ],
  "findings": [
    "42 failed sign-in attempts detected from IP 203.0.113.50",
    "Source IP geolocated to Eastern Europe"
  ],
  "recommendations": [
    "Block IP 203.0.113.50 at the firewall",
    "Reset credentials for john@example.com"
  ],
  "risk_score": 7.5,
  "summary": "Investigation report content...",
  "charts": [...],
  "tables": [...]
}

Search Past Investigations

Search across all completed investigations:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/search?q=brute+force&mode=hybrid&top=10" \
  -H "Authorization: Bearer <token>"

Search modes:

hybrid (default) — Combined keyword and semantic vector search
keyword — Traditional keyword matching
vector — Semantic similarity search

Find investigations similar to an existing one:

curl -X GET "https://api.socmate.yourcompany.com/api/v1/search/similar/sess_abc123?limit=5" \
  -H "Authorization: Bearer <token>"

Platform

​Starting an Investigation

​From the UI

​From the API

​How Investigations Work

​Personas

​Follow-Up Questions

​Real-Time Streaming

​Event Types

​Session Management

​List Sessions

​Pin a Session

​Fork a Session

​Delete a Session

​Investigation Results

​Search Past Investigations