Skip to content
akumaburnPublic

About

A free Linux live system intrusion detection system with auditing

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

LinAudit

A local host-monitoring and input-forensics stack for Linux, shipped as one static Go binary that runs on any popular systemd distro (built and tested on Manjaro/Arch, GNOME/Wayland, zsh and bash). It was born from a concrete question -- "why do commands I never typed sometimes appear in my terminal?" -- and grew into a small, self-contained system that records what happens at the input, shell, and process layers, encrypts the evidence at rest, and presents it in a password-protected local dashboard.

LinAudit Overview dashboard: the monitor-health rail (shell / input / audit), the encrypted-store badge, live keystroke/buffer/connection counts, global rx/tx throughput, and an offline GeoIP world map of current connections

Overview — monitor health (shell / input / audit), encrypted-store status, live throughput, and the offline GeoIP map of current connections.

Status: complete and in use -- input/shell/exec monitoring, encrypted storage, CLI, web dashboard, the network panel (listening processes by bandwidth, reverse DNS, offline GeoIP country + world map), and optional automated abuse-IP detection (AbuseIPDB) with forensic response.

Implemented as a single, statically-linked Go binary with no interpreter or shared-library dependency at runtime; the dashboard markup and world map are embedded via go:embed. The only non-Go runtime pieces are the shell hooks (bash / zsh / fish -- they must run inside the shell). The sole optional external tool is nvidia-smi (GPU VRAM).

Highlights

  • Three correlated planes -- prompt text (even unexecuted), per-keystroke source device, and auditd execve / uinput / USB -- so you can tell typed from pasted from injected after the fact.
  • Encrypted at rest -- a LUKS2 log store whose key is sealed to the TPM via systemd-creds; the writers refuse to start unless it is mounted.
  • Local web dashboard on 127.0.0.1:8799 -- scrypt login, per-load CSRF token, Host allowlist + Origin / Sec-Fetch checks; Overview / Network / Processes / Logs / Timeline.
  • Network panel -- per-process bandwidth read from the kernel over netlink (no ss / iproute2 dependency), reverse DNS, an offline GeoIP world-map choropleth, and offline ASN/owner classification (known corp / cloud / cdn / gov / telecom networks vs unknown) so you can see who each peer belongs to, not just where.
  • Abuse-IP detection (optional) -- matches live connections against a locally cached AbuseIPDB blacklist and, on a hit, automatically fingerprints the owning process (exe + hash, cmdline, parent chain), takes a short scoped packet capture of that one connection, persists a forensic record, and notifies -- alert + forensics only, it never blocks the peer or kills the process.
  • One static Go binary -- pure standard library, no interpreter or shared libraries, assets embedded via go:embed; builds for amd64 / arm64 / arm / 386.

Quick start

make build              # -> ./linaudit  (static, no runtime deps)
sudo sh install.sh      # detect user, install, init store, enable services, run doctor
linaudit doctor         # readiness check you can run on any distro

Then open http://127.0.0.1:8799/ -- the first visit sets the dashboard password.

Why it exists

Most "shell auditing" records only executed commands. The original symptom here was text that appeared in the prompt and was never executed, so conventional history/exec auditing was blind to it. LinAudit instead watches three planes and correlates them by timestamp, which lets you tell typed from pasted from injected after the fact.

The three planes

Plane Component What it captures
Prompt text (even unexecuted, zsh only) + executed commands (bash/zsh/fish) shell hooks (shell/linaudit.{zsh,bash,fish}) zsh: every line-editor change + every executed command; bash/fish: every executed command
Physical / virtual keystroke source linaudit-input service (inputmon/) each key event tagged with its source /dev/input device; flags new/virtual (uinput) devices
Login-attributed executions, /dev/uinput access, USB add/remove auditd rules + udev rule (system/) execve, uinput-injection signature, BadUSB enumeration

Correlation key: prompt text that grows one character at a time alongside KEY events from a real keyboard was typed; text that appears all at once with no preceding KEY was pasted or injected; keystrokes from a virtual device or a uinput open are a software injector. See docs/runbook.md.

