ubuntils

CLI/TUI Python per il triage forense di sistemi Ubuntu — rileva e rimuove i meccanismi di persistenza con raccolta di artefatti, correlazione temporale e integrazione con Wazuh.

Quando sospetti che un sistema Linux sia compromesso, i primi 30-40 minuti vengono solitamente spesi eseguendo gli stessi dieci comandi in sequenza: controllare i processi in esecuzione, cercare cron job sospetti, fare grep per LD_PRELOAD, scansionare authorized_keys alla ricerca di nuove voci, verificare sudoers. Ogni passaggio è manuale, richiede cambi di contesto ed è soggetto a errori sotto pressione. Basta saltare una fonte — ad esempio /etc/sudoers.d/ invece del solo /etc/sudoers, oppure i crontab utente oltre a /etc/cron.d/ — e si ottiene un quadro incompleto.

Le opzioni esistenti non risolvono la questione in modo pulito. lynis è un auditor di hardening, non uno strumento di triage — segnala debolezze di configurazione su un sistema pulito e genera rumore su uno compromesso. chkrootkit e rkhunter verificano firme di rootkit note ma sono ciechi a tecniche di persistenza nuove come timer systemd abusati o voci cron dall'aspetto legittimo. Le query SIEM generiche richiedono un'infrastruttura di log che potrebbe non esistere sul sistema che stai esaminando. E le suite forensi come Volatility sono pensate per immagini di memoria, non per una shell live su un host in esecuzione.

La lacuna è uno strumento che venga eseguito sul sistema live in questo momento, copra i vettori di persistenza più comuni, correli l'attività tra le fonti di log in una timeline e ti dica esattamente cosa guardare — senza richiedere un agente esterno, un database o una connessione a Internet.

Cosa fa ubuntils

ubuntils si articola in quattro fasi sequenziali:

1. Raccolta — Undici collector raccolgono artefatti forensi in modo concorrente da /proc, tabelle cron, unit systemd, chiavi SSH, file sudoers, definizioni di ambiente, integrità dei pacchetti (dpkg --verify), configurazione PAM/NSS e moduli kernel caricati. Richiede circa 2,5 secondi su un sistema tipico.
2. Rilevamento — Un motore di detection esegue tutte e sedici le regole integrate — più eventuali regole personalizzate caricate con --rules — sugli artefatti raccolti, producendo un elenco di risultati classificati e con punteggio di confidenza in circa un secondo.
3. Timeline — Un costruttore di timeline legge syslog, journald e auditd in parallelo e correla gli eventi cronologicamente, aggiungendo circa 0,3 secondi. Ogni risultato viene poi correlato automaticamente alla timeline, così porta con sé gli eventi vicini a esso correlati.
4. Output — I risultati appaiono in una TUI interattiva a quattro schede (predefinita) oppure come JSON strutturato su stdout (--json).

ubuntils stesso non effettua chiamate di rete, e ogni funzionalità — regole personalizzate e correlazione incluse — opera su artefatti raccolti localmente. L'unico modo in cui i risultati possono lasciare l'host è l'integrazione Wazuh: se è installato un agente Wazuh, uno scan live scrive i suoi risultati in un file locale che l'agente invia poi al suo manager. Passa --no-wazuh per disattivarlo per una singola esecuzione.

ubuntils scan è invariato rispetto a tutto quanto segue — è ancora 100% live, single-host, e ogni flag esistente funziona in modo identico. Due comandi aggiuntivi, collect e analyze, dividono la stessa pipeline di detection/timeline in un flusso di lavoro acquire-then-analyze adatto all'offline per i casi in cui non puoi (o non vuoi) eseguire il rilevamento direttamente sull'host sotto indagine — vedi Analisi offline: collect e analyze più sotto, incluse le sue avvertenze sulla copertura del rilevamento.

Installazione

Ubuntu 22.04+ e qualsiasi sistema con PEP 668 (consigliato):

Ubuntu 22.04+ blocca pip install a livello di sistema. Usa pipx — gestisce l'ambiente in modo trasparente così non devi mai pensarci:```bash sudo apt install pipx -y cd ubuntils pipx install -e . ubuntils scan

ubuntils richiede i privilegi di root per l'accesso completo agli artefatti. Se esegui ubuntils scan come utente non-root, si reinvoca automaticamente con sudo utilizzando lo stesso interprete Python (tramite percorso assoluto), così viene utilizzato l'ambiente corretto senza inoltrare il tuo PATH nel processo root. Ogni comando esterno (ss, dpkg, systemctl, …) viene risolto su un percorso di ricerca fisso, di proprietà di root, mai sul tuo PATH. L'esecuzione senza root salterà /etc/shadow, alcune voci di /proc e i file cron protetti, e registrerà un avviso per ciascuno.

