# novasky0x1/fibratus architecture

> Architecture diagram of the GitHub repository novasky0x1/fibratus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/novasky0x1/fibratus
- Repository: https://github.com/novasky0x1/fibratus

## Overview

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: [`cmd/fibratus/app/root.go`](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/root.go) (Root CLI), [`pkg/rules/engine.go`](https://github.com/novasky0x1/fibratus/blob/master/pkg/rules/engine.go) (Rules Engine), [`pkg/event/event.go`](https://github.com/novasky0x1/fibratus/blob/master/pkg/event/event.go) (Events), [`internal/bootstrap/bootstrap.go`](https://github.com/novasky0x1/fibratus/blob/master/internal/bootstrap/bootstrap.go) (Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_fibratus["fibratus<br/>CLI binary<br/>[main_windows.go]"]
  node_cmd_fibratus_root["Root CLI<br/>command wiring<br/>[root.go]"]
  node_cmd_fibratus_capture["Capture<br/>subcommand<br/>[capture_windows.go]"]
  node_cmd_fibratus_replay["Replay<br/>subcommand<br/>[replay_windows.go]"]
  node_cmd_fibratus_rules["Rules CLI<br/>subcommands<br/>[rules.go]"]
  node_cmd_fibratus_service["Service Ctrl<br/>Windows service"]
  node_cmd_systray["Systray<br/>tray binary<br/>[main_windows.go]"]
end

subgraph group_pipeline["Telemetry Pipeline"]
  node_etw_ingest[("ETW Ingest<br/>telemetry source<br/>[source.go]")]
  node_etw_processors["Processors<br/>event pipeline<br/>[chain.go]"]
  node_event_model["Events<br/>event model<br/>[event.go]"]
  node_enrichment["Enrichment<br/>context layer<br/>[snapshotter.go]"]
  node_cap[("Capture Store<br/>record/replay<br/>[reader.go]")]
end

subgraph group_detection["Detection"]
  node_filter_ql["Query Lang<br/>predicate language<br/>[parser.go]"]
  node_rules_engine["Rules Engine<br/>detection engine<br/>[engine.go]"]
  node_rules_actions["Rule Actions<br/>response actions<br/>[alert.go]"]
  node_yara_scan[("YARA Scan<br/>memory scanning<br/>[scanner.go]")]
end

subgraph group_delivery["Delivery"]
  node_outputs["Outputs<br/>event sinks<br/>[outputs.go]"]
  node_alertsender["Alert Sender<br/>alert transport<br/>[sender.go]"]
  node_outputs_pkg["Output Backends<br/>backend packages<br/>[console.go]"]
end

subgraph group_extension["Extensions"]
  node_filament["Filaments<br/>python extension<br/>[filament.go]"]
  node_filaments_dir["Python Tools<br/>filament scripts<br/>[README.md]"]
end

subgraph group_support["Support"]
  node_bootstrap["Bootstrap<br/>composition root<br/>[bootstrap.go]"]
  node_config["Config<br/>schema/validation<br/>[config_windows.go]"]
  node_sys_pkg["Sys Helpers<br/>windows helpers<br/>[process.go]"]
end

node_cmd_fibratus -->|"dispatches"| node_cmd_fibratus_root
node_cmd_fibratus_root -->|"capture"| node_cmd_fibratus_capture
node_cmd_fibratus_root -->|"replay"| node_cmd_fibratus_replay
node_cmd_fibratus_root -->|"rules"| node_cmd_fibratus_rules
node_cmd_fibratus_root -->|"service"| node_cmd_fibratus_service
node_cmd_fibratus -->|"starts"| node_bootstrap
node_bootstrap -->|"loads"| node_config
node_bootstrap -->|"wires"| node_etw_ingest
node_etw_ingest -->|"feeds"| node_etw_processors
node_etw_processors -->|"builds"| node_event_model
node_event_model -->|"enriched by"| node_enrichment
node_enrichment -->|"queries"| node_sys_pkg
node_event_model -->|"filtered by"| node_filter_ql
node_filter_ql -->|"powers"| node_rules_engine
node_rules_engine -->|"triggers"| node_rules_actions
node_rules_engine -->|"augments"| node_yara_scan
node_rules_engine -->|"emits"| node_outputs
node_rules_engine -->|"alerts"| node_alertsender
node_outputs -->|"implements"| node_outputs_pkg
node_cap -->|"stores"| node_event_model
node_cmd_fibratus_capture -->|"writes"| node_cap
node_cmd_fibratus_replay -->|"reads"| node_cap
node_filament -->|"consumes"| node_event_model
node_filament -->|"shares filters"| node_filter_ql
node_filaments_dir -->|"contains"| node_filament
node_cmd_systray -->|"notifies"| node_alertsender

click node_cmd_fibratus "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/main_windows.go"
click node_cmd_fibratus_root "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/root.go"
click node_cmd_fibratus_capture "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/capture/capture_windows.go"
click node_cmd_fibratus_replay "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/replay/replay_windows.go"
click node_cmd_fibratus_rules "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/rules/rules.go"
click node_cmd_fibratus_service "https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/service/control_service_windows.go"
click node_cmd_systray "https://github.com/novasky0x1/fibratus/blob/master/cmd/systray/main_windows.go"
click node_bootstrap "https://github.com/novasky0x1/fibratus/blob/master/internal/bootstrap/bootstrap.go"
click node_config "https://github.com/novasky0x1/fibratus/blob/master/pkg/config/config_windows.go"
click node_etw_ingest "https://github.com/novasky0x1/fibratus/blob/master/internal/etw/source.go"
click node_etw_processors "https://github.com/novasky0x1/fibratus/blob/master/internal/etw/processors/chain.go"
click node_event_model "https://github.com/novasky0x1/fibratus/blob/master/pkg/event/event.go"
click node_enrichment "https://github.com/novasky0x1/fibratus/blob/master/pkg/ps/snapshotter.go"
click node_filter_ql "https://github.com/novasky0x1/fibratus/blob/master/pkg/filter/ql/parser.go"
click node_rules_engine "https://github.com/novasky0x1/fibratus/blob/master/pkg/rules/engine.go"
click node_rules_actions "https://github.com/novasky0x1/fibratus/blob/master/pkg/rules/action/alert.go"
click node_yara_scan "https://github.com/novasky0x1/fibratus/blob/master/pkg/yara/scanner.go"
click node_outputs "https://github.com/novasky0x1/fibratus/blob/master/pkg/outputs/outputs.go"
click node_alertsender "https://github.com/novasky0x1/fibratus/blob/master/pkg/alertsender/sender.go"
click node_cap "https://github.com/novasky0x1/fibratus/blob/master/pkg/cap/reader.go"
click node_filament "https://github.com/novasky0x1/fibratus/blob/master/pkg/filament/filament.go"
click node_filaments_dir "https://github.com/novasky0x1/fibratus/blob/master/filaments/README.md"
click node_sys_pkg "https://github.com/novasky0x1/fibratus/blob/master/pkg/sys/process.go"
click node_outputs_pkg "https://github.com/novasky0x1/fibratus/blob/master/pkg/outputs/console/console.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_fibratus,node_cmd_fibratus_root,node_cmd_fibratus_capture,node_cmd_fibratus_replay,node_cmd_fibratus_rules,node_cmd_fibratus_service,node_cmd_systray toneBlue
class node_etw_ingest,node_etw_processors,node_event_model,node_enrichment,node_cap toneAmber
class node_filter_ql,node_rules_engine,node_rules_actions,node_yara_scan toneMint
class node_outputs,node_alertsender,node_outputs_pkg toneRose
class node_filament,node_filaments_dir toneIndigo
class node_bootstrap,node_config,node_sys_pkg toneTeal
```

## Components

### Runtime

CLI entrypoints, service control, and desktop interaction.

- [fibratus](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/main_windows.go): CLI binary · Main Windows CLI entrypoint with subcommands for capture, replay, rules, stats, and service control. · `cmd/fibratus/main_windows.go`
- [Root CLI](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/root.go): command wiring · Top-level command routing and shared CLI behavior. · `cmd/fibratus/app/root.go`
- [Capture](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/capture/capture_windows.go): subcommand · Live event capture command. · `cmd/fibratus/app/capture/capture_windows.go`
- [Replay](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/replay/replay_windows.go): subcommand · Offline replay command for captured telemetry. · `cmd/fibratus/app/replay/replay_windows.go`
- [Rules CLI](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/rules/rules.go): subcommands · Rule create, list, and validate commands. · `cmd/fibratus/app/rules/rules.go`
- [Service Ctrl](https://github.com/novasky0x1/fibratus/blob/master/cmd/fibratus/app/service/control_service_windows.go): Windows service · Install, remove, start, stop, and status operations for the agent service. · `cmd/fibratus/app/service/control_service_windows.go`
- [Systray](https://github.com/novasky0x1/fibratus/blob/master/cmd/systray/main_windows.go): tray binary · Desktop tray companion binary for notifications and interaction. · `cmd/systray/main_windows.go`

### Telemetry Pipeline

Capture, normalization, enrichment, and event processing.

- [ETW Ingest](https://github.com/novasky0x1/fibratus/blob/master/internal/etw/source.go): telemetry source · Windows ETW and kernel trace ingestion boundary. · `internal/etw/source.go`
- [Processors](https://github.com/novasky0x1/fibratus/blob/master/internal/etw/processors/chain.go): event pipeline · Specialized processor chain for process, file, registry, network, handle, memory, and module events. · `internal/etw/processors/chain.go`
- [Events](https://github.com/novasky0x1/fibratus/blob/master/pkg/event/event.go): event model · Core event types, batching, marshalling, sequencing, and formatting. · `pkg/event/event.go`
- [Enrichment](https://github.com/novasky0x1/fibratus/blob/master/pkg/ps/snapshotter.go): context layer · Process, handle, filesystem, network, PE, symbol, callstack, and Windows-specific context enrichment. · `pkg/ps/snapshotter.go`
- [Capture Store](https://github.com/novasky0x1/fibratus/blob/master/pkg/cap/reader.go): record/replay · Capture file reader and writer used by live recording and offline replay. · `pkg/cap/reader.go`

### Detection

Rules, filtering, and memory scanning.

- [Query Lang](https://github.com/novasky0x1/fibratus/blob/master/pkg/filter/ql/parser.go): predicate language · Shared filter and rule expression language with parser, AST, functions, and field accessors. · `pkg/filter/ql/parser.go`
- [Rules Engine](https://github.com/novasky0x1/fibratus/blob/master/pkg/rules/engine.go): detection engine · Compiles YAML rules and evaluates events and sequences against filters. · `pkg/rules/engine.go`
- [Rule Actions](https://github.com/novasky0x1/fibratus/blob/master/pkg/rules/action/alert.go): response actions · Alert, kill, and isolate actions executed by rules where supported. · `pkg/rules/action/alert.go`
- [YARA Scan](https://github.com/novasky0x1/fibratus/blob/master/pkg/yara/scanner.go): memory scanning · Process memory scanning and YARA-based content inspection. · `pkg/yara/scanner.go`

### Delivery

Outputs and alert fan-out.

- [Outputs](https://github.com/novasky0x1/fibratus/blob/master/pkg/outputs/outputs.go): event sinks · Pluggable serialization and sink layer for console, HTTP, Elasticsearch, Event Log, AMQP, and null. · `pkg/outputs/outputs.go`
- [Alert Sender](https://github.com/novasky0x1/fibratus/blob/master/pkg/alertsender/sender.go): alert transport · User-facing alert delivery channels such as event log, mail, Slack, and systray notifications. · `pkg/alertsender/sender.go`
- [Output Backends](https://github.com/novasky0x1/fibratus/blob/master/pkg/outputs/console/console.go): backend packages · Concrete output implementations such as console, HTTP, Elasticsearch, Event Log, AMQP, and null. · `pkg/outputs/console/console.go`

### Extensions

Filaments and external automation.

- [Filaments](https://github.com/novasky0x1/fibratus/blob/master/pkg/filament/filament.go): python extension · Python extension bridge and CPython integration for external tooling. · `pkg/filament/filament.go`
- [Python Tools](https://github.com/novasky0x1/fibratus/blob/master/filaments/README.md): filament scripts · Repository-shipped Python examples and utilities for filaments. · `filaments/README.md`

### Support

Configuration, sys helpers, and packaging.

- [Bootstrap](https://github.com/novasky0x1/fibratus/blob/master/internal/bootstrap/bootstrap.go): composition root · Wires config, sources, outputs, rules, and scanners into a runnable agent. · `internal/bootstrap/bootstrap.go`
- [Config](https://github.com/novasky0x1/fibratus/blob/master/pkg/config/config_windows.go): schema/validation · Loads, decodes, prints, and validates application configuration and schemas. · `pkg/config/config_windows.go`
- [Sys Helpers](https://github.com/novasky0x1/fibratus/blob/master/pkg/sys/process.go): windows helpers · Windows-specific system helpers for process, filesystem, device, trust, privilege, and ETW syscall support. · `pkg/sys/process.go`

## Connections

- 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.