The execve audit rules intentionally require an attributed login UID. Background services and rootful container runtimes normally use audit's unset login UID (4294967295), so excluding them prevents routine service/container churn from swamping the forensic signal. Commands launched from a terminal, including sudo commands, retain the interactive user's login UID and remain covered.

The unexecuted-prompt-text plane (per-keystroke buffer growth) requires zsh's line editor, so it is captured for zsh only. bash and fish capture executed commands; the same typed-vs-pasted-vs-injected call is still made for them by correlating each command against the shell-agnostic keystroke plane (a command that appears with no preceding KEY burst was pasted or injected).

Encryption at rest (LUKS2 + TPM)

All captured logs live in a LUKS2 container (storage/), mounted at /var/log/linaudit. The container key is sealed to the machine's TPM (systemd-creds, host+tpm2) and released automatically at boot -- the raw key is never written to disk in plaintext.

  • Protects against: a pulled/stolen disk, booting another OS, and backups / btrfs snapshots -- all see ciphertext only.
  • Does NOT protect against: a live root attacker on the running machine (the key is in the kernel keyring while mounted). Use full-disk encryption for that.
  • The writers hard-depend on the mount (Requires=linaudit-store.service), so if the store cannot be unlocked they refuse to start rather than write plaintext.

Dashboard

  • Web UI on http://127.0.0.1:8799/ (web/), bound to loopback only. First visit sets a password (scrypt-hashed); login issues an HttpOnly, SameSite=Strict session cookie. Per-load CSRF token, Host allowlist (anti DNS-rebind), and Origin/Sec-Fetch checks on top.
  • Layout: a collapsible sidebar (Overview / Network / Processes / Logs / Timeline) with a persistent status rail -- monitor health pills (click to toggle), encryption badge, live counts, and the global live/pause + interval control -- visible in every section.
  • Features: live/pause auto-refresh, global throughput sparklines + per-process trends, proportional bandwidth bars, global totals, an alert banner when a monitor is off / storage is plaintext / an abuse-IP hit landed in the last 24h (click through to the relevant view), filter/search, sortable tables (including by process and a descending-time "age" column), new-connection/-country highlighting, scroll + text-selection preservation across refreshes, keyboard shortcuts (1-5 sections, / filter, l LAN, w wired, p pause, r refresh), per-tab log views including a dedicated abuse alerts tab (peer, score, full process fingerprint, pcap path) newest first, correlated timeline, offline world-map choropleth, enable/disable each layer, logout.
  • Noise filters (default ON, toggle-able): the dashboard hides routine local/LAN connections and wired-bus (USB/PS-2) keystrokes by default, so the network and input views surface only remote peers and non-wired (wireless / virtual / injected) input -- the forensically interesting traffic. Each filter has a one-click toggle (and an l / w shortcut) and shows how many rows are hidden.
  • Processes view: per-process CPU%, resident memory, and NVIDIA GPU VRAM (via nvidia-smi, capturing both graphics and compute procs), plus a system CPU / RAM / GPU summary; sortable by any column and filterable.
  • CLI panel: linaudit (status | enable | disable | logs | report | live | open | doctor); web / input / store up|down|init|reserve are the service entry points of the same binary. linaudit doctor reports, on any distro, exactly which planes will work here.

Network panel

