corvo · tutorials

Watch your first events

on this page

1. Build the binary 2. Load a temporary audit rule 3. Run corvo in tail mode 4. Type some commands 5. See the whole event 6. Clean up Where to go next

By the end of this page you will have built corvo, made Linux audit record the commands you type, and watched those commands print to your terminal as corvo regroups them. You need a Linux machine you can run sudo on and Go 1.22 or later. Nothing here touches auditd's plugin setup or writes a queue, so it is safe to try on a machine you care about, and every step is undone at the end.

Set aside about ten minutes.

1. Build the binary

From the repository root:

make build

You now have a corvo binary in the current directory. Check it runs:

./corvo version

2. Load a temporary audit rule

corvo does not create audit events. The kernel does, when a rule tells it to. Add one rule that records every execve from your own login user:

# your audit login uid, the number that survives su and sudo
cat /proc/self/loginuid

# record execve for that uid (replace 1000 if yours differs)
sudo auditctl -a always,exit -F arch=b64 -S execve -F auid=1000 -k demo

This rule lives only in the running kernel. A reboot, or auditctl -D, removes it. It is not written to any file.

Confirm it is loaded:

sudo auditctl -l | grep demo

3. Run corvo in tail mode

tail reads audit events over the multicast socket and prints them. It coexists with auditd instead of replacing it, which is what makes it safe for a quick look. It is also lossy: under load the kernel drops events on this socket with no warning. That tradeoff is fine for a tutorial and wrong for real collection, which is why production uses plugin mode instead.

In one terminal:

sudo ./corvo tail

You will see a warning that events may be dropped. Leave it running.

4. Type some commands

In a second terminal, run a few things:

id
ls /etc
whoami

Back in the first terminal, each command shows up as a single line:

14:22:31.512  seq=48213    yourname     [id]
14:22:33.881  seq=48219    yourname     [ls /etc]
14:22:35.140  seq=48225    yourname     [whoami]

That single line is the point of corvo. The kernel delivered each of those commands as five separate records (SYSCALL, EXECVE, CWD, PATH, PROCTITLE), joined only by the sequence number. corvo put them back together before printing.

5. See the whole event

Stop corvo tail with Ctrl-C and run it again asking for JSON:

sudo ./corvo tail -json

Run id -u in the other terminal. Now you get the full event: the resolved user names, the process tree, the working directory, the arguments as a real list, the SELinux context, the file that was executed. This is the shape of what corvo would POST to an endpoint. The full field-by-field description is in the event JSON reference.

6. Clean up

Stop corvo tail. Remove the rule:

sudo auditctl -d always,exit -F arch=b64 -S execve -F auid=1000 -k demo

Or clear every rule you added by hand:

sudo auditctl -D

Nothing else was changed. There is no queue directory, no config file, no plugin registered.

Where to go next

You have seen capture and regrouping. The next step is delivery: installing corvo as a real auditd plugin that writes a durable queue and POSTs events to your endpoint.

Tutorials