AI Analysis

POST/api/v1/ai/analysis

Perform deep AI-driven analysis on security events. Identifies root cause, builds attack timelines, maps to MITRE ATT&CK techniques, and provides detailed incident response recommendations.

Permission

ai:read

Credits

15 per request

Plans

Starter, Professional, Enterprise

Timeout

Up to 60 seconds

Request Body

{
  "events": {
    "logs": [
      { "timestamp": "...", "source": "firewall", "action": "allow", ... },
      { "timestamp": "...", "source": "auth", "action": "login_success", ... },
      { "timestamp": "...", "source": "endpoint", "action": "process_create", ... }
    ]
  },
  "context": "Production environment, server handles customer PII",
  "scope": "incident"
}

Field	Type	Description
events	object	Object containing security events to analyze — typically a `logs` array of event objects with timestamps and details (required)
context	string	Additional context about the environment, affected systems, or business impact to improve analysis accuracy (optional)
scope	string	Analysis scope: `"incident"`, `"campaign"`, or `"artifact"` (optional — default: incident)

Response

{
  "data": {
    "summary": "Successful SSH brute-force intrusion from Tor exit node followed by post-exploitation reconnaissance on production server containing customer PII. Attacker gained admin-level access and began system enumeration within minutes of initial compromise.",
    "severity": "critical",
    "impact": "Full administrative access achieved on production server handling customer PII. Attacker performed host reconnaissance indicating preparation for lateral movement or data exfiltration.",
    "root_cause": "Weak SSH password for admin account combined with lack of brute-force protection allowed credential compromise from a known malicious IP address.",
    "timeline": [
      {
        "timestamp": "2026-04-03T14:20:00Z",
        "description": "Firewall allowed inbound SSH connection from 185.220.101.42 (known Tor exit node) to production server 10.0.1.15"
      },
      {
        "timestamp": "2026-04-03T14:22:00Z",
        "description": "Successful SSH login as admin from attacker IP after brute-force attempt window"
      },
      {
        "timestamp": "2026-04-03T14:25:00Z",
        "description": "Post-exploitation: attacker executed whoami.exe via cmd.exe to enumerate current user context"
      }
    ],
    "indicators": [
      { "type": "ip", "value": "185.220.101.42", "role": "attacker" },
      { "type": "ip", "value": "10.0.1.15", "role": "target" },
      { "type": "user", "value": "admin", "role": "compromised_account" },
      { "type": "process", "value": "whoami.exe", "role": "recon_tool" }
    ],
    "attack_mapping": [
      {
        "technique_id": "T1110.001",
        "name": "Brute Force: Password Guessing",
        "tactic": "Credential Access",
        "confidence": 93
      },
      {
        "technique_id": "T1033",
        "name": "System Owner/User Discovery",
        "tactic": "Discovery",
        "confidence": 97
      },
      {
        "technique_id": "T1021.004",
        "name": "Remote Services: SSH",
        "tactic": "Lateral Movement",
        "confidence": 90
      }
    ],
    "recommendations": [
      "Immediately isolate srv-prod-01 from the network to prevent lateral movement",
      "Reset the admin account credentials and revoke all active sessions",
      "Block 185.220.101.42 and all known Tor exit nodes at the perimeter firewall",
      "Perform a full forensic analysis of srv-prod-01 for persistence mechanisms",
      "Audit all PII access logs for evidence of data exfiltration",
      "Implement SSH key-based authentication and disable password login",
      "Deploy account lockout policies and fail2ban on all SSH-exposed servers"
    ]
  },
  "meta": {
    "request_id": "req_a5n6a7l8-...",
    "credits_used": 15,
    "credits_remaining": 475,
    "processing_time_ms": 5830
  }
}

Field	Type	Description
data.summary	string	Executive summary of the analysis findings
data.severity	string	"info", "low", "medium", "high", or "critical"
data.impact	string	Assessment of the business and security impact of the analyzed events
data.root_cause	string	Identified root cause of the incident or security event chain
data.timeline	array	Ordered timeline of events with timestamp and description for each step in the attack chain
data.indicators	array	Extracted indicators with type, value, and role (attacker, target, compromised_account, recon_tool, etc.)
data.attack_mapping	array	MITRE ATT&CK technique mappings with technique_id, name, tactic, and confidence score
data.recommendations	array	Prioritized list of incident response and remediation recommendations
meta.request_id	string	Unique request identifier for support and debugging
meta.credits_used	number	Credits consumed (15 per analysis request)
meta.credits_remaining	number	Remaining credit balance after this request
meta.processing_time_ms	number	Server-side processing time in milliseconds

Code Examples

cURL

curl -X POST https://api.dfir-lab.ch/v1/ai/analysis \
  -H "Authorization: Bearer sk-dfir-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": {
      "logs": [
        {
          "timestamp": "2026-04-03T14:20:00Z",
          "source": "firewall",
          "action": "allow",
          "src_ip": "185.220.101.42",
          "dst_ip": "10.0.1.15",
          "dst_port": 22,
          "protocol": "tcp"
        },
        {
          "timestamp": "2026-04-03T14:22:00Z",
          "source": "auth",
          "action": "login_success",
          "user": "admin",
          "src_ip": "185.220.101.42",
          "dst_ip": "10.0.1.15"
        },
        {
          "timestamp": "2026-04-03T14:25:00Z",
          "source": "endpoint",
          "action": "process_create",
          "host": "srv-prod-01",
          "process": "whoami.exe",
          "parent": "cmd.exe",
          "user": "admin"
        }
      ]
    },
    "context": "Production environment, server handles customer PII",
    "scope": "incident"
  }'

Python

import requests

response = requests.post(
    "https://api.dfir-lab.ch/v1/ai/analysis",
    headers={
        "Authorization": "Bearer sk-dfir-your-key-here",
        "Content-Type": "application/json",
    },
    json={
        "events": {
            "logs": [
                {
                    "timestamp": "2026-04-03T14:20:00Z",
                    "source": "firewall",
                    "action": "allow",
                    "src_ip": "185.220.101.42",
                    "dst_ip": "10.0.1.15",
                    "dst_port": 22,
                },
                {
                    "timestamp": "2026-04-03T14:22:00Z",
                    "source": "auth",
                    "action": "login_success",
                    "user": "admin",
                    "src_ip": "185.220.101.42",
                },
            ]
        },
        "context": "Production environment, server handles customer PII",
        "scope": "incident",
    },
)

data = response.json()
analysis = data["data"]
print(f"Severity: {analysis['severity']}")
print(f"Summary: {analysis['summary']}")
print(f"Root cause: {analysis['root_cause']}")

for step in analysis["timeline"]:
    print(f"  [{step['timestamp']}] {step['description']}")

Important Notes

The events object is flexible — include logs, alerts, or any structured security data. The AI model correlates events across sources and timestamps for comprehensive analysis.
Analysis scope affects depth: incident focuses on a single event chain, campaign correlates across multiple incidents, and artifact performs deep-dive analysis on a single artifact.
Each request consumes 15 credits. Results are generated fresh for every analysis — no caching is applied.

Back to API Docs