Development¶

Build Matrix¶

Fastest Local Build Paths¶

Userspace¶

cargo check --workspace
cargo build
cargo build --release

On Windows, run the final binary from an elevated PowerShell. On Linux, run it as root or with the required eBPF capabilities.

Linux eBPF Build¶

If ebpf/rustinel-ebpf.o already exists, a normal root cargo build embeds it and no nightly eBPF rebuild is needed.

If you need to rebuild the eBPF object from source:

rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
cargo install bpf-linker

cd ebpf
cargo +nightly build --release --bin rustinel-ebpf
cp target/bpfel-unknown-none/release/rustinel-ebpf rustinel-ebpf.o
cd ..

build.rs watches ebpf/src, ebpf/Cargo.toml, and ebpf/rustinel-ebpf.o. On Linux builds it embeds either the prebuilt object or a freshly compiled one.

Recommended Dev Runs¶

Windows¶

cargo run -- run --console

Linux¶

sudo cargo run -- run

Linux With eBPF Override¶

Useful when iterating on ebpf/ without rebuilding the full userspace binary:

sudo env RUSTINEL_EBPF_OBJECT=$PWD/ebpf/rustinel-ebpf.o ./target/release/rustinel run

Testing¶

Unit and Integration Tests¶

cargo test
cargo test --test integration

The placeholder integration test currently documents the Windows administrator requirement for ETW-backed testing.

Code Quality¶

cargo fmt
cargo clippy

Project Structure¶

src/
├── main.rs             # CLI entry point and platform bootstrapping
├── config.rs           # Config loading and defaults
├── alerts.rs           # ECS NDJSON alert sink
├── engine/             # Sigma rule parsing, classification, and evaluation
├── ioc/                # Atomic IOC loading and matching
├── models/             # Event, alert, and ECS data models
├── normalizer/         # Shared event normalization and enrichment
├── reload/             # Hot reload poller and worker
├── response/           # Optional process termination logic
├── scanner/            # YARA compilation and scanning
├── sensor/
│   ├── windows/        # ETW sensor implementation
│   └── linux/          # eBPF userspace loader and event decoding
├── state/              # Process, DNS, SID, and network aggregation state
└── utils/              # Platform-specific helpers

ebpf/
└── src/                # Linux eBPF programs and event ABI definitions

Logging Guidance¶

Use the existing logging contract when adding runtime logs:

• trace: high-volume internals
• debug: troubleshooting detail
• info: lifecycle and positive detections
• warn and error: degraded behavior or failures

If a line can fire on most normal events, it does not belong at debug.