ubuntils 1.5.0__py3-none-any.whl

ubuntils/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.5.0"

ubuntils/cli.py

@@ -0,0 +1,195 @@
+import os
+import platform
+import socket
+import sys
+import time
+from datetime import datetime, timezone
+
+import click
+import structlog
+
+from ubuntils import __version__
+from ubuntils.collectors import ALL_COLLECTORS
+from ubuntils.detectors.engine import DetectionEngine
+from ubuntils.detectors.finding import Severity
+from ubuntils.formatters.json_formatter import JSONFormatter
+from ubuntils.remediators import REMEDIATOR_REGISTRY
+from ubuntils.timeline.builder import TimelineBuilder
+from ubuntils.tui.app import UbuntilsApp
+from ubuntils.tui.stats_panel import get_ubuntu_version
+from ubuntils.utils.config import load_allowlist
+from ubuntils.utils.logging import configure_logging
+from ubuntils.utils.since_parser import parse_since
+
+logger = structlog.get_logger()
+
+
+def _ensure_root() -> None:
+    """Re-exec under sudo if not running as root, preserving the active venv/conda PATH."""
+    if os.geteuid() == 0:
+        return
+    current_path = os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin")
+    # Pass PATH through so sudo finds this venv's Python and ubuntils script.
+    args = ["sudo", "env", f"PATH={current_path}", sys.argv[0]] + sys.argv[1:]
+    print("ubuntils requires root — re-invoking with sudo…", file=sys.stderr)
+    try:
+        os.execvp("sudo", args)
+    except FileNotFoundError:
+        print("Error: sudo not found. Please run as root.", file=sys.stderr)
+        sys.exit(1)
+
+
+def _run_pipeline(remediate: bool, confirm: bool, allowlist=None, since=None) -> tuple:
+    """Run collectors → detection → timeline → optional remediation.
+
+    Returns (findings, timeline, stats, scan_metadata, artifact_counts, remediation_results).
+    """
+    start = time.monotonic()
+    artifacts: dict = {}
+    failures = 0
+    artifact_counts: dict = {}
+    collectors = [C() for C in ALL_COLLECTORS]
+
+    for collector in collectors:
+        name = type(collector).__name__
+        try:
+            result = collector.collect()
+            artifacts.update(result)
+            artifact_counts[name] = sum(
+                len(v) if isinstance(v, (list, dict)) else 1
+                for v in result.values()
+            )
+        except Exception as exc:
+            logger.error("collector_failed", name=name, error=str(exc))
+            failures += 1
+
+    try:
+        findings = DetectionEngine(allowlist=allowlist).run(artifacts)
+        timeline = TimelineBuilder().build()
+        if since is not None:
+            timeline = [e for e in timeline if e.timestamp >= since]
+    except Exception as exc:
+        logger.error("scan_engine_failed", error=str(exc))
+        findings = []
+        timeline = []
+
+    duration = time.monotonic() - start
+
+    remediation_results = []
+    if remediate:
+        for finding in findings:
+            remediator_cls = REMEDIATOR_REGISTRY.get(finding.rule_id)
+            if remediator_cls is None:
+                continue
+            result = remediator_cls().remediate(finding, dry_run=not confirm)
+            remediation_results.append(result)
+            logger.info(
+                "remediation",
+                rule_id=finding.rule_id,
+                status=result.status.value,
+                message=result.message,
+            )
+
+    ubuntu_version = get_ubuntu_version()
+    arch = platform.machine()
+
+    stats = {
+        "ubuntu_version": ubuntu_version,
+        "architecture": arch,
+        "duration_s": duration,
+        "collector_count": len(collectors),
+        "collector_failures": failures,
+        "finding_counts": {
+            "HIGH": sum(1 for f in findings if f.severity == Severity.HIGH),
+            "MEDIUM": sum(1 for f in findings if f.severity == Severity.MEDIUM),
+            "LOW": sum(1 for f in findings if f.severity == Severity.LOW),
+        },
+        "timeline_count": len(timeline),
+    }
+
+    scan_metadata = {
+        "tool_version": __version__,
+        "hostname": socket.gethostname(),
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "ubuntu_version": ubuntu_version,
+        "architecture": arch,
+        "duration_s": duration,
+        "collector_failures": failures,
+    }
+
+    return findings, timeline, stats, scan_metadata, artifact_counts, remediation_results
+
+
+@click.group()
+def main():
+    """ubuntils - Ubuntu incident response tool."""
+    pass
+
+
+@main.command()
+@click.option("--json", "output_json", is_flag=True, help="Output JSON instead of launching TUI")
+@click.option("--remediate", is_flag=True, help="Run remediation engine after detection")
+@click.option("--confirm", is_flag=True, help="Required with --remediate to apply changes")
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False),
+              help="YAML config with false-positive allowlist (rules/paths to suppress)")
+@click.option("--output", "output_path", type=click.Path(dir_okay=False),
+              help="Write JSON report to FILE instead of stdout (implies --json)")
+@click.option("--since", "since_value",
+              help="Limit timeline to events since this time (e.g. '24h', '7d', '2026-05-20')")
+@click.option("--verbose", is_flag=True, help="Enable verbose logging")
+def scan(output_json, remediate, confirm, config_path, output_path, since_value, verbose):
+    """Scan the system for forensic artifacts and suspicious activity."""
+    _ensure_root()
+    if output_path:
+        output_json = True
+    configure_logging(json_mode=output_json, verbose=verbose)
+
+    since = None
+    if since_value:
+        try:
+            since = parse_since(since_value)
+        except ValueError as exc:
+            raise click.ClickException(str(exc))
+
+    allowlist = None
+    if config_path:
+        try:
+            allowlist = load_allowlist(config_path)
+        except (ValueError, OSError) as exc:
+            raise click.ClickException(f"Invalid config {config_path}: {exc}")
+
+    if output_json or remediate:
+        findings, timeline, stats, scan_metadata, artifact_counts, remediation_results = \
+            _run_pipeline(remediate=remediate, confirm=confirm, allowlist=allowlist, since=since)
+
+        if output_json:
+            report = JSONFormatter().format(
+                scan_metadata, artifact_counts, findings, timeline, remediation_results
+            )
+            if output_path:
+                with open(output_path, "w") as f:
+                    f.write(report + "\n")
+                click.echo(f"Report written to {output_path}", err=True)
+            else:
+                click.echo(report)
+            return
+
+        # --remediate without --json: launch TUI with pre-computed results
+        def _override():
+            return (findings, timeline, stats)
+
+        UbuntilsApp(verbose=verbose, _scan_override=_override).run()
+        return
+
+    # Plain TUI mode: let the app run its own scan with live progress
+    UbuntilsApp(verbose=verbose, allowlist=allowlist, since=since).run()
+
+
+@main.command()
+def version():
+    """Print version and exit."""
+    click.echo(__version__)
+
+
+if __name__ == "__main__":
+    main()

ubuntils/collectors/__init__.py

@@ -0,0 +1,19 @@
+from ubuntils.collectors.processes import ProcessCollector
+from ubuntils.collectors.network import NetworkCollector
+from ubuntils.collectors.users import UserCollector
+from ubuntils.collectors.cron import CronCollector
+from ubuntils.collectors.systemd import SystemdCollector
+from ubuntils.collectors.ssh import SSHCollector
+from ubuntils.collectors.sudoers import SudoersCollector
+from ubuntils.collectors.environment import EnvironmentCollector
+
+ALL_COLLECTORS = [
+    ProcessCollector,
+    NetworkCollector,
+    UserCollector,
+    CronCollector,
+    SystemdCollector,
+    SSHCollector,
+    SudoersCollector,
+    EnvironmentCollector,
+]

ubuntils/collectors/base.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+
+class BaseCollector(ABC):
+    @abstractmethod
+    def collect(self) -> dict:
+        """
+        Collect forensic artifacts.
+        Returns a dict of collected data.
+        Must not raise — log exceptions and return {}.
+        """

ubuntils/collectors/cron.py

@@ -0,0 +1,73 @@
+import glob
+import os
+
+from ubuntils.collectors.base import BaseCollector
+
+
+class CronCollector(BaseCollector):
+    def collect(self) -> dict:
+        entries = []
+
+        # System crontab (7-field: min hour dom mon dow user command)
+        for path in ["/etc/crontab"] + glob.glob("/etc/cron.d/*"):
+            entries.extend(self._parse_system_crontab(path))
+
+        # User crontabs (5-field: min hour dom mon dow command)
+        for path in glob.glob("/var/spool/cron/crontabs/*"):
+            owner = os.path.basename(path)
+            entries.extend(self._parse_user_crontab(path, owner))
+
+        return {"cron_entries": entries}
+
+    def _parse_system_crontab(self, path: str) -> list:
+        entries = []
+        try:
+            with open(path) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if "=" in line and not line[0].isdigit() and not line[0] == "*":
+                        continue  # skip variable assignments
+                    parts = line.split(None, 6)
+                    if len(parts) < 7:
+                        continue
+                    schedule = " ".join(parts[:5])
+                    run_as = parts[5]
+                    command = parts[6]
+                    entries.append({
+                        "owner": "root",
+                        "run_as": run_as,
+                        "schedule": schedule,
+                        "command": command,
+                        "source": path,
+                    })
+        except Exception:
+            pass
+        return entries
+
+    def _parse_user_crontab(self, path: str, owner: str) -> list:
+        entries = []
+        try:
+            with open(path) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if "=" in line and not line[0].isdigit() and not line[0] == "*":
+                        continue
+                    parts = line.split(None, 5)
+                    if len(parts) < 6:
+                        continue
+                    schedule = " ".join(parts[:5])
+                    command = parts[5]
+                    entries.append({
+                        "owner": owner,
+                        "run_as": owner,
+                        "schedule": schedule,
+                        "command": command,
+                        "source": path,
+                    })
+        except Exception:
+            pass
+        return entries

ubuntils/collectors/environment.py

@@ -0,0 +1,86 @@
+import glob
+import os
+
+from ubuntils.collectors.base import BaseCollector
+from ubuntils.utils.validators import is_login_shell
+
+
+class EnvironmentCollector(BaseCollector):
+    def collect(self) -> dict:
+        definitions = []
+
+        definitions.extend(self._read_env_file("/etc/environment", "system"))
+        definitions.extend(self._read_shell_init("/etc/profile", "system"))
+        for path in glob.glob("/etc/profile.d/*.sh"):
+            definitions.extend(self._read_shell_init(path, "system"))
+
+        for username, home in self._get_login_users():
+            for filename in (".bashrc", ".bash_profile", ".profile", ".zshrc", ".zprofile"):
+                path = f"{home}/{filename}"
+                if os.path.exists(path):
+                    definitions.extend(self._read_shell_init(path, username))
+
+        return {"env_definitions": definitions}
+
+    def _get_login_users(self):
+        try:
+            with open("/etc/passwd") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    parts = line.split(":")
+                    if len(parts) < 7:
+                        continue
+                    username, home, shell = parts[0], parts[5], parts[6]
+                    if is_login_shell(shell) and home:
+                        yield username, home
+        except Exception:
+            return
+
+    def _read_env_file(self, path: str, owner: str) -> list:
+        entries = []
+        try:
+            with open(path) as f:
+                for line in f:
+                    raw = line.strip()
+                    if not raw or raw.startswith("#"):
+                        continue
+                    if "=" in raw:
+                        var, _, val = raw.partition("=")
+                        entries.append({
+                            "owner": owner,
+                            "source": path,
+                            "variable": var.strip(),
+                            "value": val.strip().strip("\"'"),
+                            "raw_line": raw,
+                        })
+        except Exception:
+            pass
+        return entries
+
+    def _read_shell_init(self, path: str, owner: str) -> list:
+        entries = []
+        try:
+            with open(path) as f:
+                for line in f:
+                    raw = line.strip()
+                    if not raw or raw.startswith("#"):
+                        continue
+                    actual = raw
+                    if actual.startswith("export "):
+                        actual = actual[7:].strip()
+                    if "=" in actual:
+                        var, _, val = actual.partition("=")
+                        var = var.strip()
+                        if var and all(c.isalnum() or c == "_" for c in var):
+                            entries.append({
+                                "owner": owner,
+                                "source": path,
+                                "variable": var,
+                                "value": val.strip().strip("\"'"),
+                                "raw_line": raw,
+                            })
+        except Exception:
+            pass
+        return entries

ubuntils/collectors/network.py

@@ -0,0 +1,58 @@
+from ubuntils.collectors.base import BaseCollector
+from ubuntils.utils.shell import run_command
+
+
+class NetworkCollector(BaseCollector):
+    def collect(self) -> dict:
+        stdout, _, returncode = run_command(["ss", "-tunap"])
+        if returncode != 0:
+            stdout, _, returncode = run_command(["netstat", "-tunap"])
+        if returncode != 0:
+            return {}
+
+        known_protos = {"tcp", "tcp6", "udp", "udp6", "raw", "raw6"}
+        connections = []
+        for line in stdout.splitlines():
+            parts = line.split()
+            if not parts or parts[0].lower() not in known_protos:
+                continue
+            if len(parts) < 5:
+                continue
+            proto = parts[0]
+            state = parts[1] if len(parts) > 5 else ""
+            local = parts[4] if len(parts) > 5 else parts[3]
+            remote = parts[5] if len(parts) > 5 else parts[4]
+
+            local_addr, local_port = self._split_addr(local)
+            remote_addr, remote_port = self._split_addr(remote)
+
+            pid = self._extract_pid(line)
+
+            connections.append({
+                "proto": proto,
+                "local_addr": local_addr,
+                "local_port": local_port,
+                "remote_addr": remote_addr,
+                "remote_port": remote_port,
+                "state": state,
+                "pid": pid,
+            })
+
+        return {"connections": connections}
+
+    def _split_addr(self, addr_port: str):
+        if addr_port in ("*", "0.0.0.0:*", ":::*"):
+            return addr_port, "*"
+        addr, _, port = addr_port.rpartition(":")
+        return addr or addr_port, port or "*"
+
+    def _extract_pid(self, line: str) -> str:
+        if "pid=" in line:
+            start = line.index("pid=") + 4
+            end = line.find(",", start)
+            return line[start:end] if end != -1 else line[start:].rstrip(")")
+        parts = line.split()
+        last = parts[-1] if parts else ""
+        if "/" in last:
+            return last.split("/")[0]
+        return ""

ubuntils/collectors/processes.py

@@ -0,0 +1,48 @@
+import glob
+import os
+
+from ubuntils.collectors.base import BaseCollector
+
+
+class ProcessCollector(BaseCollector):
+    def collect(self) -> dict:
+        processes = []
+        try:
+            status_paths = glob.glob("/proc/*/status")
+        except Exception:
+            return {}
+
+        for status_path in status_paths:
+            try:
+                pid = int(status_path.split("/")[2])
+                name, uid = self._parse_status(status_path)
+                exe = os.readlink(f"/proc/{pid}/exe")
+                cmdline = self._read_cmdline(f"/proc/{pid}/cmdline")
+                processes.append({
+                    "pid": pid,
+                    "name": name,
+                    "uid": uid,
+                    "exe": exe,
+                    "cmdline": cmdline,
+                })
+            except FileNotFoundError:
+                continue
+            except Exception:
+                continue
+
+        return {"processes": processes}
+
+    def _parse_status(self, path: str):
+        name, uid = "", 0
+        with open(path) as f:
+            for line in f:
+                if line.startswith("Name:"):
+                    name = line.split(":", 1)[1].strip()
+                elif line.startswith("Uid:"):
+                    uid = int(line.split(":", 1)[1].split()[0])
+        return name, uid
+
+    def _read_cmdline(self, path: str) -> str:
+        with open(path, "rb") as f:
+            data = f.read()
+        return data.replace(b"\x00", b" ").decode(errors="replace").strip()

ubuntils/collectors/ssh.py

@@ -0,0 +1,52 @@
+import os
+
+from ubuntils.collectors.base import BaseCollector
+
+
+class SSHCollector(BaseCollector):
+    def collect(self) -> dict:
+        entries = []
+        try:
+            with open("/etc/passwd") as f:
+                passwd_lines = f.readlines()
+        except Exception:
+            return {}
+
+        for line in passwd_lines:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split(":")
+            if len(parts) < 6:
+                continue
+            username, home = parts[0], parts[5]
+            if not home:
+                continue
+            auth_keys_path = f"{home}/.ssh/authorized_keys"
+            if not os.path.exists(auth_keys_path):
+                continue
+            try:
+                file_mtime = os.stat(auth_keys_path).st_mtime
+                with open(auth_keys_path) as f:
+                    for key_line in f:
+                        key_line = key_line.strip()
+                        if not key_line or key_line.startswith("#"):
+                            continue
+                        key_parts = key_line.split(None, 2)
+                        if len(key_parts) < 2:
+                            continue
+                        key_type = key_parts[0]
+                        key_data = key_parts[1]
+                        comment = key_parts[2] if len(key_parts) > 2 else ""
+                        entries.append({
+                            "username": username,
+                            "home": home,
+                            "key_type": key_type,
+                            "key_data": key_data,
+                            "comment": comment,
+                            "file_mtime": float(file_mtime),
+                        })
+            except Exception:
+                continue
+
+        return {"authorized_keys": entries}

ubuntils/collectors/sudoers.py

@@ -0,0 +1,75 @@
+import glob
+
+from ubuntils.collectors.base import BaseCollector
+
+
+class SudoersCollector(BaseCollector):
+    def collect(self) -> dict:
+        rules = []
+        paths = ["/etc/sudoers"] + glob.glob("/etc/sudoers.d/*")
+        for path in paths:
+            rules.extend(self._parse_sudoers_file(path))
+        return {"sudoers_rules": rules}
+
+    def _parse_sudoers_file(self, path: str) -> list:
+        rules = []
+        try:
+            with open(path) as f:
+                for line in f:
+                    raw = line.strip()
+                    if not raw or raw.startswith("#") or raw.startswith("@"):
+                        continue
+                    if raw.startswith("#include") or raw.startswith("@include"):
+                        continue
+                    if "=" not in raw and raw.startswith("Defaults"):
+                        continue
+                    parsed = self._parse_rule_line(raw, path)
+                    if parsed:
+                        rules.append(parsed)
+        except Exception:
+            pass
+        return rules
+
+    def _parse_rule_line(self, line: str, source: str):
+        # Basic sudoers rule: user host=(run_as) [options:] commands
+        # Skip Defaults lines
+        if line.startswith("Defaults"):
+            return None
+        parts = line.split(None, 2)
+        if len(parts) < 3:
+            return None
+        user = parts[0]
+        host_runas_cmds = parts[2] if len(parts) > 2 else parts[1]
+
+        # Extract run_as from (...)
+        run_as = ""
+        if "(" in host_runas_cmds and ")" in host_runas_cmds:
+            start = host_runas_cmds.index("(")
+            end = host_runas_cmds.index(")")
+            run_as = host_runas_cmds[start + 1:end]
+            rest = host_runas_cmds[end + 1:].strip()
+        else:
+            rest = host_runas_cmds
+
+        # Extract options (NOPASSWD, PASSWD, etc.)
+        options = ""
+        if ":" in rest:
+            maybe_options, _, commands = rest.partition(":")
+            maybe_options = maybe_options.strip()
+            if any(kw in maybe_options for kw in ("NOPASSWD", "PASSWD", "NOEXEC", "EXEC")):
+                options = maybe_options
+                commands = commands.strip()
+            else:
+                commands = rest
+        else:
+            commands = rest
+
+        return {
+            "source": source,
+            "user": user,
+            "host": parts[1],
+            "run_as": run_as,
+            "options": options,
+            "commands": commands.strip(),
+            "raw_line": line,
+        }