Analysis Endpoints

GET /api/data/

Retrieve paginated timeline data with filtering, sorting, and time range queries. Uses lazy evaluation for out-of-core processing.

Path Parameters

filename

string

required

CSV filename returned from /upload endpoint (e.g., Security_evtx_1704067200.csv)

Query Parameters

page

integer

default:"1"

Page number (1-indexed)

size

integer

default:"50"

Records per page (max: 1000)

query

string

Global search query (case-insensitive, searches all columns)

start_time

string

Filter events after this timestamp (inclusive)

end_time

string

Filter events before this timestamp (inclusive)

col_filters

string

Column-specific filters (e.g., {"EventID":"4624","User":"admin"})

sort_col

string

Column name to sort by (alternative: sort[0][field] for Tabulator.js compatibility)

sort_dir

string

Sort direction (alternative: sort[0][dir])

Response Schema

current_page

integer

Current page number

last_page

integer

Total number of pages

total

integer

Total records matching filters

total_unfiltered

integer

Total records in file (before filters)

data

array

Array of timeline events (objects with dynamic schema)

start_time

string

Earliest timestamp in filtered dataset

end_time

string

Latest timestamp in filtered dataset

Examples

curl "http://localhost:8000/api/data/Security_evtx_1704067200.csv?page=1&size=50"

Response Example

{
  "current_page": 1,
  "last_page": 842,
  "total": 42084,
  "total_unfiltered": 85000,
  "start_time": "2024-01-01T00:00:00.000Z",
  "end_time": "2024-01-07T23:59:59.999Z",
  "data": [
    {
      "_id": 1,
      "Time": "2024-01-01T08:23:45.123Z",
      "EventID": "4624",
      "User": "SYSTEM",
      "Computer": "WORKSTATION-01",
      "Message": "An account was successfully logged on"
    },
    {
      "_id": 2,
      "Time": "2024-01-01T08:24:12.456Z",
      "EventID": "4688",
      "User": "admin",
      "CommandLine": "powershell.exe -ExecutionPolicy Bypass"
    }
  ]
}

GET /api/histogram/

Generate time-series histogram with event distribution, peaks, and outlier detection.

Path Parameters

filename

string

required

CSV filename from upload

Query Parameters

exclude_id

string

EventID to exclude from histogram (e.g., 4624 for logon noise reduction)

start_time

string

Time range start

end_time

string

Time range end

query

string

Global search filter

col_filters

string

Column-specific filters

selected_ids

string

Row IDs for subset histogram (e.g., ["5","20","100"])

Response Schema

labels

array<string>

X-axis labels (timestamps or time buckets)

datasets

array<object>

Chart.js dataset objects with event counts per bucket

stats

object

Statistical summary

peak

integer

Maximum events in a single bucket

mean

float

Average events per bucket

start_time

string

Dataset start timestamp

end_time

string

Dataset end timestamp

interpretation

string

Human-readable summary (e.g., “High activity spike detected at 2024-01-01 14:00”)

Example

curl "http://localhost:8000/api/histogram/Security_evtx_1704067200.csv?exclude_id=4624"

Response Example

{
  "labels": ["2024-01-01 08:00", "2024-01-01 09:00", "2024-01-01 10:00"],
  "datasets": [
    {
      "label": "Event Distribution",
      "data": [1250, 3420, 2180],
      "backgroundColor": "rgba(30, 58, 95, 0.8)",
      "type": "bar"
    },
    {
      "label": "Peak Threshold",
      "data": [3420, 3420, 3420],
      "borderColor": "#dc2626",
      "type": "line"
    }
  ],
  "stats": {
    "peak": 3420,
    "mean": 2283.3,
    "start_time": "2024-01-01T08:00:00.000Z",
    "end_time": "2024-01-01T23:59:59.999Z"
  },
  "interpretation": "High activity spike detected at 2024-01-01 09:00 (150% above baseline)"
}

