Name: Inner Warden
Author: Inner Warden

The bar, said plainly

Inner Warden runs in production on real machines. A bug in the sensor is a CVE-shaped problem. So the bar is real, but it is not mysterious. There are four checks you have to pass, every commit message is in English, and the style rules fit on a postcard. If you have shipped Rust before, you already know most of this.

The first PR is the hardest. Once you have landed one, the rest is muscle memory.

The four make targets you will run a lot

Run these from the repo root before you push. CI runs them too, but local turnaround is faster.

make test         # cargo test --workspace, ~2 min
make check        # cargo clippy --workspace -- -D warnings + fmt
make replay-qa    # rerun the recorded sensor traces, diff findings
make heap-budget  # agent must stay under the heap budget gate

make test is the obvious one. It is also the slowest, so save it for when you think you are done. make check is fast and catches almost every embarrassing thing. make replay-qa is non-negotiable for any change that touches the sensor or correlation rules. make heap-budget is the gate that keeps the agent from quietly growing.

The CI gates a PR has to clear

CI runs on every push to a PR branch. The required checks:

Clippy with --workspace -- -D warnings. Every warning is a hard fail. We do not ship a clippy allow without a good reason and an inline comment.

Codecov patch coverage at 70%. The lines you add must be 70% covered. The project coverage line moves slowly; the patch coverage line is what stops a PR.

Replay-qa green. The recorded traces under qa/replay/ must produce the same findings they used to. If your change moved findings around on purpose, regenerate the goldens in the same commit and explain why in the PR description.

Heap budget. The agent's anonymous heap RSS is bounded. If your change pushes it over the budget, the gate fails and you have to either trim the regression or argue for a new budget in the PR.

Style rules that come up in review

Commits in English. The rest of the codebase is mostly English. Mixing languages in commit messages makes git log hard to scan.

Use tracing::warn! and friends, with structured fields. Not println!, not eprintln!, not log::warn!. The reason is structured fields, not the macro itself.

// Good
tracing::warn!(pid = ev.pid, detector = self.id(), "skipped");

// Not good
tracing::warn!("skipped pid {} detector {}", ev.pid, self.id());

let _ = only with a comment. If you are deliberately throwing away a Result, say why on the same line. Otherwise it reads as an oversight.

No em dashes. We use a hyphen with spaces, a comma, or a rephrase. This is a real codebase rule and reviewers will flag it.

IO errors in sinks should warn! and continue, not propagate with ?. A failing remote sink should never take down the agent.

Synchronous IO inside a tokio task goes through spawn_blocking. Including SQLite. Especially SQLite.

A reasonable first PR

Three flavours land easily:

A new detector. Self-contained, easy to test, easy to review. There is a separate post that walks through writing one in 50 lines.

A new sink. The sink trait is small. A Discord webhook sink, a syslog sink, an S3 archival sink, all live next to each other under crates/agent/src/sinks/.

An integration recipe. A markdown file that documents how to wire Inner Warden into something else (Wazuh, OSSEC, a specific cloud provider). These help users a lot and never get a hard review.

The PR template

Three sections: what changed, why, how it was tested. Be specific about the testing. "Ran make test" is fine for a comment fix; for a detector you want to call out the replay-qa traces you added or updated.

Link the spec or issue if there is one. If there is not, a two-line description of the user-visible change is enough.

What gets pushed back

Tests that pass for the wrong reason. A clippy allow with no comment. A new dependency added without a one-liner on why we need it. A change to the JSONL contract without a version bump and a migration note. None of these are dealbreakers; they are just the things review will ask you to revisit.

Contributing Your First PR to Inner Warden