Troubleshooting¶

Use this page when Rustinel starts but does not behave the way you expect, or when it fails before first telemetry.

Start Here¶

Before changing config or rules, check these first:

• Read the current operational log: logs/rustinel.log.<date>
• Run in the foreground with a higher log level:
• Windows: .\rustinel.exe run --console --log-level debug
• Linux: sudo ./rustinel run --log-level debug
• Trigger a known bundled demo rule:
• Windows: whoami /all
• Linux: whoami
• Confirm you are using the expected working directory and rule paths

Quick Symptom Guide¶

Startup Failures¶

Failed to load configuration¶

This usually means one of these:

• config.toml is not in the current working directory
• the TOML syntax is invalid
• an EDR__... environment override has the wrong shape or type
• a relative path assumes a different working directory than the one Rustinel is using

What to do:

• verify where you launched Rustinel from
• prefer absolute paths for production deployments
• temporarily move to the install directory and start again
• remove recent environment overrides and retry

See Configuration.

Windows says Administrator privileges are required¶

Windows ETW collection requires an elevated process.

What to do:

• start Rustinel from an elevated PowerShell
• if running as a service, confirm the service account has the required privileges

Typical symptom in logs:

This application requires Administrator privileges
Please run as Administrator to access ETW providers

Linux eBPF sensor failed to start¶

The most common causes are:

• kernel older than 5.8
• BTF is not available
• missing root or required eBPF capabilities
• tracefs or debugfs is not mounted
• invalid RUSTINEL_EBPF_OBJECT override path
• incompatible or stale eBPF object

What to do:

• confirm the host meets the Linux requirements from Getting Started
• if the error contains tracefs not found, mount the tracing filesystems and retry:

mount -t tracefs tracefs /sys/kernel/tracing
mount -t debugfs debugfs /sys/kernel/debug

• some minimal Linux environments, including some WSL 2 distros, may start without these filesystems mounted
• retry without RUSTINEL_EBPF_OBJECT if you were using an override
• if you are iterating on the eBPF program, rebuild the object and retry
• check the operational log for the exact Aya or loader error

Typical symptom in logs:

eBPF object load failed — ensure BTF is available and kernel is 5.8+

Linux source build fails on the first build¶

If ebpf/rustinel-ebpf.o is missing, the build falls back to compiling the eBPF crate. That first build needs:

• nightly Rust
• rust-src
• bpf-linker

See Getting Started and Development.

Agent Runs But No Alerts¶

The process starts cleanly, but alerts.json stays empty¶

Check these in order:

1. Trigger the bundled whoami Sigma rule first.
2. Confirm the operational log shows rules loaded successfully.
3. Confirm the relevant detector is enabled:
4. scanner.sigma_enabled
5. scanner.yara_enabled
6. ioc.enabled
7. Confirm the rule paths point to the directories and files you expect.
8. Confirm you are testing telemetry that exists on the current platform.

See Detection.

The detector is enabled, but my test never matches¶

The most common reasons are:

• the rule depends on fields that the platform does not emit
• the event family does not exist on that platform yet
• the event was skipped by an allowlist
• the event was suppressed by network aggregation

Examples:

• registry, image load, PowerShell, WMI, service, and task detections are Windows-only today
• Linux DNS events currently do not populate QueryName or QueryResults
• repeated network connections may be suppressed when aggregation is enabled

Linux DNS or IOC domain rules do not match¶

This is a current platform limitation, not just a rule problem.

Linux eBPF DNS events currently preserve record_type, Image, and ProcessId, but they do not currently populate:

• QueryName
• QueryResults
• QueryStatus

That means:

• Sigma DNS rules that depend on the queried domain name are much stronger on Windows
• IOC domain matching is much stronger on Windows
• IOC IP matching from DNS answers is effectively Windows-only right now

See Detection and Roadmap.

YARA did not scan the process I expected¶

Check these first:

• YARA only runs on process-start events
• the executable path may be under an allowlisted prefix
• YARA may be disabled
• the YARA rule file may be outside the configured top-level directory
• the queue may have been full and the job dropped

Typical symptom in logs:

YARA queue full; dropping scan job

IOC hash matching did not fire¶

Hash matching is more selective than inline IOC checks.

It only runs when:

• at least one hash IOC is loaded
• a process-start event queued the executable path
• the file path is not allowlisted
• the file size is below ioc.max_file_size_mb

Hot Reload Problems¶

My rule edits are ignored¶

Check these first:

• reload.enabled must be true
• the file must be under the configured detector path
• Sigma reloads recursively, but YARA only loads top-level files
• a failed reload keeps the previous detector set live

Typical reload failure messages:

Sigma reload failed; keeping previous engine
YARA reload failed; keeping previous scanner
Rejected IOC reload: indicator set is empty

I changed a file but nothing reloaded¶

Remember:

• reload polling is local file based
• the poll cadence is effectively max(reload.debounce_ms, 2000ms)
• empty rebuild results are rejected on purpose

If in doubt, make a tiny valid change to a known-good file and watch the operational log.

Active Response Problems¶

I see alerts, but no process is killed¶

Active response only executes when all of the following are true:

• response.enabled = true
• response.prevention_enabled = true
• alert severity is at or above response.min_severity
• the target has a valid PID
• the target image is known
• the PID is not protected
• the target is not Rustinel itself
• the image or path is not allowlisted

If prevention_enabled = false, the response engine logs what it would have done instead of killing the process.

See Active Response.

Active response says the target was skipped¶

That is usually expected and safety-related.

The response engine skips:

• protected low system PIDs
• Rustinel itself
• allowlisted images and paths
• alerts without a usable PID or image path

Dropped Events And Full Queues¶

I see “dropping event” or “queue full” in logs¶

These messages mean the agent is under backpressure somewhere in the pipeline.

Common log lines include:

Sensor event channel full; dropping ETW event
eBPF sensor: event channel full, dropping event
YARA queue full; dropping scan job
IOC hash queue full; dropping job
Active response queue full, dropping task

What to do:

• reduce event volume during testing
• narrow overly broad rules
• widen trusted-path exclusions where appropriate
• avoid scanning large trusted software trees unnecessarily
• watch system load while reproducing the issue

If the problem is persistent, capture the relevant log excerpt before tuning.

Logging And Output Problems¶

I have no operational logs¶

Check these first:

• logging.directory points to a writable location
• the current working directory is what you expect
• the service or supervisor account can write there

Rustinel may fall back to a temp directory if file logging cannot be initialized. If that also fails, it falls back to a sink writer and you may lose file-based operational logs.

Alerts are missing match details¶

That is controlled by alerts.match_debug.

Use:

• off for no match metadata
• summary for compact details
• full for more verbose match information

See Detection and Output Format.

I see operational logs but alert writes fail¶

Check:

• alerts.directory is writable
• the filesystem is not full
• the process has permission to create or rotate files there

Typical symptom in logs:

Failed to write ECS alert

Windows ETW Restart Behavior¶

Why did the Windows agent exit after the ETW sensor failed?¶

That is intentional.

If the ETW sensor thread dies unexpectedly, Rustinel forces the process to exit so the Windows Service Manager or another supervisor can restart it. This avoids leaving a process that appears healthy but is no longer collecting telemetry.

Typical symptom in logs:

CRITICAL: ETW sensor thread died unexpectedly
Forcing process exit to trigger restart

Before Opening An Issue¶

Collect these first:

• platform and version
• Rustinel version or commit
• exact start command
• relevant config snippets
• relevant operational log excerpt
• whether the bundled whoami demo rule works
• on Linux: kernel version, BTF availability, and whether an eBPF override object was used

If the problem is rule-related, include the minimal rule and the event type you expected it to match.