| Target | Needs |
|---|---|
| All platforms | Rust 1.98 or later (the repository pins Rust 1.98.1) |
| Windows | Visual Studio Build Tools |
| macOS | Xcode Command Line Tools |
| Linux eBPF object | nightly Rust, rust-src, and bpf-linker |
cargo install cargo-deny --version 0.20.2 --locked
cargo install cargo-audit --version 0.23.0 --locked
python3 scripts/audit-lockfiles.py
cargo deny --locked check
(cd ebpf && cargo deny --locked check)The Supply Chain workflow runs these checks in CI and daily at 06:23 UTC, and supports manual runs.
The audit scans both complete lockfiles, including disabled optional dependencies, and fails on vulnerabilities, unsoundness, unmaintained crates, and yanked releases.
Each workspace's deny.toml supplies its advisory exceptions and their reasons for both tools.
The deny checks also enforce licenses, sources, and dependency bans, with transitive unsoundness and yanked releases treated as errors.
Make the CI Supply Chain / Dependency checks check required in branch protection to block merges when dependency checks fail.
cargo build
cargo build --releaseRun the agent with the privileges it needs:
=== "Linux and macOS"
```bash
sudo cargo run -- run
```
=== "Windows"
From an elevated PowerShell:
```powershell
cargo run -- run
```
On macOS, live Endpoint Security events also need a signed bundle, see macOS. Building and testing do not.
The release profile sets panic = "abort"; development builds and tests unwind, including cargo test --release.
See Sensor callback failures for the operator-visible behavior and Callback panic audit for the code invariants.
The kernel and userspace event types are declared once, in the ebpf-common crate that both ebpf/ and the agent depend on.
Change a repr(C) event or layout there, and both sides rebuild against it.
build.rs picks the embedded object in this order:
RUSTINEL_EBPF_STUB=1embeds a stub with no programs. The sensor refuses to start with it, and the build prints a warning.RUSTINEL_EBPF_PREBUILT=1embedsebpf/rustinel-ebpf.owhatever its age, and fails if the file is missing. Setting both variables is an error.- Otherwise
ebpf/rustinel-ebpf.ois embedded only when it is not older thanebpf/,ebpf-common/, and their manifests. An older copy is ignored with a build warning, and the object is compiled from source with nightly.
The file is ignored by Git, and a stale copy is never embedded unnoticed.
The agent logs the chosen source (prebuilt, source, or stub) when it loads the embedded object.
Changing either variable re-runs the build script.
To compile the object yourself, for example with a pinned nightly:
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.oTo try a new object without rebuilding the agent:
sudo env RUSTINEL_EBPF_OBJECT=$PWD/ebpf/rustinel-ebpf.o ./target/release/rustinel runFor cargo check, clippy, or unit tests without the nightly toolchain, set RUSTINEL_EBPF_STUB=1.
The resulting binary cannot collect telemetry.
Compilation alone does not run the kernel verifier. After building the eBPF object and release agent as above, run the same load, attachment, event-family, and demo-alert checks used by CI:
cargo build --locked --release
sudo python3 tests/ebpf_load_smoke.py \
--binary target/release/rustinel \
--ebpf-object ebpf/rustinel-ebpf.o \
--rules-dir rules/sigma \
--artifacts-dir target/ebpf-load-smoke
sudo python3 tests/native_capture_contract.py \
--binary "$PWD/target/release/rustinel"The smoke test requires root, curl, network access, and a Linux 5.8 or newer kernel with BTF.
It verifies that the supplied object is embedded in the binary before starting the agent.
CI runs the commands on both the current GitHub runner kernel and Linux 5.10; use a VM when reproducing the 5.10 leg locally.
Endpoint Security needs a bundle signed with the com.apple.developer.endpoint-security.client entitlement.
Build one with your Developer ID and an Endpoint Security provisioning profile:
cargo build --release
scripts/macos/package-app.sh \
--binary target/release/rustinel \
--output target/release/Rustinel.app \
--profile "$HOME/Downloads/rustinel.provisionprofile" \
--identity "Developer ID Application: Example (TEAMID)"Grant the bundle Full Disk Access, then run sudo ./target/release/Rustinel.app/Contents/MacOS/rustinel run.
scripts/macos/test-bpf-lifecycle.sh builds and signs the bundle, then checks interface reconcile, restart, and removal with a live test and a feth interface; it needs root and a Terminal with Full Disk Access.
On a SIP-disabled test Mac, --adhoc replaces --profile and --identity.
Never use it on a normal Mac.
Release signing in CI reads MACOS_SIGN_IDENTITY, MACOS_CERT_P12_BASE64, MACOS_CERT_PASSWORD, MACOS_PROVISIONING_PROFILE_BASE64, MACOS_NOTARY_APPLE_ID, MACOS_NOTARY_TEAM_ID, and MACOS_NOTARY_PASSWORD.
Release checksum files and the rules catalog are signed with the Minisign key configured as RELEASE_MINISIGN_KEY in both release repositories.
Its public half is release-minisign.pub, embedded in the binary, and rustinel update also pins the Apple Developer Team ID of the macOS app.
- Rotating the Minisign key: update the embedded public key and both repository secrets together before publishing another release. Installed binaries trust only the old key, so first publish a transition release that trusts both keys, or require a manual install after rotation.
- Changing the Apple signing team: update the pinned Team ID in the updater and the macOS release validation in the same change, then publish a release signed by the existing Minisign key so installed clients can authenticate it.
cargo test --locked
cargo fmt --all
cargo clippy --locked --all-targets -- -D clippy::allThe normal suite uses synthetic events and needs no privileges.
Ignored by default. Run them on a disposable machine:
| Test | Command | Needs |
|---|---|---|
| Memory scanning | cargo build --locked --example memory_target && cargo test --locked --test yara_memory -- --include-ignored |
Administrator, or root with process-memory access |
| Active response | cargo test --locked --test active_response -- --include-ignored |
Same |
| Windows process user | cargo test --locked --test windows_process_user -- --ignored --nocapture |
Administrator |
| Windows service recovery | cargo test --locked --lib platform::windows::tests::configures_recovery_on_created_and_existing_services -- --ignored |
Administrator, creates and deletes a temporary SCM service |
| Linux process identity | cargo test --test linux_task_identity live_task_identity_matches_proc -- --ignored |
root, RUSTINEL_EBPF_OBJECT set |
| Linux eBPF memory scanning | cargo build --example memory_target && cargo test --test linux_task_identity live_ebpf_process_reaches_yara_memory_scan -- --ignored |
root, process-memory access, RUSTINEL_EBPF_OBJECT set |
| Linux socket fields | cargo test --test linux_socket_tuple live_tuple_and_connection_churn -- --ignored |
root, RUSTINEL_EBPF_OBJECT set, a non-loopback interface |
| macOS collector loss | sudo python3 scripts/macos/test-collector-loss.py <agent pid> <telemetry.json> |
A signed agent running as root. Suspends it for 10 seconds |
Linux kernel-dependent changes should be checked on several kernels, for example 5.10, 5.15, 6.1, and 6.8. Tests that hide BTF must run in a VM or a private mount namespace, never on a shared host.
The Windows ETW decoders read a record through the EtwHeader and EtwProperties traits in src/sensor/windows/etw/props.rs.
The sensor implements them for ferrisetw, and the tests implement them for records saved as JSON under tests/fixtures/etw.
src/sensor/windows/etw/fixture_tests.rs feeds each fixture through the same routing and decode_* functions the live sensor uses, so cargo test on Windows covers them without a session.
The fixtures are plain JSON, but the tests that read them only compile on Windows.
Each fixture file has a provenance block (Windows build, date, host, and what the scenario did) and a list of records in arrival order.
Keep related records together and in order: the Kernel-File and Kernel-Registry decoders join pathless events to earlier naming events.
To record a new one on a disposable Windows machine, as Administrator:
- Set
RUSTINEL_ETW_RECORDto an output file and startrustinel capture. The recorder saves the header and every property the decoders read, one JSON object per line. It writes nothing until a file named<output>.onexists, so create that file just before the activity and delete it right after.RUSTINEL_ETW_RECORD_MAX(default 5000) caps the record count. - Run the activity, then stop
rustinel captureand remove any leftoverrustinel-etw-*session withlogman stop <name> -ets. - Pick the records the scenario needs.
A file or registry write names its target only by kernel object, so keep the earlier
CreateKey/OpenKeyor file-create record for the same object. - Wrap them as
{"provenance": {...}, "records": [...]}, save the file, and add a test infixture_tests.rsthat asserts the canonical fields.
Recordings contain command lines, paths, and user names from the machine. Read them before committing, and delete or replace anything that identifies a real person.
The drain_process_ring, drain_network_ring, drain_file_ring, and drain_dns_ring functions in src/sensor/linux/ebpf.rs read records through the RingSource trait.
The sensor implements it for the aya ring buffer, and the tests implement it for records saved as hex under tests/fixtures/linux_ring.
src/sensor/linux/ebpf/ring_fixture_tests.rs feeds each fixture through the real drain functions, so cargo test on Linux covers decoding, the telemetry counters, and the file directory index without root or a loaded program.
Each fixture file has a provenance block (kernel, date, host, and what the scenario did) and a list of {"ring", "hex"} records in arrival order.
Keep a file's records in order: the file drain joins relative paths to earlier directory opens.
The checked-in fixtures were recorded on lab-ubuntu (kernel 7.0.0-38) and cut by hand where a provenance note says so.
To record a new one on a disposable Linux machine, as root:
- Set
RUSTINEL_EBPF_RECORDto an output file and start the agent. Every record any of the four drains reads is appended as one{"ring":"process","hex":"..."}line, before it is decoded, so short reads are kept. - Run the activity, then stop the agent.
- Pick the lines the scenario needs and wrap them as
{"provenance": {...}, "records": [...]}. - Save the file and add a test in
ring_fixture_tests.rsthat asserts the canonical fields and the counters.
Recordings contain command lines, paths, and user names from the machine.
Read them before committing, and delete or replace anything that identifies a real person.
Fixed-size path buffers also carry stale bytes after the terminating NUL, which can be a path the kernel handled earlier, so inspect the whole record (strings on the decoded hex) and zero what does not belong.
The macOS decoders read a message through the EsMessage trait in src/sensor/macos/esf/view.rs.
The sensor implements it for the live Endpoint Security Message, and the tests implement it for EsRecord, loaded from JSON under tests/fixtures/esf.
src/sensor/macos/esf/fixture_tests.rs feeds each fixture through the same build_sensor_event the live handler calls, so cargo test on a Mac covers every build_*_event without a client, root, or the entitlement.
Each fixture file has a provenance block (macOS build, architecture, date, and what the scenario did) and a list of records in arrival order.
Keep related records together and in order: exec parent links resolve against earlier execs in the same file.
To record new ones on a Mac with a Developer ID profile and a terminal that has Full Disk Access:
scripts/macos/record-esf-fixtures.shThe script builds and signs the agent, starts it with RUSTINEL_ESF_RECORD set, runs the workloads under /private/tmp/rustinel-esf-fixture, and writes tests/fixtures/esf/process_lifecycle.json and file_lifecycle.json.
To record by hand, run a signed agent with RUSTINEL_ESF_RECORD=<file>.
It writes nothing until a file named <file>.on exists, so create that file just before the activity and delete it right after.
RUSTINEL_ESF_RECORD_MAX (default 5000) caps the record count.
Pick the records the scenario needs, wrap them as {"provenance": {...}, "records": [...]}, and add a test in fixture_tests.rs.
Recordings contain command lines, paths, and uids from the machine. Read them before committing, and delete or replace anything that identifies a real person.
CI loads every rule from the SigmaHQ commit pinned in compatibility/sigmahq-baseline.json and fails on parser errors or when the per-platform load counts drift from the baseline.
To run it locally, check out that commit and run:
RUSTINEL_EBPF_STUB=1 RUSTINEL_SIGMA_CORPUS_DIR=/path/to/sigma \
cargo test --locked --test sigma_corpus_compatibility -- --include-ignoredtests/fixtures/replay/ holds a Windows recording and the rules it must trigger.
tests/replay_fixture.rs replays it on every platform.
To regenerate it on a Windows lab machine:
rustinel capture --output windows-powershell.ndjson- Run
windows-powershell-fixture.ps1, then press Ctrl-C. - Check the manifest says
"status": "complete". - Copy both files into
tests/fixtures/replay/. Never edit a recording by hand: its checksum is verified. - Run
cargo test --test replay_fixture.
CI runs the rustinel-rules atomic suite against Linux and Windows builds: it performs safe actions and checks each produces its alert.
Release tags run it against every release artifact.
The Linux and Windows checks are required on pull requests; a missing alert or an engine startup failure blocks merging.
The JSON report contains failed trigger output, and CI uploads it with the engine output and logs even when the suite fails.
Signed macOS atomics run on pushes to main and for release artifacts.
Both CI and release read one reviewed commit from .github/atomic-rules-ref, taken from the rules repository's main branch.
To update it deliberately:
- Choose a reviewed
rustinel-rulescommit that is reachable frommain. - Set the full commit SHA in
.github/atomic-rules-ref. - Run a pull request with the complete Linux and Windows atomic suite, review its reports and logs, and merge only when both required checks pass.
The next signed macOS
mainrun validates the same pin; do not move the pin past a failing macOS run. - Before a release, confirm its artifact atomic matrix also passes with that exact SHA. Intel macOS remains an explicitly optional release leg.
The docs use Zensical:
pip install zensical
zensical serveParts of the reference are generated from code.
After changing CLI flags, config options, or FIELD_AVAILABILITY, run:
cargo run --bin generate-docsTests fail when a generated section is out of date. Writing rules are in CONTRIBUTING.md.
| Level | For |
|---|---|
trace |
High-volume internals |
debug |
Troubleshooting detail. Nothing that fires on most events |
info |
Lifecycle and detections |
warn, error |
Degraded behavior and failures |