corvo documentation

corvo is an auditd plugin. It reads Linux audit's raw records from stdin, regroups the fragments into whole events, resolves ids into names, and POSTs them as JSON to an HTTP endpoint. A durable on-disk queue sits between capture and delivery, so an endpoint outage costs you nothing.

Each page here has one job: get you running, get one specific task done, hand you the exact fact you need, or explain why a decision was made. A page trying to do more than one of those stops being useful for any of them.

practical steps theory learning

learning by doing

Tutorials

Start here if you have never run corvo.

Watch your first events: Build corvo, load a temporary rule, and watch a command you typed print to the terminal. No endpoint, no queue, ten minutes.

why it is built this way

Explanation

The reasoning behind the decisions, and what each one costs.

Why a plugin instead of netlink: The kernel delivers audit events to one process only, and that fact shapes the whole design.
How an event survives: Five places a fragment could vanish between the kernel and the endpoint, and the barrier at each one.
auid, uid, and the chain of accountability: auid and uid answer different questions, and only one of them survives sudo.
What corvo costs: What running corvo actually costs, measured rather than estimated.

working

recipes for a goal you have

How-to guides

Each one assumes you already know corvo and just need the steps.

Install from a package: The RPM and the .deb, built from one spec with no rpmbuild or dpkg-buildpackage on the build machine.
Install from source: For when you cannot install a package, or want corvo outside /usr/bin. Go 1.22 and nothing else.
Point corvo at your endpoint: The three config layers, and the keys that decide whether an outage loses events or just waits.
Pick which events ship: Filter the flood auditd hands you down to the commands you actually care about.
Rotate a token with no downtime: Swap the bearer token with a SIGHUP: no stopped collection, no restarted auditd.
Resolve names for SSSD, LDAP, and AD users: Give the static binary a way to resolve SSSD, LDAP, and AD users it cannot see in /etc/passwd.
Recover rejected batches: What happens to a batch the endpoint will never accept, and how to get it back.
Backfill after a gap: Replay audit.log and its rotated copies for a machine that was running without corvo.
Diagnose an SELinux denial: Why corvo check passes by hand and still gets permission denied under auditd.
Turn on metrics: Off by default. What flipping it on costs and exposes.

the facts, for looking up

Reference

Every command, config key, environment variable, and metric.

Commands: Every subcommand and what it does.
Configuration keys: Every key in corvo.yaml, and what reloads on SIGHUP.
Environment variables: Every CORVO_* variable, and the config key it maps to.
Metrics: Every metric name, and what /healthz does and does not check.
Audit rules and the plugin file: The plugin file auditd reads, and the rules that decide what reaches it.
The event JSON: How the event JSON maps to what auditd actually reports.

Where this documentation ends

corvo is one half of a pair. What arrives on the wire, and what every status code means for the batch in flight, is the API contract both corvo and ninho implement.

The documents on this site are generated from docs/ in git.rda.run/corvo/corvo, which stays the source of truth.

target platforms
The target is audit 3.x. It ships on RHEL 9 and Debian 12, and on their later releases and rebuilds, with the plugin at /etc/audit/plugins.d/ on all of them. corvo needs Go 1.22 or later to build.

auditd → https · nothing gets lost corvo (Portuguese for raven) is the agent, ninho (nest) is the server. Both speak the same versioned contract.

docs how it works corvo (agent) ninho (server)

ninho docs tutorials how-to guides reference explanation

corvo docs tutorials how-to guides reference explanation

reference API contract install metrics and queue

code git.rda.run/corvo/corvo git.rda.run/corvo/ninho MIT license