Python CLI/TUI for forensic triage of Ubuntu systems — detects and remediates persistence mechanisms with artifact collection, timeline correlation, and Wazuh integration.
Forensic triage for live Ubuntu systems — automated artifact collection, persistence detection, and guided remediation in about a minute.
When you suspect a Linux system is compromised, the first 30-40 minutes are usually spent running the same ten commands in sequence: check running processes, look for weird cron jobs, grep for LD_PRELOAD, scan authorized_keys for new entries, audit sudoers. Each step is manual, context-switching, and error-prone under pressure. Miss one source — say, /etc/sudoers.d/ instead of just /etc/sudoers, or user crontabs in addition to /etc/cron.d/ — and you have an incomplete picture.
Existing options don't solve this cleanly. lynis is a hardening auditor, not a triage tool — it reports configuration weaknesses on a clean system and generates noise on a hot one. chkrootkit and rkhunter check for known rootkit signatures but are blind to novel persistence techniques like abused systemd timers or legitimate-looking cron entries. Generic SIEM queries require log infrastructure that may not exist on the system you're looking at. And forensic suites like Volatility target memory images, not a live shell on a running host.
The gap is a tool that runs on the live system right now, covers the most common persistence vectors, correlates activity across log sources into a timeline, and tells you exactly what to look at — without requiring an external agent, a database, or an internet connection.
ubuntils runs in four sequential stages:
/proc, cron tables, systemd units, SSH keys, sudoers files, environment definitions, package integrity (dpkg --verify), PAM/NSS config, and loaded kernel modules. Most collectors finish in a second or two; dpkg --verify, which re-checks every installed package file, dominates — a full scan took 29–68 seconds on an Ubuntu 26.04 arm64 desktop VM.--rules — over the collected artifacts, producing a ranked, confidence-scored findings list in about one second.--json).ubuntils itself makes no network calls, and every feature — custom rules and correlation included — runs against locally collected artifacts. The one way findings can leave the host is the Wazuh integration: if a Wazuh agent is installed, a live scan writes its findings to a local file that the agent then ships to its manager. Pass --no-wazuh to turn that off for a run.
ubuntils scan is unchanged by everything below — it is still 100% live, single-host, and every existing flag works identically. Two additional commands, collect and analyze, split the same detection/timeline pipeline into an offline-friendly acquire-then-analyze workflow for cases where you can't (or don't want to) run detection directly on the host under investigation — see Offline analysis: collect and analyze below, including its detection-coverage caveats.
Ubuntu 22.04+ and any system with PEP 668 (recommended):
Ubuntu 22.04+ blocks system-wide pip install. Use pipx — it handles the environment transparently so you never think about it:
sudo apt install pipx -y
pipx ensurepath # then open a new shell
git clone https://github.com/asmitdesai/ubuntils.git
cd ubuntils
pipx install -e .
ubuntils scan # not `ubuntils scan` — see below
Run it as your normal user: scan and collect re-invoke themselves under sudo. Typing ubuntils … yourself fails with command not found, because sudo's secure_path doesn't include ~/.local/bin where pipx puts the command. If you need to start it from a root shell, call the installed binary by path (~youruser/.local/bin/ubuntils scan), or install into a virtual environment instead:
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/ubuntils scan
Older systems / manual install:
git clone https://github.com/asmitdesai/ubuntils.git
cd ubuntils
pip install -r requirements.txt -e .
ubuntils scan
ubuntils requires root for full artifact access. If you run ubuntils scan as a non-root user it will automatically re-invoke itself with sudo using the same Python interpreter (by absolute path), so the correct environment is used without forwarding your PATH into the root process. Every external command (ss, dpkg, systemctl, …) is resolved on a fixed, root-owned search path, never your PATH. Running without root will skip /etc/shadow, some /proc entries, and protected cron files, and will log warnings for each.
Detection only — interactive TUI:
ubuntils scan
Detection with JSON output saved to file:
ubuntils scan --json > /tmp/triage-$(hostname)-$(date +%Y%m%d).json
Detection with CLI remediation preview (dry run — no changes applied):
ubuntils scan --remediate
Detection with CLI remediation applied:
ubuntils scan --remediate --confirm
Print version:
ubuntils version
Collect a tamper-evident bundle for later or offline analysis:
ubuntils collect --output /path/to/bundle.tar.gz
Analyze a previously collected bundle (no root required):
ubuntils analyze /path/to/bundle.tar.gz --json
Analyze a mounted forensic image or extracted filesystem tree instead of a bundle:
ubuntils analyze --root /mnt/forensic-image --json
See Offline analysis: collect and analyze for the bundle format and — importantly — what offline analysis cannot detect compared to a live scan.
ubuntils scan [OPTIONS]
--json Output JSON to stdout instead of launching the TUI
--output FILE Write the JSON report to FILE (implies --json)
--remediate Run the remediation engine after detection
--confirm Required with --remediate to actually apply changes (else dry-run)
--min-confidence N Only auto-remediate findings with confidence >= N (default 40)
--no-wazuh Never forward findings to a local Wazuh agent
--config FILE YAML allowlist of findings to suppress (see below)
--baseline FILE YAML baseline of environment-specific known-good fingerprints to suppress (see below)
--since TIME Limit the timeline to events since TIME (e.g. '24h', '7d', '2026-05-20')
--rules FILE YAML file of custom detection rules to add (see below)
--verbose Verbose structlog output