Skip to main content

​
Architecture

Chronos-DFIR provides a FastAPI-based REST API for forensic timeline analysis and DFIR data processing. The API is designed for high-performance streaming operations on large evidence files (6GB+) using:
  • Polars lazy evaluation for out-of-core processing
  • Streaming I/O with chunked uploads/downloads
  • Async-first endpoints for concurrent operations
  • Chain of custody with SHA256 hashing during upload

​
Base URL

All API endpoints are served from the application root: 
http://localhost:8000
The API runs on port 8000 by default. Use uvicorn app:app --host 0.0.0.0 --port 8000 to start the server.

​
Authentication

Chronos-DFIR does not require authentication for local forensic analysis workflows. The API is designed for:
  • Local deployment on analyst workstations
  • Air-gapped environments for sensitive investigations
  • Trusted network access only
Do NOT expose the API to untrusted networks. Use SSH tunneling or VPN for remote access.

​
Request/Response Format

​
Content Types

  • JSON: Default for all structured data exchanges
  • Multipart Form Data: File uploads (/upload endpoint)
  • Binary Streams: Large file downloads

​
Common Request Headers

Content-Type: application/json
Accept: application/json

​
Standard Response Schema

Success responses follow this pattern: 
{
  "status": "success",
  "data": { /* endpoint-specific payload */ },
  "metadata": { /* optional */ }
}
Error responses: 
{
  "error": "Detailed error message",
  "status_code": 500
}

​
Pagination

Endpoints returning large datasets use cursor-based pagination:
​
page
integer
default:"1"
Current page number (1-indexed)
​
size
integer
default:"50"
Records per page (max: 1000)
Paginated response format: 
{
  "current_page": 1,
  "last_page": 842,
  "total": 42084,
  "total_unfiltered": 85000,
  "data": [ /* records */ ]
}

​
Filtering & Querying

Chronos-DFIR supports unified filtering across all data endpoints:

​
Global Text Search

​
query
string
Case-insensitive search across ALL columns. Uses Polars vectorized string matching.
curl "http://localhost:8000/api/data/file.csv?query=powershell"

​
Column Filters

​
col_filters
string
JSON-encoded object mapping column names to filter values. Supports exact match and regex.
curl "http://localhost:8000/api/data/file.csv?col_filters={\"EventID\":\"4624\"}"

​
Time Range Filtering

​
start_time
string
Filter events after this timestamp (inclusive)
​
end_time
string
Filter events before this timestamp (inclusive)
curl "http://localhost:8000/api/data/file.csv?start_time=2024-01-01T00:00:00&end_time=2024-01-02T00:00:00"

​
Row Selection

​
selected_ids
string
JSON array of row IDs for subset analysis (e.g., ["5", "20", "100"])

​
Sorting

​
sort_col
string
Column name to sort by
​
sort_dir
string
Sort direction (ascending or descending)
Alternatively, use Tabulator.js format: 
curl "http://localhost:8000/api/data/file.csv?sort[0][field]=Time&sort[0][dir]=desc"

​
Error Handling

​
HTTP Status Codes

CodeMeaningExample
200SuccessData retrieved successfully
400Bad RequestInvalid filter syntax
404Not FoundFile does not exist
500Internal ErrorProcessing failure
504Gateway TimeoutEnrichment timeout (30s limit)

​
Common Error Scenarios

{
  "error": "File not found",
  "status_code": 404
}

​
Performance Considerations

​
Streaming Architecture

Chronos-DFIR uses lazy evaluation with Polars scan_csv() and sink_csv() to process files larger than available RAM:
  • Files are never fully loaded into memory
  • Filters are pushed down to the scan layer
  • Only requested pages are materialized

​
Rate Limiting

No built-in rate limiting. For production deployments, use:
  • Nginx rate limiting (limit_req_zone)
  • Traefik middleware
  • API Gateway (AWS, Azure)

​
Concurrent Requests

FastAPI supports async concurrency. The forensic report endpoint uses asyncio.gather() to parallelize:
  • Timeline analysis
  • Sigma rule matching
  • YARA scanning
  • Threat intelligence enrichment
Peak parallelism: 9 concurrent tasks in /api/forensic_report

​
Data Formats

​
Supported Input Formats

FormatExtensionParser
CSV.csvPolars scan_csv
Excel.xlsxPolars read_excel
JSON.json, .jsonl, .ndjsonPolars read_json
Parquet.parquetPolars scan_parquet
SQLite.db, .sqlite, .sqlite3Cursor + Polars DataFrame
Plist.plistplistlib + Polars
MFT.mftCustom binary parser
EVTX.evtxevtx_dump + Polars
Whitespace-delimited.pslist, .txt, .logRegex parser
ZIP.zipAutomatic extraction

​
Output Formats

  • CSV: UTF-8 with BOM (Excel-compatible)
  • XLSX: xlsxwriter with text formatting for hex values
  • JSON: Standard array format [{...}, {...}]
  • PDF: Multi-method fallback (WeasyPrint → Playwright → xhtml2pdf)
  • HTML: Standalone report with embedded Chart.js

​
Chain of Custody

All file uploads compute SHA256 hash during streaming upload (zero extra I/O): 
{
  "chain_of_custody": {
    "sha256": "a3f5b2c1...",
    "file_size_bytes": 6442450944,
    "original_filename": "Security.evtx"
  }
}
Timestamps in parsed artifacts (MFT, EVTX) are never fabricated. If parsing fails, fields are set to null to maintain forensic integrity.

​
API Endpoint Categories

  • Upload: File ingestion with artifact-type routing
  • Analysis: Data retrieval, histogram, forensic reports
  • Export: Multi-format exports (CSV, XLSX, PDF, HTML, JSON)

​
Next Steps

Upload Endpoint

Stream forensic artifacts with chain of custody

Analysis Endpoints

Query timelines, generate histograms, run forensic reports

Export Endpoints

Export filtered datasets in CSV, XLSX, PDF, HTML

Build docs developers (and LLMs) love

Get started for freeTalk to us