POST /api/forensic_report

Generate comprehensive forensic analysis with parallel execution of:

Timeline analysis (peaks, gaps, anomalies)
Context extraction (users, IPs, processes)
Threat hunting (suspicious patterns)
Sigma rule matching (86 rules)
YARA scanning
MITRE ATT&CK mapping
Cross-source correlation
Session profiling
Risk scoring (Smart Risk Engine M4)
Threat intelligence enrichment

Request Body

filename

string

required

CSV filename to analyze

query

string

Global search filter

col_filters

object

Column-specific filters

selected_ids

array<string>

Row IDs for subset analysis

start_time

string

Time range start

end_time

string

Time range end

sort_col

string

Sort column

sort_dir

string

Sort direction

Response Schema

total_records

integer

Number of events analyzed

filename

string

Source filename

top_tactic

string

Most common tactic/event type (e.g., “Win EventID 4688: Process Creation”)

primary_identity

string

Most active user/IP

risk_level

string

Overall risk assessment

risk_score

integer

Numeric risk score

risk_justify

array<string>

Risk justification factors (e.g., [“Sigma critical hit: Mimikatz detected”, “Lateral movement detected”])

eps

float

Events per second (activity rate)

results

array<object>

Analysis results from 4 parallel tasks:

Timeline: Peaks, gaps, time range
Context: Users, IPs, hosts, paths, event IDs
Hunting: Suspicious patterns, network connections, logon events
Identity: Top processes, rare executions, asset inventory

sigma_hits

array<object>

Matched Sigma rules with evidence rows

title

string

Rule name

level

string

Severity level

mitre_technique

string

MITRE ATT&CK technique ID (e.g., “T1059.001”)

matched_rows

integer

Total matching events

sample_evidence

array<object>

First 150 matching rows with forensic context columns

all_row_ids

array<integer>

All matching row IDs (up to 500)

yara_hits

array<object>

YARA rule matches (scans first 5MB of CSV text)

mitre_kill_chain

array<object>

MITRE ATT&CK tactics derived from Sigma hits

cross_source_correlation

object

Cross-file correlation chains (user, IP, process pivots)

session_profiles

array<object>

Session behavior profiles (dwell time, request patterns)

execution_artifacts

object

Detected execution artifacts (Prefetch, ShimCache, AmCache)

threat_intelligence

object

IOC enrichment from threat feeds (VirusTotal, AbuseIPDB, etc.)

Example

curl -X POST http://localhost:8000/api/forensic_report \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "Security_evtx_1704067200.csv"
  }'

Response Example (Abbreviated)

{
  "total_records": 42084,
  "filename": "Security_evtx_1704067200.csv",
  "top_tactic": "Win EventID 4688: Process Creation",
  "primary_identity": "admin",
  "risk_level": "High",
  "risk_score": 78,
  "risk_justify": [
    "Sigma critical hit: Mimikatz Execution Detected",
    "Lateral movement to 5 hosts",
    "Suspicious PowerShell execution (-EncodedCommand)"
  ],
  "eps": 2.45,
  "results": [
    {
      "type": "timeline",
      "peaks": [
        {"hour": "2024-01-01 14:00", "count": 3420}
      ],
      "time_range": "2024-01-01 to 2024-01-07"
    },
    {
      "type": "context",
      "users": [{"id": "admin", "count": 12500}],
      "ips": [{"id": "192.168.1.100", "count": 8200}]
    }
  ],
  "sigma_hits": [
    {
      "title": "Mimikatz Execution Detected",
      "level": "critical",
      "mitre_technique": "T1003.001",
      "matched_rows": 3,
      "sample_evidence": [
        {
          "Time": "2024-01-01T14:23:45.123Z",
          "EventID": "4688",
          "CommandLine": "mimikatz.exe sekurlsa::logonpasswords",
          "User": "admin"
        }
      ],
      "all_row_ids": [1250, 1251, 1252]
    }
  ],
  "yara_hits": [
    {
      "rule": "Mimikatz_Keywords",
      "namespace": "windows",
      "tags": ["credential_dumping"],
      "strings_matched": 2
    }
  ],
  "mitre_kill_chain": [
    {
      "tactic": "Credential Access",
      "threat_level": "critical",
      "count": 3,
      "description": "T1003.001: LSASS Memory Dumping"
    }
  ]
}