Avvio rapido

Solo rilevamento — TUI interattiva:```bash sudo ubuntils scan

Rilevamento con anteprima di correzione CLI (dry run — nessuna modifica applicata):```bash sudo ubuntils scan --remediate

Versione stampabile:```bash ubuntils version

Analizza un bundle raccolto in precedenza (non è richiesto root):```bash ubuntils analyze /path/to/bundle.tar.gz --json

Vedi Analisi offline: raccolta e analisi per il formato del bundle e — cosa importante — cosa l'analisi offline non può rilevare rispetto a una scan dal vivo.

Flag e configurazione```

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

ubuntils collect [OPTIONS] --output FILE Bundle path to write (default ./ubuntils-bundle-.tar.gz) --verbose Verbose structlog output

ubuntils analyze (BUNDLE | --root PATH) [OPTIONS] --root PATH Analyze a mounted image / artifact tree instead of a bundle --json Output JSON instead of launching the TUI --output FILE Write the JSON report to FILE (implies --json) --config FILE YAML allowlist of findings to suppress (same format as scan) --baseline FILE YAML baseline of environment-specific known-good fingerprints to suppress (same format as scan) --rules FILE YAML file of custom detection rules to add (same format as scan) --since TIME Limit the timeline to events since TIME (e.g. '24h', '7d', '2026-05-20') --verbose Verbose structlog output

ubuntils version Print version string and exit

| --no-color | Disabilita l'output colorato | | --debug | Abilita l'output di debug | | --verbose | Abilita l'output dettagliato | | --silent | Sopprime tutto l'output non essenziale | | --json | Emette i risultati in formato JSON | | --csv | Emette i risultati in formato CSV | | --html | Emette i risultati in formato HTML | | --markdown | Emette i risultati in formato Markdown | | --output FILE | Scrive l'output su FILE | | --config FILE | Usa il file di configurazione FILE | | --profile NAME | Usa il profilo di configurazione NAME | | --timeout SECONDS | Imposta il timeout a SECONDS | | --retries N | Riprova le operazioni fallite N volte | | --threads N | Usa N thread per l'esecuzione | | --rate-limit N | Limita le richieste a N al secondo | | --proxy URL | Usa il proxy URL | | --user-agent STRING | Imposta lo User-Agent a STRING | | --header HEADER | Aggiunge HEADER alle richieste | | --cookie COOKIE | Aggiunge COOKIE alle richieste | | --auth TOKEN | Usa TOKEN per l'autenticazione | | --api-key KEY | Usa KEY come chiave API | | --insecure | Disabilita la verifica del certificato TLS | | --follow-redirects | Segue i reindirizzamenti HTTP | | --max-redirects N | Limita i reindirizzamenti a N | | --quiet | Sopprime l'output non essenziale | | --force | Forza l'operazione senza conferma | | --dry-run | Mostra cosa verrebbe fatto senza eseguirlo | | --yes | Risponde automaticamente sì ai prompt | | --no-input | Disabilita tutti i prompt interattivi | | --log-level LEVEL | Imposta il livello di log a LEVEL | | --log-file FILE | Scrive i log su FILE | | --version | Mostra la versione del programma ed esce | | --help | Mostra il messaggio di aiuto ed esce |```bash sudo ubuntils scan --json --config allowlist.yaml

I cannot translate this content because no text was provided. The INPUT section is empty.

Please send the actual Markdown content for chunk 29, and I will return the Italian translation following all the rules you specified.```bash sudo ubuntils scan --json --baseline baseline.yaml

| -s | --server | SERVER | http://localhost:8080 | URL del server MCP | | -t | --token | TOKEN | None | Token di autenticazione | | -c | --config | CONFIG | None | File di configurazione | | -v | --verbose | VERBOSE | False | Abilita logging dettagliato | | -o | --output | OUTPUT | None | File di output | | -f | --format | FORMAT | json | Formato di output (json, yaml, table) | | -q | --quiet | QUIET | False | Modalità silenziosa | | -d | --debug | DEBUG | False | Abilita modalità debug | | -h | --help | HELP | False | Mostra messaggio di aiuto |

Esempi di Utilizzo

Sviluppo

Configurazione dell'Ambiente

Esecuzione dei Test

Stile del Codice

Contribuire

1. Fai il fork del repository
2. Crea un branch per la funzionalità (git checkout -b feature/amazing-feature)
3. Effettua il commit delle modifiche (git commit -m 'Add some amazing feature')
4. Esegui il push sul branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

Licenza

Questo progetto è distribuito sotto la Licenza MIT - vedi il file LICENSE per i dettagli.

Ringraziamenti

• Grazie a tutti i contributori
• Ispirato dal protocollo MCP
• Costruito con Python e amore

Supporto

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussioni: GitHub Discussions

Nota: Questo è un progetto di esempio per scopi dimostrativi.```bash sudo ubuntils scan --json --rules custom_rules.yaml

Analisi offline: raccolta e analisi

ubuntils scan esegue raccolta, rilevamento e timeline insieme sull'host attivo. collect e analyze dividono quella pipeline in due: collect acquisisce un bundle a prova di manomissione da un host (non esegue rilevamenti), e analyze esegue la stessa pipeline di rilevamento/timeline usata da scan su un bundle, o su un'immagine montata tramite --root, senza richiedere root e senza toccare nuovamente l'host originale. Questo è per i casi in cui vuoi acquisire gli artefatti una volta e analizzarli più tardi, altrove, o ripetutamente — o quando stai facendo triage di un'immagine disco invece che di un sistema in esecuzione.

`ubuntils collect````bash

sudo ubuntils collect --output /path/to/bundle.tar.gz

Accetta come argomento posizionale un percorso di bundle oppure --root PATH che punta a un'immagine montata / albero di filesystem estratto — non entrambi. Esegue lo stesso motore di rilevamento, le regole personalizzate, l'allowlist e la logica di baseline usati da scan. Non richiede root. Il bundle viene estratto in una directory temporanea privata che viene eliminata non appena l'analisi termina (può contenere /etc/shadow).

La copertura differisce tra le due modalità offline, perché un bundle trasporta uno stato catturato riprodotto al momento di collect, mentre --root ha solo ciò che si trova sul filesystem montato:

• analyze BUNDLE riproduce l'output reale dei comandi ss/systemctl list-timers/journalctl catturato al momento di collect, quindi NetworkCollector e SystemdCollector producono risultati autentici da quella istantanea — non vengono saltati. La timeline è costruita dal syslog/messages/audit.log/journalctl che il bundle ha catturato, quindi è completamente popolata e i risultati ottengono una correlazione reale tramite related_events.
• analyze --root PATH punta a un'immagine montata e inattiva, senza processi attivi o stato del kernel da interrogare, quindi l'esecuzione dei comandi è completamente disabilitata: NetworkCollector e SystemdCollector vengono saltati, registrati in scan_metadata.command_collectors_skipped. La timeline viene comunque costruita, ma dai file di log statici presenti sull'immagine (/var/log/syslog, /var/log/messages, /var/log/audit/audit.log) — la riproduzione di journald non è disponibile qui poiché non c'è un journalctl attivo per interrogare un'immagine inattiva.

Vedi Offline analysis: collect and analyze per l'elenco completo delle lacune di copertura del rilevamento offline.

Formato del bundle

Un bundle è un tarball gzippato con tutto sotto un prefisso bundle/:``` bundle/ ├── manifest.json ├── files/ │ ├── etc/passwd │ ├── etc/shadow │ ├── var/log/syslog │ └── ... # every captured file, path-flattened under files/ └── commands/ ├── ss.txt ├── netstat.txt ├── systemctl_list_timers_json.txt ├── systemctl_list_timers_text.txt └── journalctl.txt

✓ indica successo, ✗ indica fallimento, lo spinner indica il collector attivo, e le righe vuote sono in attesa. Una volta che tutti i collector terminano e il rilevamento + la timeline sono completati, la TUI passa automaticamente alla schermata dei risultati.

Schermata dei risultati

La schermata dei risultati ha quattro schede navigate tramite i tasti numerici:

Premi q o Ctrl+C per uscire.

Scheda Riepilogo (tasto 1)

Mostra i metadati della scansione e i principali risultati su un'unica schermata:``` Collectors: 8 run · 0 failed Findings: 2 HIGH · 1 MEDIUM · 0 LOW Timeline: 47 events Duration: 2.8s

● HIGH CRON_TMP_PATH /etc/cron.d/cleanup ● HIGH LD_PRELOAD_INJECT /home/alice/.bashrc ○ MED SSH_UNAUTHORIZED_KEY /home/bob/.ssh/authorized_keys

Remediation in-TUI

Per i risultati che dispongono di una remediation automatizzata, premi R mentre il risultato è selezionato. Appare una finestra di conferma:``` ┌─────────────────────────────────────────────────┐ │ Remediate CRON_TMP_PATH? │ │ │ │ Will remove the offending cron entry from │ │ /etc/cron.d/cleanup after creating a backup. │ │ Backup will be created at /var/backups/ubuntils/…│ │ │ │ Y: confirm Esc: cancel │ └─────────────────────────────────────────────────┘

In caso di errore, il pannello dei dettagli mostra l'errore. Il backup viene sempre creato prima di tentare qualsiasi modifica.

Premi Esc per comprimere il pannello dei dettagli.

Scheda Timeline (tasto 3)

Un elenco cronologico scorrevole di eventi di log correlati. Ogni riga mostra timestamp, origine e descrizione. Gli eventi vengono raccolti da syslog, journald e auditd e deduplicati.

Scheda Stats (tasto 4)

Una vista riepilogativa della scansione: versione di Ubuntu rilevata, architettura, durata della scansione, numero di collector e fallimenti, e conteggi dei risultati per severità insieme al totale degli eventi della timeline.

Cosa rileva

Perché esiste ciascuna regola

CRON_ROOT_EXEC — I crontab utente vengono eseguiti come proprietario del crontab. Una voce che invoca sudo o un interprete di proprietà di root significa che l'utente ha organizzato l'esecuzione di codice con privilegi di root in modo pianificato, senza bisogno di un accesso sudo persistente. Questo sopravvive ai cambi di password.

Esempio di risultato:``` [HIGH] CRON_ROOT_EXEC Title: User crontab executing with sudo Artifact: /var/spool/cron/crontabs/alice Raw value: */5 * * * * sudo /usr/bin/python3 /tmp/beacon.py Remediation: available

LD_PRELOAD_INJECT — LD_PRELOAD fa sì che il linker dinamico carichi una libreria condivisa specificata prima di tutte le altre, consentendo l'intercettazione arbitraria di funzioni in qualsiasi binario collegato dinamicamente. Un valore che punta al di fuori dei percorsi standard delle librerie è un indicatore quasi certo di rootkit nello spazio utente; viene controllata ogni libreria in un elenco separato da spazi o due punti. /etc/ld.so.preload si inietta in ogni processo ed è vuoto su Ubuntu standard, quindi qualsiasi voce presente viene segnalata — anche una inserita all'interno di /lib, un trucco comune dei rootkit. La remediation rimuove le voci da /etc/ld.so.preload anziché commentarle, perché il loader non ha sintassi per i commenti in quel file.

Esempio di rilevamento:``` [HIGH] LD_PRELOAD_INJECT Title: LD_PRELOAD set to non-standard library path Artifact: /home/alice/.bashrc Raw value: export LD_PRELOAD=/tmp/.libssl.so Remediation: available

SSH_UNAUTHORIZED_KEY — Una chiave SSH appena aggiunta concede accesso remoto persistente indipendentemente dalle password. La finestra di 7 giorni intercetta le aggiunte recenti evitando il rumore derivante dal provisioning iniziale su sistemi più vecchi. Nota: la regola utilizza l'mtime del file, che riflette l'ultima scrittura al file authorized_keys, non il timestamp di inserimento di ogni singola chiave.

Esempio di rilevamento:``` [MEDIUM] SSH_UNAUTHORIZED_KEY Title: SSH authorized key added in last 7 days Artifact: /home/bob/.ssh/authorized_keys Raw value: ssh-rsa AAAAB3NzaC1... attacker@evil Remediation: available

PROCESS_MASQUERADE — Assegnare a un binario malevolo il nome di un processo di sistema noto (sshd, python3, bash) è una tecnica di base per evitare il rilevamento nell'output di ps. Questa regola confronta il nome del processo da /proc/<pid>/status con il percorso exe risolto da /proc/<pid>/exe. Le posizioni standard includono /usr/local/{bin,sbin}, /usr/lib, /usr/libexec e /snap, quindi systemd (/usr/lib/systemd/systemd) e i pacchetti snap non la attivano. Solo segnalazione — terminare un processo richiede il giudizio umano.

Esempio di rilevamento:``` [MEDIUM] PROCESS_MASQUERADE Title: Process masquerading as system binary Artifact: /proc/1337/exe Raw value: name=sshd, exe=/tmp/.sshd Remediation: not available

USER_EMPTY_PASSWORD — Un account il cui campo password in /etc/shadow è vuoto non ha alcuna password, e lo stack PAM predefinito di Ubuntu (pam_unix ... nullok) ne consente l'accesso senza inserirne una. Su un account con una shell di login, questa è una porta aperta. Solo segnalazione — bloccalo con passwd -l mentre indaghi.

Esempio di rilevamento:``` [HIGH] USER_EMPTY_PASSWORD Title: Login account with no password Artifact: /etc/shadow Raw value: eve:: Remediation: not available

SHELL_RC_MODIFICATION — I file di inizializzazione della shell sono un vettore di persistenza affidabile perché vengono eseguiti a ogni login dell'utente. Questa regola evidenzia le modifiche recenti per la revisione umana. Solo segnalazione — il contenuto degli RC della shell richiede una lettura prima di agire su di esso.

Esempio di rilevamento:``` [LOW] SHELL_RC_MODIFICATION Title: Shell init file recently modified Artifact: /root/.bashrc Raw value: mtime=2024-01-15 14:22:01 (6 hours ago) Remediation: not available

IMMUTABLE_FLAG_SET — Gli attaccanti spesso impostano il flag immutable (i) o il flag append-only (a) sui file per impedirne la modifica o la cancellazione, persino da parte di root, anche per nascondere manomissioni da ulteriori modifiche/rotazione dei log. L'impostazione di questi flag su file di sistema sensibili come /etc/passwd, /etc/sudoers, /etc/pam.d/*, o sui file di log auth/syslog/wtmp/btmp è un forte indicatore di hardening da parte dell'attaccante. Questa regola rileva i flag immutable e append-only tramite lsattr su quella lista fissa di percorsi sensibili. Solo flag — le modifiche ai flag richiedono una revisione umana.

Esempio di rilevamento:``` [MEDIUM] IMMUTABLE_FLAG_SET Title: Sensitive file has an unexpected chattr flag Artifact: /etc/ld.so.preload Raw value: ----i--------e--- Remediation: not available

KERNEL_MODULE_SUSPICIOUS — I moduli del kernel vengono eseguiti in ring 0 con accesso illimitato. Gli attaccanti caricano frequentemente moduli del kernel personalizzati per rootkit, sniffing di pacchetti o occultamento di processi. Questa regola confronta i moduli attualmente caricati con una piccola allowlist di moduli integrati previsti (comuni alla maggior parte dei sistemi). È di severità LOW perché tale allowlist è deliberatamente ristretta. Nota: host con molto hardware, con driver GPU, schede Wi-Fi o driver proprietari genereranno falsi positivi. I responder dovrebbero aggiungere i moduli previsti del proprio host tramite --config, inserendo in allowlist il nome del modulo (usato come artifact_path). Solo flag — l'indagine sui moduli del kernel richiede strumenti forensi e competenza umana.

Esempio di rilevamento:``` [LOW] KERNEL_MODULE_SUSPICIOUS Title: Loaded kernel module not in the expected set Artifact: implant_rootkit Raw value: {'name': 'implant_rootkit', 'size': '12288', 'used_by': []} Remediation: not available

Output JSON

--json scrive un singolo oggetto JSON su stdout. Non viene stampato nient'altro.```json { "scan_metadata": { "tool_version": "2.1.0", "hostname": "web-01", "generated_at": "2026-06-10T08:22:03.114523+00:00", "ubuntu_version": "Ubuntu 22.04.3 LTS", "architecture": "x86_64", "duration_s": 2.84, "collector_failures": 0, "bundle_integrity": "live", "command_collectors_skipped": [], "collectors_degraded": {}, "rules_failed": [], "timeline_error": null, "suppressed_by_baseline": 1 }, "artifact_counts": { "ProcessCollector": 142, "NetworkCollector": 23, "UserCollector": 4, "CronCollector": 7, "SystemdCollector": 12, "SSHCollector": 3, "SudoersCollector": 5, "EnvironmentCollector": 18 }, "findings": [ { "rule_id": "CRON_TMP_PATH", "severity": "HIGH", "title": "Cron job references writable temp directory", "description": "A cron job was found referencing /tmp, /var/tmp, or /dev/shm. These directories are world-writable and commonly used as attacker staging grounds.", "artifact_path": "/etc/cron.d/cleanup", "raw_value": "0 * * * * root /tmp/.update", "remediation_available": true, "remediation_description": "Will remove the offending cron entry from /etc/cron.d/cleanup after creating a timestamped backup.", "related_events": [ { "timestamp": "2024-01-15T08:20:00+00:00", "source": "syslog", "description": "CRON[2841]: (root) CMD (/tmp/.update)" } ], "confidence": 75, "confidence_band": "HIGH", "signals": [ {"name": "timeline_corroboration", "weight": 25, "detail": "1 nearby timeline event(s)"} ] }, { "rule_id": "PROCESS_MASQUERADE", "severity": "MEDIUM", "title": "Process masquerading as system binary", "description": "Process 'sshd' (pid=1337) has exe path outside standard binary directories: /tmp/.sshd", "artifact_path": "/proc/1337/exe", "raw_value": "/tmp/.sshd", "remediation_available": false, "guided_remediation": "Confirm pid 1337 is malicious (ls -l /proc/1337/exe, cat /proc/1337/cmdline), then terminate it: kill -9 1337.", "confidence": 50, "confidence_band": "MEDIUM", "signals": [] } ], "timeline": [ { "timestamp": "2024-01-15T08:22:01+00:00", "source": "syslog", "description": "sshd: Accepted publickey for alice from 10.0.0.42 port 52341" } ], "report_sha256": "a3f1c9…(64 hex chars)" }

Salvaguardie

Ogni bonifica segue lo stesso schema indipendentemente da come viene attivata:

1. Rileva se il percorso dell'artefatto è un symlink — in tal caso rifiuta (impedisce la scrittura di root attraverso symlink controllati dall'attaccante)
2. Crea un backup con timestamp in /var/backups/ubuntils/YYYYMMDD_HHMMSS/ con modalità 0700
3. Convalida lo stato corrente (la riga esatta deve essere ancora presente)
4. Applica la modifica minima possibile — le voci cron e le chiavi vengono rimosse riga per riga; le righe LD_PRELOAD nei file di init della shell vengono commentate; le voci in /etc/ld.so.preload vengono rimosse (il loader non ha sintassi di commento lì, quindi una voce commentata verrebbe comunque caricata). Per sudoers, il contenuto modificato viene verificato con visudo -cf su una copia temporanea prima che il file reale venga toccato
5. Scrive atomicamente — il nuovo contenuto va in un file temporaneo accanto all'originale (stessa modalità e proprietario), viene fsync'd, poi rinominato sopra di esso, così un crash durante la scrittura non può lasciare un /etc/sudoers troncato
6. Verifica che la riga esatta sia sparita

Se un qualsiasi passaggio fallisce, la bonifica si interrompe immediatamente, il sistema viene lasciato invariato e l'errore completo viene segnalato con il percorso del backup e il comando di rollback. L'accesso sudo è protetto in due modi: le regole NOPASSWD %group (come %sudo) sono solo flag e non vengono mai rimosse automaticamente, e il bonificatore di sudoers rifiuta di rimuovere l'ultima regola dal file sudoers principale.

Integrazione con Wazuh

ubuntils è costruito per un triage su singolo host e in un momento preciso — lo esegui quando sospetti già che qualcosa non vada, e non contatta mai casa né continua a monitorare dopo la fine della scansione. È una scelta deliberata, ma significa anche che un risultato di ubuntils vive solo in quel singolo report a meno che qualcosa non lo porti avanti. La maggior parte dei team che esegue Ubuntu su qualsiasi scala ha già un SIEM che fa il lato continuo del rilevamento, quindi invece di costruire ubuntils come proprio agente di monitoraggio a lunga esecuzione, consegna i suoi risultati a quello che probabilmente esegui già: Wazuh.

Se un agente Wazuh è presente sull'host (/var/ossec/bin/wazuh-agentd o /var/ossec/etc/ossec.conf esiste), ubuntils scan (a meno che non venga eseguito con --no-wazuh) aggiunge ogni risultato come una riga JSON a /var/log/ubuntils/wazuh-alerts.json perché l'agente lo raccolga — questo è un puro forwarder, non un modulo Wazuh: nessuna chiamata di rete, nessuna chiave API, nient'altro che le stesse scritture di artefatti locali che ubuntils già effettua — anche se l'agente spedirà ovviamente quelle righe fuori dall'host al suo manager; questo è il punto. Viene rilevato automaticamente senza flag richiesto (usa --no-wazuh per escludere un'esecuzione), quindi un ubuntils scan scriptato o pianificato su una flotta di host registrati all'agente inizia ad alimentare il SIEM immediatamente senza cablaggio aggiuntivo. Questo non accade mai durante l'ubuntils analyze offline (bundle o --root), poiché quei risultati descrivono un host diverso da quello che esegue l'agente Wazuh locale — inoltrare i risultati di un bundle all'agente dell'analista li attribuirebbe alla macchina sbagliata.

L'intento è di integrare ubuntils in una pipeline di allerta/escalation esistente invece di chiedere a un responder di badare a un secondo strumento: una volta caricate le regole di esempio seguenti, un risultato ubuntils di severità HIGH (un nuovo account UID-0, un rootkit LD_PRELOAD, un backdoor PAM) appare come un normale avviso Wazuh, eredita qualunque routing di notifica il manager abbia già configurato, e si trova accanto a ogni altro segnale nella stessa timeline invece che in un file JSON autonomo che qualcuno deve ricordarsi di controllare.

Per far sì che Wazuh analizzi e avvisi su questi risultati, copia le regole di esempio da examples/wazuh/ sul tuo manager Wazuh, e aggiungi il blocco <localfile> da examples/wazuh/ossec_localfile_snippet.xml al file /var/ossec/etc/ossec.conf dell'agente. Non è necessaria l'installazione di un decoder personalizzato: il localfile è configurato con log_format json, quindi il decoder JSON integrato di Wazuh analizza ogni riga e mappa ogni chiave JSON di primo livello k su data.k, che local_rules.xml confronta direttamente.

1. examples/wazuh/local_rules.xml → /var/ossec/etc/rules/ del manager
2. Il blocco <localfile> di examples/wazuh/ossec_localfile_snippet.xml → /var/ossec/etc/ossec.conf dell'agente
3. Riavvia entrambi: systemctl restart wazuh-manager (manager), systemctl restart wazuh-agent (host dell'agente)

Questi sono solo template di esempio, forniti come punto di partenza — non sono stati testati contro un manager Wazuh live e dovrebbero essere verificati in un ambiente non di produzione prima di fare affidamento su di essi.

Schema JSON per riga:

Collector

Dipendenze dei collector

PackageCollector richiede tre strumenti standard di Ubuntu sull'host live (dpkg, lsattr, find — tutti presenti nelle installazioni Ubuntu standard). Se un comando non è disponibile, PackageCollector produce con garbo dati vuoti per quella porzione invece di andare in crash. L'analisi offline (analyze BUNDLE) riproduce l'output dei comandi catturato al momento di collect, quindi la disponibilità dei comandi sull'host dell'analizzatore non è richiesta.

La scansione find per setuid/setgid passa -xdev per rimanere limitata — non scende in filesystem montati separatamente (un mount distinto sotto /opt, un /home montato via NFS, ecc.). Questo è un compromesso deliberato tra runtime e copertura: senza -xdev, la scansione potrebbe bloccarsi scansionando mount di rete o filesystem virtuali. Se il tuo ambiente monta questi percorsi su filesystem separati, sappi che non verranno scansionati.

dpkg --verify e la scansione find per setuid/setgid usano timeout generosi non predefiniti (10 minuti e 5 minuti rispettivamente, vedi ubuntils/collectors/packages.py) poiché entrambi possono legittimamente superare di molto il default della libreria di 30 secondi su un host reale con un grande database di pacchetti o albero di filesystem; ubuntils collect usa gli stessi timeout quando cattura questi comandi in un bundle.

Compatibilità

L'esecuzione senza root produce una scansione parziale con avvisi. Percorsi critici come /etc/shadow, directory crontab protette e alcune voci di /proc verranno saltati.

Roadmap

v1.0.0

• Tutti gli 8 collector
• Tutte le 8 regole di rilevamento
• Costruttore di timeline (syslog, journald, auditd)
• Schermata di avanzamento della scansione live con ✓/✗ per collector
• TUI interattiva a quattro schede (Summary / Findings / Timeline / Stats)
• Bonifica nella TUI con modale di conferma e worker in background
• Modalità di output JSON
• Bonifica da CLI per 5 regole con backup, rollback e protezione symlink
• Supporto Ubuntu 20.04/22.04/24.04
• 240 test con copertura del 90%

v1.1.0

• Allowlisting dei falsi positivi per rule id o percorso (--config)
• --output FILE per scrivere i report direttamente
• Finestra temporale della timeline con --since
• Report a prova di manomissione (report_sha256, hostname, timestamp)
• Regola di rilevamento USER_UID_ZERO

v1.5.0

• Regole di rilevamento personalizzate con pattern-match via YAML (--rules)
• PROCESS_SUSPICIOUS_CONNECTION — correlazione processo↔rete tramite PID
• Correlazione automatica risultato↔timeline (related_events)
• Bonifica guidata per le tre regole che richiedono giudizio
• 282 test con copertura del 92%

Le ricerche di hash su VirusTotal e l'esportazione IOC MISP sono state rimosse da questa release. VirusTotal risponde solo per hash noti — il caso che rkhunter già copre, e l'opposto del gap sulle tecniche nuove che ubuntils prende di mira — ed entrambe le funzionalità avrebbero inserito una chiamata di rete in uno strumento il cui valore si basa sul non farne nessuna. ubuntils stesso non effettua ancora chiamate di rete (vedi l'integrazione con Wazuh per l'unico modo disattivabile con cui i risultati possono lasciare l'host, tramite un agente locale).

v2.0.0 — split offline collect/analyze

• ubuntils collect — acquisisce un bundle a prova di manomissione (manifest.json + file/comandi con hash) da un host live, senza rilevamento
• ubuntils analyze (BUNDLE | --root PATH) — esegue la stessa pipeline di rilevamento/timeline di scan su un bundle o un'immagine montata, senza root richiesto
• bundle_integrity (live/ok/mismatch) esposto in scan_metadata
• Gap documentati nella copertura del rilevamento in modalità offline (PROCESS_MASQUERADE, PROCESS_SUSPICIOUS_CONNECTION, e copertura ridotta per i percorsi glob di cron/sudoers/SSH e per ExecStart dei timer systemd)
• Rilevamento affidabile: punteggio di confidenza (confidence/confidence_band/signals), soppressione con --baseline, sostituzione delle euristiche basate solo su mtime in SSH_UNAUTHORIZED_KEY/SHELL_RC_MODIFICATION con segnali di ctime + contenuto, e una vera timeline offline sia per analyze BUNDLE che per analyze --root
• Pacchetto di copertura: PACKAGE_TAMPERED, IMMUTABLE_FLAG_SET, PAM_BACKDOOR, KERNEL_MODULE_SUSPICIOUS, SETUID_INVENTORY (tramite PackageCollector, PamCollector, KernelCollector; tutti solo flag per design)
• 400 test con copertura del 93,79%

v2.1.0 — inoltro al SIEM

• Risultati di ubuntils scan live inoltrati a un agente Wazuh locale come JSONL, rilevato automaticamente (nessun flag richiesto)
• Decoder/regole Wazuh di esempio e snippet <localfile> di ossec.conf (examples/wazuh/)
• Inoltro intenzionalmente limitato al solo scan live — non si attiva mai durante analyze offline, poiché un bundle o un'immagine descrive un host diverso da quello che esegue l'agente
• --no-wazuh per escludere una scansione dall'inoltro

v2.1.0 — hardening (audit completo del codebase)

• Sicurezza: il re-exec di sudo non inoltra più il PATH del chiamante, e i comandi si risolvono su un percorso sicuro fisso; le modifiche a sudoers sono verificate con visudo prima di toccare il file; scritture di bonifica atomiche; output di report/bundle sicuro rispetto ai symlink; bundle estratti eliminati dopo analyze
• Copertura del rilevamento: /etc/ld.so.preload analizzato, voci cron @reboot/@daily e script in /etc/cron.{hourly,daily,weekly,monthly}, unit .service di systemd e binari ExecStart non di proprietà di root, regole sudoers %group e #include/@includedir, ogni elemento di una lista LD_PRELOAD
• Nuova regola USER_EMPTY_PASSWORD (account di login senza password)
• Meno falsi positivi: controlli dei percorsi delimitati da separatori, distinzione tra setuid e setgid, daemon snap//usr/lib trattati come standard, KERNEL_MODULE_SUSPICIOUS declassato a LOW, un risultato NSS per modulo
• Report onesti: regole fallite e collector degradati registrati in scan_metadata e nella TUI; un fallimento della timeline non scarta più i risultati; bundle manomessi avvisano ed escono con codice 3; anno/fuso orario di syslog gestiti correttamente
• Bonifica più sicura: gate --min-confidence (default 40), risultati mostrati nella TUI dopo scan --remediate
• 444 test con copertura del 94,29%

v3.0.0 / v4.0.0 (esplorativo)

• Dashboard web per il triage multi-host
• Supporto macOS

Contribuire

I contributi più utili al momento sono nuove regole di rilevamento (aggiunte come funzioni autonome in detectors/rules.py con un test corrispondente), collector aggiuntivi per tipi di artefatti non ancora coperti, moduli di bonifica per SUSPICIOUS_SYSTEMD_TIMER e SHELL_RC_MODIFICATION (entrambi attualmente solo flag per design, ma potrebbero esistere percorsi di auto-bonifica sicuri), casi di test per edge case su configurazioni Ubuntu specifiche, e miglioramenti alla documentazione.

Apri una issue prima di iniziare un contributo importante per evitare lavoro duplicato.

Licenza

MIT

Autore

Creato da Asmit — BTech in Informatica, PES University, Bengaluru. Lo strumento è nato dalla frustrazione per quanto tempo richieda il triage manuale di Ubuntu rispetto a ciò che uno script ben mirato può automatizzare.