How novasky0x1/fibratus works
1. What this repository is
Fibratus is a Windows-only Go security agent for adversary behavior detection, prevention, and hunting. Its core job is to ingest low-level system activity, enrich it, evaluate it against rules and YARA, then emit alerts/events to multiple sinks or persist them for later analysis.
2. Top-level runtime shape
The main executable lives under cmd/fibratus and is wrapped in a CLI with subcommands for capture, replay, rules management, listing, stats, service control, and version info. There is also a separate cmd/systray binary for tray-based interaction/notification.
3. Event collection pipeline
The ingestion boundary starts in internal/etw and pkg/sys/etw, which work with Windows ETW and related kernel telemetry. Raw trace data is converted into internal event objects, then passed through processor chains that specialize by event family such as process, file, registry, network, handle, memory, and module activity.
4. Enrichment and normalization layer
After collection, events are enriched with process state, handles, filesystem metadata, network address details, PE information, symbolization, and other Windows-specific context. That enrichment happens across packages like pkg/ps, pkg/handle, pkg/fs, pkg/network, pkg/pe, pkg/symbolize, pkg/callstack, and pkg/event, which together turn raw telemetry into analysis-ready events.
5. Detection engine
The main detection boundary is pkg/rules. It compiles YAML rules into executable logic, supports simple matching and sequence rules, and evaluates incoming events against filter expressions. The engine is tightly coupled to the event model and also supports rule actions such as alerting, process kill, and isolation-oriented responses where available.
6. Filtering and query language
Rule conditions are expressed via a custom query language in pkg/filter/ql, with parsing, AST, functions, and Windows-aware field accessors. This layer is important architecturally because it is the shared predicate system used by rules, event selection, and other event-driven components.
7. YARA and memory scanning
Fibratus includes a memory-scanning subsystem under pkg/yara and related filter functions. The scanner augments behavior rules with content-based inspection of process memory, which is part of the “memory scanning” pillar described in the README.
8. Alerting and output fan-out
Detected signals are sent through the output/alerting layer. pkg/outputs provides pluggable sinks such as console, HTTP, Elasticsearch, Event Log, AMQP/RabbitMQ, and null. Separately, pkg/alertsender handles alert delivery channels like Event Log, mail, Slack, and systray notifications. This creates a clear split between generic event serialization/output and user-facing alert transport.
9. Capture, replay, and forensics
The pkg/cap package and CLI capture/replay commands form the forensics path. Events can be recorded into capture files, then replayed later for offline inspection or testing. This means the system has both a live telemetry pipeline and an offline analysis pipeline that share the same event model.
10. Filaments extension model
pkg/filament and the top-level filaments/ directory implement a Python extension model. Filaments let users write Python-based tooling that runs in the Fibratus context, bridging Go telemetry with the Python ecosystem. Architecturally, this is an extensibility boundary rather than part of the core detector.
11. Bootstrap, configuration, and validation
Startup wiring is handled in internal/bootstrap and pkg/config. Config files live under configs/, with schemas and validation support in the config package. This layer decides which sources, processors, rules, outputs, and scanners are activated, so it is the main composition root for the application.
12. Windows service and UX integration
The cmd/fibratus/app/service subtree contains Windows service lifecycle management, while cmd/systray provides desktop tray integration. These are deployment/runtime concerns around the core engine, not part of detection logic, but they matter for how the agent is installed, run, and controlled on Windows hosts.
13. Rules catalog and operational content
The rules/ directory is the shipped detection content library. It contains many YAML rules organized by MITRE-style categories, plus shared macros. The CLI can list, validate, and create rules, so the repository includes both the engine and the operational content it executes.
14. Build and distribution
The project is packaged as Windows MSI installers under build/msi, with GitHub Actions workflows for PR, master, and release automation. This indicates the main deployment artifact is a signed Windows installer for the agent and its companion binaries, rather than a server-side service.
15. How the pieces fit together
In the live path, Windows telemetry enters ETW-based collectors, is normalized/enriched, evaluated by rules and YARA, then emitted to outputs and alert senders. In the offline path, capture files can be replayed through the same analysis pipeline. Filaments extend the system externally, while service/CLI/systray layers control how the engine is run and observed.
Main entry points: root.go Root CLI · engine.go Rules Engine · event.go Events · bootstrap.go Bootstrap
Components 24
Runtime
CLI entrypoints, service control, and desktop interaction.
- fibratus · Main Windows CLI entrypoint with subcommands for capture, replay, rules, stats, and service control.
cmd/fibratus/main_windows.go - Root CLI · Top-level command routing and shared CLI behavior.
cmd/fibratus/app/root.go - Capture · Live event capture command.
cmd/fibratus/app/capture/capture_windows.go - Replay · Offline replay command for captured telemetry.
cmd/fibratus/app/replay/replay_windows.go - Rules CLI · Rule create, list, and validate commands.
cmd/fibratus/app/rules/rules.go - Service Ctrl · Install, remove, start, stop, and status operations for the agent service.
cmd/fibratus/app/service/control_service_windows.go - Systray · Desktop tray companion binary for notifications and interaction.
cmd/systray/main_windows.go
Telemetry Pipeline
Capture, normalization, enrichment, and event processing.
- ETW Ingest · Windows ETW and kernel trace ingestion boundary.
internal/etw/source.go - Processors · Specialized processor chain for process, file, registry, network, handle, memory, and module events.
internal/etw/processors/chain.go - Events · Core event types, batching, marshalling, sequencing, and formatting.
pkg/event/event.go - Enrichment · Process, handle, filesystem, network, PE, symbol, callstack, and Windows-specific context enrichment.
pkg/ps/snapshotter.go - Capture Store · Capture file reader and writer used by live recording and offline replay.
pkg/cap/reader.go
Detection
Rules, filtering, and memory scanning.
- Query Lang · Shared filter and rule expression language with parser, AST, functions, and field accessors.
pkg/filter/ql/parser.go - Rules Engine · Compiles YAML rules and evaluates events and sequences against filters.
pkg/rules/engine.go - Rule Actions · Alert, kill, and isolate actions executed by rules where supported.
pkg/rules/action/alert.go - YARA Scan · Process memory scanning and YARA-based content inspection.
pkg/yara/scanner.go
Delivery
Outputs and alert fan-out.
- Outputs · Pluggable serialization and sink layer for console, HTTP, Elasticsearch, Event Log, AMQP, and null.
pkg/outputs/outputs.go - Alert Sender · User-facing alert delivery channels such as event log, mail, Slack, and systray notifications.
pkg/alertsender/sender.go - Output Backends · Concrete output implementations such as console, HTTP, Elasticsearch, Event Log, AMQP, and null.
pkg/outputs/console/console.go
Extensions
Filaments and external automation.
- Filaments · Python extension bridge and CPython integration for external tooling.
pkg/filament/filament.go - Python Tools · Repository-shipped Python examples and utilities for filaments.
filaments/README.md
Support
Configuration, sys helpers, and packaging.
- Bootstrap · Wires config, sources, outputs, rules, and scanners into a runnable agent.
internal/bootstrap/bootstrap.go - Config · Loads, decodes, prints, and validates application configuration and schemas.
pkg/config/config_windows.go - Sys Helpers · Windows-specific system helpers for process, filesystem, device, trust, privilege, and ETW syscall support.
pkg/sys/process.go
Connections 26
- fibratus → Root CLI: dispatches · Main binary routes to shared CLI command tree.
- Root CLI → Capture: capture · CLI launches live capture mode.
- Root CLI → Replay: replay · CLI launches offline replay mode.
- Root CLI → Rules CLI: rules · CLI exposes rule management commands.
- Root CLI → Service Ctrl: service · CLI controls Windows service lifecycle.
- fibratus → Bootstrap: starts · Executable initializes the composition root.
- Bootstrap → Config: loads · Bootstrap reads and validates runtime configuration.
- Bootstrap → ETW Ingest: wires · Bootstrap activates telemetry sources.
- ETW Ingest → Processors: feeds · Raw ETW data is normalized by processor chains.
- Processors → Events: builds · Processors materialize internal events.
- Events → Enrichment: enriched by · Event objects are augmented with Windows context.
- Enrichment → Sys Helpers: queries · Enrichment relies on low-level Windows helpers.
- Events → Query Lang: filtered by · Shared predicate language selects and matches events.
- Query Lang → Rules Engine: powers · Rules use the same query language for conditions and sequences.
- Rules Engine → Rule Actions: triggers · Matched rules execute response actions.
- Rules Engine → YARA Scan: augments · Rules can incorporate YARA and memory-scanning signals.
- Rules Engine → Outputs: emits · Detection results are serialized to configured sinks.
- Rules Engine → Alert Sender: alerts · User-facing notifications are delivered through alert channels.
- Outputs → Output Backends: implements · Backend packages provide concrete output targets.
- Capture Store → Events: stores · Capture files persist and restore the same event shape.
- Capture → Capture Store: writes · Live capture records events to capture files.
- Replay → Capture Store: reads · Replay reads capture files back into the pipeline.
- Filaments → Events: consumes · Python extensions operate on Fibratus events.
- Filaments → Query Lang: shares filters · Filaments can reuse the shared predicate language.
- Python Tools → Filaments: contains · Repository-shipped Python tooling sits on the filament boundary.
- Systray → Alert Sender: notifies · Tray binary participates in alert delivery.