Performance

Report generation uses parallel execution with asyncio.gather() (9 concurrent tasks):

Timeline analysis: ~0.8s
Context extraction: ~1.2s
Hunting patterns: ~1.5s
Identity analysis: ~1.0s
Sigma matching: ~2.5s
YARA scan: ~0.5s
Correlation: ~1.8s
Sessions: ~1.2s
Execution artifacts: ~0.9s
Total: ~3.5s (wall-clock time, 9 tasks in parallel)

Tested on 42,084 EVTX events

Threat intelligence enrichment adds 5-30s depending on API rate limits.

POST /api/histogram_subset

Generate histogram for selected rows only (subset analysis).

Request Body

filename

string

required

CSV filename

selected_ids

array<string>

required

Row IDs to include (e.g., ["5", "20", "100"])

query

string

Global search filter

col_filters

object

Column filters

start_time

string

Time range start

end_time

string

Time range end

Response

Same schema as /api/histogram/{filename} with interpretation prefixed by "Filtered View: ".

GET /api/empty_columns/

Identify completely empty columns (all nulls or empty strings) for UI optimization.

Query Parameters

Same filtering params as /api/data/{filename} (query, col_filters, start_time, end_time, selected_ids).

Response

{
  "empty_columns": ["Field5", "Hashes", "ParentImage"]
}

Excludes internal columns (_id, No., Original_No.) from empty check.

GET /api/timeseries/

Advanced timeseries analysis with trend detection and peak identification using the chronos_timeseries_builder skill.

Response Schema

trend

string

Trend direction (rising, falling, stable)

peaks

array<object>

Detected peaks with timestamps and magnitudes

chart_data

object

Chart.js-compatible dataset

Next Steps

Export Endpoints

Export filtered datasets in CSV, XLSX, PDF, HTML formats

Endpoints

Engine Modules

GET /api/data/

Path Parameters

Query Parameters

Response Schema

Examples

Response Example

GET /api/histogram/

Path Parameters

Query Parameters

Response Schema

Example

Response Example

POST /api/forensic_report

Request Body

Response Schema

Example

Response Example (Abbreviated)

Performance

POST /api/histogram_subset

Request Body

Response

GET /api/empty_columns/

Query Parameters

Response

GET /api/timeseries/

Response Schema

Next Steps

Export Endpoints

Build docs developers (and LLMs) love

Endpoints

Engine Modules

​GET /api/data/

​Path Parameters

​Query Parameters

​Response Schema

​Examples

​Response Example

​GET /api/histogram/

​Path Parameters

​Query Parameters

​Response Schema

​Example

​Response Example

​POST /api/forensic_report

​Request Body

​Response Schema

​Example

​Response Example (Abbreviated)

​Performance

​POST /api/histogram_subset

​Request Body

​Response

​GET /api/empty_columns/

​Query Parameters

​Response

​GET /api/timeseries/

​Response Schema

​Next Steps

Export Endpoints

Build docs developers (and LLMs) love

GET /api/data/

Path Parameters

Query Parameters

Response Schema

Examples

Response Example

GET /api/histogram/

Path Parameters

Query Parameters

Response Schema

Example

Response Example

POST /api/forensic_report

Request Body

Response Schema

Example

Response Example (Abbreviated)

Performance

POST /api/histogram_subset

Request Body

Response

GET /api/empty_columns/

Query Parameters

Response

GET /api/timeseries/

Response Schema

Next Steps