ninho documentation

One Go binary with the web UI embedded inside it, and a PostgreSQL behind it. Nothing else has to be installed on the server: a single static file to copy onto the machine, and the trail of the whole fleet in one place.

Every page here answers one kind of question: getting something running, getting one specific thing done, the exact fact you came for, or why it works this way. Keeping those apart is what makes each page short enough to actually read.

practical steps theory learning

learning by doing

Tutorials

Start here if you have never run ninho.

Getting started: From an empty machine to your first audit event on screen, in about ten minutes.

why it is built this way

Explanation

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

Architecture: One Go binary and a PostgreSQL, and why nothing else is installed.
The contract and the status codes: Why the status code decides whether the audit data survives.
The authentication model: Two independent mechanisms: a bearer token for ingest, a directory for reading.
Reading the trail: Silence is the failure that hides, and other things the screens assume you know.

working

recipes for a goal you have

How-to guides

Each one assumes you already know what you want to accomplish.

Deploy to production: The binary, the database, and the three variables that decide whether the deploy is sound.
Configure LDAP sign-in: Restrict reading to your directory, and optionally to one group.
Split the database roles: Separate who writes from who reads, so a leaked ingest token cannot erase the trail.
Query the API from a script: Read the trail from cron, a notebook or an incident response, with no browser.
Build and release: One static binary with the UI inside it, and the container image.
Troubleshooting: Diagnosis by symptom, starting from the warnings in the first lines of the startup log.

the facts, for looking up

Reference

Every environment variable, route, status code and column.

Configuration: Every environment variable, plus the timeouts and limits that are not configurable.
HTTP API: Every route, parameter, and status code, on both surfaces.
Database: Schema, partitions, roles, and migrations.
Make targets: What each target builds, runs, or checks.

Where this documentation ends

ninho is one half of a pair. What the agent collects, and how it filters and retries, is documented in corvo, whose API contract is what both sides implement. A question about what arrives here has its answer in that contract.

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

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