Raven

A lightweight, zero-dependency PC flight recorder for Windows — records every process, connection, and resource spike to a local SQLite database you own.

• Watches processes, network connections, CPU/memory/disk spikes in real time
• All data stays on your machine — no cloud, no agent, no phoning home
• Single binary, no install required: drop it and run

---

Why Raven

When something weird happens on your machine — a mystery process, a spike that disappeared before you could investigate, a connection to an IP you don't recognise — you usually find out too late. Task Manager shows you the present. Raven records the past.

It runs quietly in the background and writes a timestamped event log to a local SQLite file. No vendor account. No telemetry. No cloud upload. You own the database and you can query it with any tool you like, not just Raven's TUI.

Security researchers use it to trace malware behaviour. Sysadmins use it to audit what ran on a machine before an incident. Developers use it to understand what their software actually does at runtime. If you've ever wished Windows had a black box, this is it.

---

Features

Event	What gets recorded
process_start	Process name, PID, timestamp
process_stop	Process name, PID, timestamp
cpu_spike	Utilisation % at spike time
mem_spike	Memory % and MB used
net_connect	Process name, remote IP:port
disk_spike	Combined R+W rate in MB/s

All events carry a severity (info, warning, alert) and are queryable by type, time range, and process name.

---

Quickstart

# Download the latest release
curl -LO https://github.com/HoraDomu/Raven/releases/latest/download/raven-windows-amd64.exe
Rename-Item raven-windows-amd64.exe raven.exe

# Run it (records + opens TUI viewer)
.\raven.exe

That's it. Raven creates ~\.raven\raven.db on first run and starts recording immediately.

---

Building from source

Requires Go 1.22+. No CGO. No external C libraries.

git clone https://github.com/HoraDomu/Raven.git
cd Raven
go mod tidy
make build
# or: GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build ./cmd/raven

---

Usage

Default — record + TUI

.\raven.exe

Starts the background recorder and opens the live timeline viewer. Close the TUI and recording stops.

Headless daemon

.\raven.exe record

Records in the background with no UI. Useful in a startup script or as a Windows service. Press Ctrl+C to stop.

View only

.\raven.exe view

Opens the TUI against the existing database without starting a new recording session.

Query CLI

.\raven.exe query --process chrome --last 24h
.\raven.exe query --type net_connect --last 1h
.\raven.exe query --since "2026-04-14 10:00" --until "2026-04-14 12:00"
.\raven.exe query --type cpu_spike

---

Query examples

What did chrome connect to in the last hour?

.\raven.exe query --process chrome --type net_connect --last 1h

TIME                 TYPE         PROCESS      PID    DETAIL
────────────────────────────────────────────────────────────────────
2026-04-15 14:23:01  net_connect  chrome.exe   4821   "chrome.exe" → 142.250.80.46:443
2026-04-15 14:22:47  net_connect  chrome.exe   4821   "chrome.exe" → 93.184.216.34:443

What processes ran today?

.\raven.exe query --type process_start --since "2026-04-15 00:00"

Any CPU spikes in the last 6 hours?

.\raven.exe query --type cpu_spike --last 6h

What happened in a specific window?

.\raven.exe query --since "2026-04-15 02:00" --until "2026-04-15 02:30"

Full history for a suspicious process:

.\raven.exe query --process svchost

---

TUI key bindings

Key	Action
e	Cycle event type filter
t	Cycle time range (5 min → 30 min → 1 h → 6 h → all)
l	Toggle live mode (auto-refresh)
/	Filter by process name
c	Clear all filters
r	Force refresh
↑ / ↓	Scroll event list
PgUp / PgDn	Scroll by page
q	Quit

---

Configuration

Raven writes a default config to ~\.raven\config.toml on first run. Edit any value and restart.

[recording]
# Poll interval in seconds.
poll_interval = 1.0

# CPU usage % threshold for cpu_spike events.
cpu_spike_threshold = 80.0

# Memory usage % threshold for mem_spike events.
mem_spike_threshold = 85.0

# Combined disk read+write rate (MB/s) for disk_spike events.
disk_spike_threshold_mb = 50.0

[database]
# Path to the SQLite database. ~ is expanded to your home directory.
path = "~/.raven/raven.db"

# Max events loaded into the TUI timeline at once.
timeline_limit = 300

[display]
# Event types hidden from the TUI by default.
# Example: hide_by_default = ["process_start", "process_stop"]
hide_by_default = []

The database itself is a plain SQLite file at the configured path. Query it directly with any SQLite client:

SELECT * FROM events WHERE event_type = 'net_connect' ORDER BY timestamp DESC LIMIT 20;

---

Roadmap

In progress

• Windows service installation (raven install / raven uninstall)
• Export to JSON / CSV (raven export --format json --last 24h)
• Alert rules with desktop notifications (configurable in config.toml)

Up for grabs

These are good first issues for contributors. Each one is scoped, well-defined, and won't require deep knowledge of the whole codebase.

• [good first issue] Add IPv6 TCP connection tracking (GetExtendedTcpTable with AF_INET6)
• [good first issue] Add a gpu_spike event type using NVAPI or DXGI
• [good first issue] Add a --json flag to raven query for machine-readable output
• [good first issue] Colour-code severity in the TUI (alert = red background, warning = yellow)
• [help wanted] Persistent filter presets saved to config.toml
• [help wanted] raven diff <db1> <db2> to compare two recording sessions

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup instructions, PR guidelines, and a walkthrough of how to add a new event type (the most common contribution). All PRs get reviewed within 48 hours.

---

License

MIT — see LICENSE.