The dashboard's network section answers "what is my machine talking to":

  • Processes by bandwidth -- every listening or actively-connected process, sorted by current rx+tx (delta of the kernel's per-socket tcp_info byte counters read over netlink, sampled every 2s), with its listening ports.
  • Remote connections -- each established peer with reverse-DNS hostname, GeoIP country flag, and its owning network. LAN/private/CGNAT/multicast peers are classified locally and excluded from rDNS, GeoIP, and the map; they are also hidden from the connection list, country bars, and counts by default (a "show LAN" toggle and the l key bring them back for a full local + remote view). While LAN is shown, two level filters separate the local traffic: local↔local (localhost to localhost, both endpoints loopback) and local↔LAN (localhost to or from LAN/private peers) -- each independently toggleable, both on by default.
  • Owner networks -- each remote peer is resolved to its ASN and organization via an offline ASN database, then bucketed into a colour-coded category: corp (Microsoft / Apple / Google / ...), cloud (AWS / Azure / GCP / Hetzner / ...), cdn (Cloudflare / Akamai / Fastly / ...), gov (government / military, best-effort), telecom (consumer ISPs / carriers), or unknown (no ASN match). A legend strip shows the known-vs-unknown breakdown and one-click filters the table by category. Government detection is heuristic (AS-name keywords plus a small curated ASN list) and intentionally conservative to avoid false positives.
  • World map -- an offline choropleth highlighting the countries of current connections.

Socket data is read straight from the kernel over netlink (NETLINK_SOCK_DIAG / INET_DIAG, including per-socket tcp_info byte counters), so there is no dependency on the ss/iproute2 binary. Everything is offline except reverse-DNS, which uses the system resolver (same as normal browsing) and can be turned off. GeoIP country and ASN/owner lookups both use bundled local DBs; no observed IP is ever sent to a third party. (UDP exposes no per-socket byte counters, so UDP shows as connections without bandwidth.)

Abuse-IP detection (AbuseIPDB)

Optional; off until you configure an API key. When enabled, LinAudit automates the same forensic steps you'd otherwise do by hand the moment a live connection's peer matches a known-malicious IP:

  1. Fetch -- once a day (linaudit-abusefeed.timer), linaudit abusefeed refresh downloads AbuseIPDB's bulk blacklist (GET /api/v2/blacklist, confidence >= 90 by default) and atomically writes it to a local CSV cache (/usr/local/share/linaudit/abuseipdb/blacklist.csv). This bulk pull is the only network call this feature ever makes -- individual observed IPs are never looked up against AbuseIPDB or any other third party; matching is purely a local map lookup against the cached file (web/netmon/abuse.go), consistent with the GeoIP/ASN "nothing observed leaves the machine" contract above.
  2. Match -- the existing connection sampler checks each live remote peer against the cached blacklist (offline, in-process) as it already does for GeoIP/ASN.
  3. Respond (alert + forensics only -- deliberately no auto-block, no auto-kill): on a match, alert.Handle fingerprints the owning process (pid, exe path + its SHA-256, cmdline, parent chain, owner), takes a short scoped tcpdump capture of just that one connection's 5-tuple (bounded to 20s / 500 packets -- enough to recover the TLS SNI hostname without decrypting anything), persists a JSON record to /var/log/linaudit/alerts/alerts.log, and sends a desktop notification to the monitored user. A 30-minute per-peer cooldown prevents repeat-alerting on one still-open connection.

Setup: get a free API key at https://www.abuseipdb.com/ (developer account), then either pass it to the installer --

sudo ABUSEIPDB_API_KEY=your-key-here sh install.sh

-- or add it after the fact to /etc/linaudit/linaudit.env (ABUSEIPDB_API_KEY=..., 0600 root-owned) and run sudo systemctl enable --now linaudit-abusefeed.timer && sudo linaudit abusefeed refresh. linaudit doctor reports whether the feed is configured and, once fetched, how fresh the cache is. The key is never logged, hardcoded, or exposed anywhere, including by doctor (which only reports whether one is set).

Alerts and captures live under the encrypted store like everything else (/var/log/linaudit/alerts/alerts.log, .../alerts/pcaps/*.pcap) and are viewable in the dashboard's Logs > abuse alerts tab or linaudit logs alerts. The text log is logrotated (daily, 14 days) same as the other logs, but captured .pcap files are not auto-pruned -- they are typically small and few, but clean them up manually (.../alerts/pcaps/) if disk space becomes a concern on a long-running, frequently-alerting host.

Repository layout / deployment map

The runtime is one statically-linked binary built from the Go packages (cmd/linaudit plus web, web/netmon, web/procmon, inputmon, storage, abusefeed, alert, cli). The dashboard HTML and world map are compiled into it via go:embed.

Repo path Deployed to Notes
cmd/linaudit + the Go packages /usr/local/bin/linaudit one static binary; every role is a subcommand
web/dashboard.html, web/world.svg embedded in the binary via go:embed -- no sidecar files at runtime
shell/linaudit.zsh ~/.config/zsh/linaudit.zsh sourced from ~/.zshrc; captures prompt buffer + executed commands
shell/linaudit.bash ~/.config/bash/linaudit.bash sourced from ~/.bashrc; captures executed commands
shell/linaudit.fish ~/.config/fish/conf.d/linaudit.fish auto-loaded by fish (no rc edit); captures executed commands
inputmon/linaudit-input.service /etc/systemd/system/ ExecStart=/usr/local/bin/linaudit input
web/linaudit-web.service /etc/systemd/system/ ExecStart=/usr/local/bin/linaudit web
storage/linaudit-store.service /etc/systemd/system/ ExecStart=/usr/local/bin/linaudit store up; ordered before the writers
abusefeed/linaudit-abusefeed.{service,timer} /etc/systemd/system/ daily ExecStart=/usr/local/bin/linaudit abusefeed refresh; only enabled if ABUSEIPDB_API_KEY is set
alert/ (package, no unit) runs in-process inside linaudit web fingerprint + capture + persist + notify on an abuse-IP match; writes under /var/log/linaudit/alerts/
data/fetch-geoip.sh downloads to /usr/local/share/linaudit/geoip/ offline IP->country + IP->ASN/org DBs (CC BY 4.0)
system/linaudit.rules /etc/audit/rules.d/ auditd (augenrules --load)
system/97-linaudit.rules /etc/udev/rules.d/ USB/input add-remove -> journal
system/linaudit.logrotate /etc/logrotate.d/linaudit daily, 14 days; installer templates the monitored user; covers alerts.log too (not the pcaps)
system/linaudit-dashboard.json /etc/brave/policies/managed/ sets the dashboard as Brave homepage
install.sh run as root detect user, build + install everything, store init, enable services, run doctor
(generated) /etc/linaudit/linaudit.env written by installer LINAUDIT_USER=<user> and, if provided, ABUSEIPDB_API_KEY=<key>; sourced by the store + web + abusefeed units
test/inject/ go run ./test/inject (root) simulates a software keystroke injector (uinput)

linaudit store init (root, run once) creates the LUKS2 container and seals the key to the TPM; it replaces the former secure-init.sh / secure-mount.sh shell scripts, now folded into the binary (linaudit store up|down).

The container file is created with all of its space allocated up front and, on a copy-on-write filesystem, exempt from copy-on-write. Both matter: the store is reached through a loop device, so a write the host filesystem cannot satisfy comes back as an I/O error, and that takes the store read-only until it is checked -- every plane then records nothing while the services still look healthy. sudo linaudit store reserve (with the store closed) converts an image created before this, linaudit doctor reports the state on its store backing line, and store up repairs a filesystem that was already damaged before it mounts it. See docs/runbook.md, "Store read-only".

Runtime dependencies: systemctl / journalctl (the systemd base) and, for the encrypted store, cryptsetup + systemd-creds (systemd >= 250). A TPM2 device hardware-binds the store key; without one the key seals host-only (with a warning). auditd/auditctl (exec/uinput/USB plane) and nvidia-smi (GPU VRAM) are optional and degrade gracefully when absent. No Python, no iproute2, no shared libraries. Run linaudit doctor to see exactly what is available on a given host.

Runtime secrets and captured data live OUTSIDE the repo and are git-ignored: the TPM-sealed key (/etc/linaudit/store.key.cred), the password hash (/var/lib/linaudit/auth.json), the encrypted container (/var/lib/linaudit/store.img), and all *.log files.

Build & install

Build (Go >= 1.21; standard library only, so the build is offline and reproducible and cross-compiles to amd64/arm64/arm/386):

make build      # -> ./linaudit  (CGO_ENABLED=0 static, ~7 MB, no runtime deps)
make test       # parity vectors, parsers, classify, scrypt, evdev decode, identity

One-step install on any systemd distro (privileged; creates an encrypted volume -- review it first):

sudo sh install.sh

It auto-detects the monitored user (override with LINAUDIT_USER=), installs the binary + units + configs, templates the logrotate user, fetches the offline GeoIP DB (SKIP_GEOIP=1 to skip), runs linaudit store init (SKIP_STORE=1 to skip), enables the services, installs the shell hooks for every shell present (bash/zsh/fish), and finishes with linaudit doctor. Pass ABUSEIPDB_API_KEY=your-key-here to also enable abuse-IP detection (daily timer + an immediate first fetch); omitted, that feature just stays configured-off (see "Abuse-IP detection" above for enabling it later without a reinstall).

Prefer to do it by hand: install ./linaudit to /usr/local/bin/; the three units from inputmon/, web/, storage/ to /etc/systemd/system/; the configs from system/ (substituting __LINAUDIT_USER__ in the logrotate file); run sudo linaudit store init then systemctl enable --now linaudit-store linaudit-input linaudit-web; sudo sh data/fetch-geoip.sh; and install the shell hooks -- shell/linaudit.zsh sourced from ~/.zshrc, shell/linaudit.bash from ~/.bashrc, and shell/linaudit.fish dropped into ~/.config/fish/conf.d/ (auto-loaded). If auditd is installed, augenrules --load.

Security and privacy notes

  • Logs are local and 0600, encrypted at rest, never transmitted.
  • The keystroke log is effectively a keylogger (root-only). Disable any time with linaudit disable input.
  • The web service is root and localhost-only; worst case for an authenticated abuse is toggling monitoring -- there is no arbitrary-command path.
  • Abuse-IP detection is the one deliberate exception to "logs never transmitted" -- and only in the fetch direction. It downloads AbuseIPDB's bulk blacklist (public reputation data about IPs in general, not about this host); it never sends an observed IP, hostname, or any other host data to AbuseIPDB or anywhere else. Its response is strictly alert + forensics: it never blocks a peer or kills a process. ABUSEIPDB_API_KEY lives only in root-owned /etc/linaudit/linaudit.env (0600) and is never logged or displayed, including by doctor.

Known limitations / TODO

  • The monitored user is auto-detected (LINAUDIT_USER > SUDO_USER > current user

    store-dir owner > sole login account) and install.sh pins it in /etc/linaudit/linaudit.env; only multi-user hosts with no LINAUDIT_USER need manual selection. System paths under /usr/local, /var/lib, /var/log, /etc/linaudit are fixed. The web bind address is overridable via LINAUDIT_ADDR.

  • Targets systemd Linux (all popular distros: Ubuntu/Debian/Fedora/RHEL/Arch/ openSUSE/Mint/Pop!_OS). The static binary is distro/libc-agnostic; the units and configs assume systemd, and the encrypted store needs systemd >= 250 + cryptsetup. a supported shell (bash/zsh/fish) is needed only for the shell plane, and only zsh captures unexecuted prompt text; auditd, TPM2, Brave, and nvidia-smi are optional and degrade gracefully. linaudit doctor reports what is present.
  • Builds for amd64/arm64/arm/386 (verified). Tested on amd64; the evdev decode and ioctl numbers assume the asm-generic encoding (x86/arm/arm64), so exotic arches (mips/ppc/sparc) would need a check.
  • No uninstaller yet; make covers build/test/install-binary and install.sh does the full system install.
  • Abuse-IP detection is one signal, not a guarantee: it only catches peers already on AbuseIPDB's list, refreshed once a day, at whatever confidence threshold is configured (90 by default) -- a fresh or under-reported malicious IP, or one below that threshold, will not match. .pcap captures under alerts/pcaps/ are not auto-pruned by logrotate (only alerts.log is); clean them up manually if needed.
  • Planned/optional: UDP per-process bandwidth (no per-socket UDP byte counters), and diff-patch table rendering so refresh does not reset scroll/selection.

Third-party data and assets

  • GeoIP: ip-location-db geo-whois-asn-country (CC BY 4.0, by NRO) -- fetched via data/fetch-geoip.sh, not vendored.
  • ASN/org: ip-location-db asn (CC BY 4.0, by RouteViews / DB-IP / NRO) -- fetched via data/fetch-geoip.sh, not vendored.
  • World map: simple-world-map (web/world.svg) by Al MacDonald / Fritz Lekschas, CC BY-SA 3.0.
  • Abuse-IP blacklist: AbuseIPDB /api/v2/blacklist, optional and requires your own free API key -- see "Abuse-IP detection" above. Subject to AbuseIPDB's own terms; not vendored, refetched daily.

License

Apache License 2.0 -- see LICENSE. Third-party data/assets retain their own licenses (see above).

About

A free Linux live system intrusion detection system with auditing

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages