daemonaudit 0.1.0__py3-none-any.whl

daemonaudit/__init__.py

@@ -0,0 +1,3 @@
+"""daemonaudit — red/blue security audit for self-hosted AI agent daemons."""
+
+__version__ = "0.1.0"

daemonaudit/__main__.py

@@ -0,0 +1,4 @@
+from daemonaudit.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

daemonaudit/banner.py

@@ -0,0 +1,13 @@
+from daemonaudit import __version__
+
+DEMON = r"""
+   ^      ^
+   |\    /|
+  (  o  o  )    daemonaudit v{v}
+   \  ~~  /     who can hurt your agent — and how badly
+    `----´
+"""
+
+
+def banner() -> str:
+    return DEMON.format(v=__version__)

daemonaudit/chain/__init__.py

@@ -0,0 +1,3 @@
+from daemonaudit.chain.rules import build_attack_paths, build_blast_radius
+
+__all__ = ["build_attack_paths", "build_blast_radius"]

daemonaudit/chain/rules.py

@@ -0,0 +1,161 @@
+"""Chain rules: turn a flat list of findings into attack paths.
+
+A rule is an ordered list of hops; each hop is a set of tags, any one of which
+satisfies it. A path exists when every hop has at least one finding carrying one of
+its tags. The first matching finding per hop becomes the hop shown in the report.
+`kill_hop` is the earliest hop — fix it and the whole path is gone.
+
+A path needs a real foothold: hop 1 must be MEDIUM or worse, intermediate hops at
+least LOW; only the final hop (what is reached) may be INFO. Without this, the vendor's
+own `curl | bash` install docs (LOW, bundled) would "chain" on every default install.
+
+Tags are set by checks (see each check) — rules never parse titles.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from daemonaudit.model import AttackPath, BlastEntry, Finding, RedactedSecret, ScanReport, Severity
+
+# What a stolen credential of each kind lets an attacker do.
+BLAST: dict[str, str] = {
+    "anthropic-api-key": "spend on your Anthropic account and run models as you; reads nothing of yours",
+    "openai-api-key": "spend on your OpenAI account; may reach fine-tunes, files and assistants you created",
+    "openrouter-api-key": "spend your OpenRouter balance across every provider it fronts",
+    "azure-openai-api-key": "spend on your Azure OpenAI resource",
+    "google-api-key": "billable calls on every Google API the key is enabled for",
+    "google-oauth-client-secret": "impersonate your OAuth app to users who trust it",
+    "github-token": "act as you on GitHub: read private repos, push commits, open PRs, read Actions secrets it can see",
+    "github-fine-grained-pat": "whatever repos/permissions the PAT was scoped to, as you",
+    "telegram-bot-token": "become your bot: read every message sent to it and reply to your contacts as it",
+    "discord-bot-token": "become your bot in every server it is in: read channels it can see, post as it",
+    "discord-webhook-url": "post anything into that Discord channel as the webhook",
+    "slack-token": "read channels and DMs the token can see; post as the bot or as you",
+    "slack-app-token": "open Socket Mode connections as your Slack app",
+    "aws-access-key-id": "whatever the IAM identity allows — often everything in the account",
+    "private-key-block": "log in to every host or service that trusts this key",
+    "jwt": "act as the session/identity the token represents until it expires",
+    "bearer-token": "act as whatever identity the bearer token represents",
+    "url-embedded-credential": "log in to that service as that user",
+    "generic-credential": "unknown — depends on the service; assume the worst until you know",
+}
+
+
+@dataclass(frozen=True)
+class Rule:
+    name: str
+    narrative: str
+    hops: tuple[frozenset[str], ...]
+    reaches_default: str
+
+
+RULES: list[Rule] = [
+    Rule(
+        "Remote → agent tools → every credential",
+        "Something on the network reaches the daemon without a password, hands it a prompt, and the agent runs commands on your host with your keys in its environment.",
+        (frozenset({"net:public"}), frozenset({"net:unauth", "net:unauth:verified"}), frozenset({"exec:host", "exec:noapproval"}), frozenset({"secret:procenv", "secret:vault"})),
+        "every credential the daemon holds",
+    ),
+    Rule(
+        "Local unauthenticated service → agent tools → every credential",
+        "A service on this host answers without auth. Anything running as any user here — a browser tab via a crafted page, another account, a compromised package — can drive the agent.",
+        (frozenset({"net:unauth", "net:unauth:verified"}), frozenset({"exec:host", "exec:noapproval"}), frozenset({"secret:procenv", "secret:vault"})),
+        "every credential the daemon holds",
+    ),
+    Rule(
+        "Anyone on the chat platform → prompt injection → commands as you",
+        "The front door is open to strangers. A message is a prompt; with approvals weakened, a prompt is a shell.",
+        (frozenset({"content:allow-all", "net:unauth-inbound"}), frozenset({"exec:noapproval", "exec:noapproval:cron"}), frozenset({"exec:host", "secret:procenv", "secret:vault"})),
+        "command execution as your user, and every credential",
+    ),
+    Rule(
+        "Malicious skill → remote code → your host",
+        "A skill you installed downloads and runs code on first use. It runs where the agent runs: on your host, as you.",
+        (frozenset({"skill:remote-exec"}), frozenset({"exec:host"}), frozenset({"secret:procenv", "secret:vault"})),
+        "everything in the daemon's environment",
+    ),
+    Rule(
+        "Skill sees master keys → exfiltration",
+        "Provider keys are passed into every command the agent runs, and at least one skill both reads credentials and talks to the network.",
+        (frozenset({"secret:passthrough"}), frozenset({"skill:exfil-shape", "skill:wants-secrets", "skill:remote-exec"})),
+        "the forwarded provider keys",
+    ),
+    Rule(
+        "Injected instructions in a skill → agent acts against you",
+        "Text the model reads contains instructions a human would not see. With approvals weakened there is nothing between those instructions and your shell.",
+        (frozenset({"skill:injection"}), frozenset({"exec:noapproval", "exec:noapproval:cron", "exec:host"})),
+        "command execution as your user",
+    ),
+    Rule(
+        "SSRF → local services → agent",
+        "The agent's web tools may be pointed at localhost, and something is listening there. A hostile web page becomes a client of your own services.",
+        (frozenset({"ssrf:off"}), frozenset({"net:loopback", "net:unauth", "net:unauth:verified"})),
+        "whatever the loopback services expose — including the agent's own API",
+    ),
+    Rule(
+        "Local user → readable credentials",
+        "No exploit needed: another account or process on this host just reads the file.",
+        (frozenset({"secret:sprawl:readable", "secret:vault-readable"}),),
+        "the credentials in the listed files",
+    ),
+    Rule(
+        "Local user → gateway socket → agent as you",
+        "The control socket is writable by others. Connecting to it is driving the agent with your identity.",
+        (frozenset({"local:gateway-socket"}), frozenset({"secret:procenv", "secret:vault", "exec:host"})),
+        "command execution as your user, and every credential",
+    ),
+]
+
+
+def _index(findings: list[Finding]) -> dict[str, list[Finding]]:
+    idx: dict[str, list[Finding]] = {}
+    for f in findings:
+        for t in f.tags:
+            idx.setdefault(t, []).append(f)
+    return idx
+
+
+def build_attack_paths(report: ScanReport) -> list[AttackPath]:
+    idx = _index(report.findings)
+    vault = [f for f in report.findings if "secret:vault" in f.tags]
+    reach_detail = ""
+    if vault and vault[0].secrets:
+        kinds: dict[str, int] = {}
+        for s in vault[0].secrets:
+            kinds[s.kind] = kinds.get(s.kind, 0) + 1
+        reach_detail = " (" + ", ".join(f"{k}×{n}" for k, n in sorted(kinds.items())) + ")"
+    paths: list[AttackPath] = []
+    for rule in RULES:
+        hops: list[Finding] = []
+        used: set[int] = set()
+        for n, hop in enumerate(rule.hops):
+            last = n == len(rule.hops) - 1
+            floor = Severity.MEDIUM.rank if n == 0 else (Severity.INFO.rank if last else Severity.LOW.rank)
+            candidates = [f for t in hop for f in idx.get(t, []) if id(f) not in used and f.severity.rank >= floor]
+            if not candidates:
+                break
+            best = max(candidates, key=lambda f: f.severity.rank)
+            hops.append(best)
+            used.add(id(best))
+        else:
+            reaches = rule.reaches_default + (reach_detail if "credential" in rule.reaches_default else "")
+            paths.append(AttackPath(rule.name, rule.narrative, hops, reaches, kill_hop=1))
+    paths.sort(key=lambda p: -p.severity.rank)
+    return paths
+
+
+def build_blast_radius(report: ScanReport) -> list[BlastEntry]:
+    """Per-kind summary of every credential the audit could see (vault + process env)."""
+    seen: dict[str, dict[str, RedactedSecret]] = {}
+    for f in report.findings:
+        if not ({"secret:vault", "secret:procenv"} & set(f.tags)):
+            continue
+        for s in f.secrets:
+            seen.setdefault(s.kind, {})[s.fingerprint] = s
+    out = [
+        BlastEntry(kind, len(v), BLAST.get(kind, BLAST["generic-credential"]), [s.display for s in list(v.values())[:5]])
+        for kind, v in seen.items()
+    ]
+    out.sort(key=lambda b: (-b.count, b.kind))
+    return out

daemonaudit/checks/_walk.py

@@ -0,0 +1,63 @@
+"""Shared filesystem helpers for checks. Never follows symlinks below the root."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Iterator
+
+
+def _guard_root(root: Path) -> bool:
+    """The root must exist and must not itself be a symlink (discovery resolved it)."""
+    return root.exists() and not root.is_symlink()
+
+
+def _prune(d: Path, root: Path, dirnames: list[str], exclude: set[str], exclude_root: set[str]) -> None:
+    banned = exclude | (exclude_root if d == root else set())
+    dirnames[:] = [n for n in dirnames if n not in banned and not (d / n).is_symlink()]
+
+
+def walk_files(root: Path, exclude: set[str], max_depth: int = 4, exclude_root: set[str] = frozenset()) -> Iterator[Path]:
+    root = Path(root)
+    if not _guard_root(root):
+        return
+    if root.is_file():
+        yield root
+        return
+    base_depth = len(root.parts)
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        d = Path(dirpath)
+        if len(d.parts) - base_depth >= max_depth:
+            dirnames[:] = []
+        _prune(d, root, dirnames, exclude, exclude_root)
+        for fn in filenames:
+            p = d / fn
+            if p.is_symlink():
+                continue
+            yield p
+
+
+def walk_entries(root: Path, exclude: set[str], max_depth: int = 3, exclude_root: set[str] = frozenset()) -> Iterator[Path]:
+    """Files *and* directories below root (not root itself)."""
+    root = Path(root)
+    if not _guard_root(root) or not root.is_dir():
+        return
+    base_depth = len(root.parts)
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        d = Path(dirpath)
+        if len(d.parts) - base_depth >= max_depth:
+            dirnames[:] = []
+        _prune(d, root, dirnames, exclude, exclude_root)
+        for n in dirnames:
+            yield d / n
+        for fn in filenames:
+            p = d / fn
+            if not p.is_symlink():
+                yield p
+
+
+def rel(home: Path, p: Path) -> str:
+    try:
+        return str(p.relative_to(home))
+    except ValueError:
+        return str(p)

daemonaudit/checks/advisories.py

@@ -0,0 +1,75 @@
+"""ADV-001: version staleness and dismissed advisories — from Hermes's own local
+cache only. daemonaudit never contacts the network."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from daemonaudit.discover.hermes_config import load_settings
+from daemonaudit.model import CheckOutput, Finding, Position, Severity, Target
+from daemonaudit.platform import NotSupported, Platform
+from daemonaudit.registry import check
+
+
+@check("ADV-001", "Outdated daemon or dismissed security advisories", Position.CONTENT)
+def advisories(target: Target, plat: Platform) -> CheckOutput:
+    out = CheckOutput()
+    settings = load_settings(target, plat)
+    p = target.home / ".update_check"
+    try:
+        raw = plat.read_nofollow(p, 64 * 1024)
+    except NotSupported:
+        raw = p.read_bytes() if p.exists() else b""
+    except FileNotFoundError:
+        raw = b""
+    except OSError as e:
+        out.note(f".update_check unreadable ({e.strerror or e})")
+        raw = b""
+    if raw:
+        try:
+            d = json.loads(raw.decode("utf-8", "replace"))
+            behind = int(d.get("behind") or 0)
+            ts = d.get("ts")
+            age = ""
+            if isinstance(ts, (int, float)):
+                days = (datetime.now(timezone.utc) - datetime.fromtimestamp(ts, timezone.utc)).days
+                age = f", checked {days} day(s) ago"
+            if behind > 0:
+                out.findings.append(
+                    Finding(
+                        check_id="ADV-001",
+                        title=f"Hermes is {behind} update(s) behind (v{d.get('ver') or target.version or '?'}{age})",
+                        severity=Severity.LOW if behind < 10 else Severity.MEDIUM,
+                        position=Position.CONTENT,
+                        asset=str(p),
+                        why=(
+                            "Per Hermes's own update check. Agent frameworks ship security fixes often "
+                            "(gateway auth, injection guards, dependency advisories); running behind means running known bugs."
+                        ),
+                        fix="hermes update   # then restart the gateway",
+                        verify_cmd="hermes doctor",
+                        evidence=[f"behind={behind}"],
+                    )
+                )
+        except (ValueError, TypeError):
+            out.note(".update_check is not valid JSON")
+    else:
+        out.note(".update_check absent — Hermes has not run its update check")
+
+    acked = settings.get("security.acked_advisories") or []
+    if acked:
+        out.findings.append(
+            Finding(
+                check_id="ADV-001",
+                title=f"{len(acked)} security advisory(ies) have been dismissed",
+                severity=Severity.INFO,
+                position=Position.CONTENT,
+                asset=str(target.home / "config.yaml"),
+                why="`hermes doctor --ack` hides an advisory permanently. Make sure each one was resolved, not just silenced.",
+                fix="Review: remove ids from security.acked_advisories in config.yaml to see them again.",
+                verify_cmd="hermes doctor",
+                evidence=[str(a) for a in acked[:10]],
+            )
+        )
+    return out

daemonaudit/checks/network.py

@@ -0,0 +1,149 @@
+"""NET-001: what the daemon listens on. NET-002: unix socket permissions."""
+
+from __future__ import annotations
+
+import ipaddress
+
+from daemonaudit.checks._walk import rel, walk_entries
+from daemonaudit.discover.hermes import DEFAULT_PORTS
+from daemonaudit.discover.hermes_config import load_settings
+from daemonaudit.model import CheckOutput, Finding, Position, Severity, Target
+from daemonaudit.platform import Platform
+from daemonaudit.registry import check
+
+
+def _is_loopback(ip: str) -> bool:
+    try:
+        return ipaddress.ip_address(ip.split("%")[0]).is_loopback
+    except ValueError:
+        return ip in ("localhost",)
+
+
+def _is_wildcard(ip: str) -> bool:
+    return ip in ("0.0.0.0", "::", "*", "")
+
+
+@check("NET-001", "Daemon listeners reachable from the network", Position.REMOTE)
+def listeners(target: Target, plat: Platform) -> CheckOutput:
+    out = CheckOutput()
+    settings = load_settings(target, plat)
+    pids = set(target.pids)
+    names = {}
+    for pid in list(pids):
+        for c in plat.children(pid):
+            pids.add(c["pid"])
+            names[c["pid"]] = c["name"]
+    known_ports = dict(DEFAULT_PORTS)
+    api_port, _ = settings.env("API_SERVER_PORT")
+    if api_port and api_port.isdigit():
+        known_ports["api_server"] = int(api_port)
+    port_names = {v: k for k, v in known_ports.items()}
+
+    sockets = plat.listening_sockets()  # NotSupported → registry marks skip
+    ours = [s for s in sockets if (s["pid"] in pids) or (s["port"] in port_names)]
+
+    if not target.pids:
+        out.findings.append(
+            Finding(
+                check_id="NET-001",
+                title="Daemon is not running — network exposure could not be observed",
+                severity=Severity.INFO,
+                position=Position.REMOTE,
+                asset=str(target.home),
+                why="Listeners can only be attributed to the daemon while it runs. Only well-known daemon ports were checked.",
+                fix="Re-run the audit while the gateway is running for a complete picture.",
+                verify_cmd="daemonaudit scan  # with the gateway up",
+            )
+        )
+
+    loop: list[str] = []
+    for s in sorted(ours, key=lambda s: (s["port"], s["ip"])):
+        who = port_names.get(s["port"], names.get(s["pid"], "daemon"))
+        label = f"{s['ip']}:{s['port']} ({who}, pid {s['pid']})"
+        if _is_loopback(s["ip"]):
+            loop.append(label)
+            continue
+        exposure = "every interface" if _is_wildcard(s["ip"]) else f"the {s['ip']} interface"
+        api_unauth = s["port"] == known_ports["api_server"] and not settings.env_set("API_SERVER_KEY")
+        out.findings.append(
+            Finding(
+                check_id="NET-001",
+                title=f"Daemon port {s['port']} ({who}) is bound to {exposure}",
+                severity=Severity.CRITICAL if api_unauth else Severity.HIGH,
+                position=Position.REMOTE,
+                asset=f"{s['ip']}:{s['port']}",
+                why=(
+                    f"Anything that can reach this host on port {s['port']} can talk to the daemon directly. "
+                    + ("The API server has no API_SERVER_KEY, so that access is unauthenticated: remote prompt → tool use. "
+                       if api_unauth else "Whether that is safe depends entirely on the auth in front of it. ")
+                    + "On a laptop this includes every network you join."
+                ),
+                fix=(
+                    "Bind to 127.0.0.1 (e.g. API_SERVER_HOST=127.0.0.1) and reach it over SSH/Tailscale, "
+                    "or put it behind an authenticating reverse proxy. Set API_SERVER_KEY if the API server is enabled."
+                ),
+                verify_cmd=f"ss -tlnp 2>/dev/null | grep ':{s['port']} ' || lsof -nP -iTCP:{s['port']} -sTCP:LISTEN",
+                evidence=[label],
+                tags=["net:public"] + (["net:unauth"] if api_unauth else []),
+            )
+        )
+    if loop:
+        out.findings.append(
+            Finding(
+                check_id="NET-001",
+                title=f"{len(loop)} daemon listener(s) are loopback-only",
+                severity=Severity.INFO,
+                position=Position.REMOTE,
+                asset=str(target.home),
+                why="Loopback listeners are reachable only by processes on this host. That is the right default; listed for inventory.",
+                fix="Nothing to do — keep them this way.",
+                evidence=loop[:15],
+                tags=["net:loopback"],
+            )
+        )
+    return out
+
+
+@check("NET-002", "Unix sockets accessible to other users", Position.LOCAL)
+def unix_sockets(target: Target, plat: Platform) -> CheckOutput:
+    if not plat.posix_modes:
+        from daemonaudit.registry import Skipped
+
+        raise Skipped(f"{plat.name}: socket permission bits unavailable")
+    out = CheckOutput()
+    home, lay = target.home, target.layout
+    for p in walk_entries(home, lay.exclude_dirs, max_depth=3, exclude_root=lay.exclude_root_dirs):
+        try:
+            m = plat.file_mode(p)
+        except OSError as e:
+            out.note(f"cannot stat {p} ({e.strerror or e})")
+            continue
+        if not m.is_socket:
+            continue
+        if m.other_writable:
+            sev, who = Severity.HIGH, "any local user"
+        elif m.group_writable:
+            sev, who = Severity.LOW, "the file's group"
+        else:
+            continue
+        r = rel(home, p)
+        gateway = p.name == "gateway.sock"
+        out.findings.append(
+            Finding(
+                check_id="NET-002",
+                title=f"Socket {r} is writable by {who} (mode {m.octal})",
+                severity=Severity.HIGH if (gateway and m.group_writable) else sev,
+                position=Position.LOCAL,
+                asset=str(p),
+                why=(
+                    "Connecting to a unix socket needs write permission on it. "
+                    + ("This is the gateway control socket: whoever can write to it can drive the agent as you. "
+                       if gateway else "Local processes running as other users can send it messages.")
+                ),
+                fix=f"chmod 600 {p}  # and set umask 077 for the daemon so it is created that way",
+                verify_cmd=plat.stat_cmd(p),
+                evidence=[f"mode {m.octal}"],
+                tags=["local:gateway-socket"] if gateway else [],
+            )
+        )
+    return out