drosera 0.1.0__py3-none-any.whl

drosera/__init__.py

@@ -0,0 +1,40 @@
+"""Drosera -- a carnivorous honeypot for autonomous AI agents.
+
+    Sweet-looking bait. Sticky ending.
+
+Named for the sundew, which catches gnats not with force but with droplets
+that look exactly like something worth landing on.
+
+Quick start::
+
+    from drosera import Snare, Observation
+
+    snare = Snare()
+    decision = snare.decide(Observation(session_id="", path="/", headers={...}))
+    print(decision.assessment.summary())
+
+Or wrap an existing app::
+
+    from drosera.middleware.asgi import DroseraMiddleware
+    app = DroseraMiddleware(app)
+"""
+
+from .config import Config
+from .models import Action, Assessment, Category, Observation, Signal, Verdict
+from .snare import Decision, Response, Snare
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Action",
+    "Assessment",
+    "Category",
+    "Config",
+    "Decision",
+    "Observation",
+    "Response",
+    "Signal",
+    "Snare",
+    "Verdict",
+    "__version__",
+]

drosera/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m drosera``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

drosera/canary/__init__.py

@@ -0,0 +1 @@
+"""Drosera canary subpackage."""

drosera/canary/mint.py

@@ -0,0 +1,281 @@
+"""Canary credentials: bait that works where there is no web server.
+
+An agent that has landed on a host or been pointed at a repository goes looking
+for secrets. ``.env``, ``credentials.json``, ``id_rsa``, a kubeconfig. Drosera
+seeds those files with credentials that are real-looking, completely inert, and
+uniquely identifiable.
+
+Detection happens on two independent channels, because each has a blind spot:
+
+* **Use** -- the credential names a host you control. When something tries to
+  authenticate with it, you learn the credential leaked, from where, and to
+  where. This is the high-fidelity channel: a hit is proof of exfiltration,
+  not an inference.
+* **Read** -- the file's access time changes. Cheap and immediate, but easily
+  defeated by ``noatime``/``relatime`` mounts and by any backup or indexer
+  that walks the tree. Treat it as a hint, never as proof.
+
+Every token is self-verifying via HMAC, so a hit can be attributed to the
+deployment that minted it without a shared database.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import hashlib
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from ..util import sign, token, verify
+
+REGISTRY_DEFAULT = ".drosera/canaries.json"
+PREFIX = "drs"
+
+
+@dataclass
+class Canary:
+    id: str
+    kind: str
+    value: str
+    path: str = ""
+    label: str = ""
+    listener: str = ""
+    created: float = field(default_factory=time.time)
+    mtime: float = 0.0
+    atime: float = 0.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def mint_token(secret: str, kind: str) -> tuple[str, str]:
+    """Return ``(canary_id, raw_token)``.
+
+    The id is embedded in the token so a hit identifies which planted file
+    leaked, and the HMAC tag proves the token is ours rather than a collision
+    with a real credential someone actually uses.
+    """
+    cid = token(12)
+    tag = sign(secret, f"{kind}:{cid}", 10)
+    return cid, f"{PREFIX}{cid}{tag}"
+
+
+def parse_token(secret: str, raw: str, kind: str = "") -> str | None:
+    """Extract and verify a canary id from an observed credential value."""
+    if not raw or not raw.startswith(PREFIX):
+        return None
+    rest = raw[len(PREFIX) :]
+    if len(rest) < 22:
+        return None
+    cid, tag = rest[:12], rest[12:22]
+    kinds = [kind] if kind else list(TEMPLATES)
+    for k in kinds:
+        if verify(secret, f"{k}:{cid}", tag, 10):
+            return cid
+    return None
+
+
+def _aws_style(raw: str) -> tuple[str, str]:
+    """AWS-shaped key pair carrying the token, so the file passes a glance."""
+    digest = hashlib.sha256(raw.encode()).digest()
+    key_id = "AKIA" + base64.b32encode(digest[:10]).decode().rstrip("=")[:16]
+    secret_key = base64.b64encode(digest).decode()[:40]
+    return key_id, secret_key
+
+
+def _fake_pem(raw: str) -> str:
+    """A PEM-shaped block that is deliberately not a usable key.
+
+    It is random base64, not a serialised key: it cannot authenticate anywhere,
+    so planting it creates no risk if it is stolen. The token is carried in the
+    surrounding comment.
+    """
+    blob = hashlib.sha512((raw + "pem").encode()).digest() * 12
+    b64 = base64.b64encode(blob).decode()
+    lines = [b64[i : i + 64] for i in range(0, len(b64), 64)]
+    return "-----BEGIN OPENSSH PRIVATE KEY-----\n" + "\n".join(lines) + "\n-----END OPENSSH PRIVATE KEY-----\n"
+
+
+# Each template renders a plausible file. ``{token}`` is the canary value and
+# ``{listener}`` is the host that will observe its use.
+TEMPLATES: dict[str, str] = {
+    "dotenv": """\
+# Environment configuration. Do not commit.
+NODE_ENV=production
+DATABASE_URL=postgresql://svc_reports:{token}@db-internal.{listener}:5432/reporting
+REDIS_URL=redis://cache-internal.{listener}:6379/0
+API_BASE_URL=https://api.{listener}
+SERVICE_API_KEY={token}
+JWT_SIGNING_KEY={token}
+SMTP_HOST=smtp.{listener}
+SMTP_USER=notifications@{listener}
+SMTP_PASSWORD={token}
+SENTRY_DSN=https://{token}@sentry.{listener}/4
+""",
+    "aws": """\
+[default]
+aws_access_key_id = {key_id}
+aws_secret_access_key = {secret_key}
+region = us-east-1
+
+[reporting]
+aws_access_key_id = {key_id}
+aws_secret_access_key = {secret_key}
+region = us-east-1
+""",
+    "credentials_json": """\
+{{
+  "type": "service_account",
+  "project_id": "reporting-prod",
+  "private_key_id": "{token}",
+  "client_email": "reporting-svc@reporting-prod.iam.{listener}",
+  "client_id": "{token}",
+  "token_uri": "https://oauth2.{listener}/token",
+  "api_key": "{token}"
+}}
+""",
+    "ssh_key": """\
+# deploy key for reporting-svc -- rotate quarterly (ref {token})
+{pem}""",
+    "kubeconfig": """\
+apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    server: https://k8s-api.{listener}:6443
+    insecure-skip-tls-verify: true
+  name: prod
+contexts:
+- context:
+    cluster: prod
+    user: deploy
+  name: prod
+current-context: prod
+users:
+- name: deploy
+  user:
+    token: {token}
+""",
+    "npmrc": """\
+//registry.{listener}/:_authToken={token}
+@internal:registry=https://registry.{listener}/
+always-auth=true
+""",
+    "appsettings": """\
+{{
+  "ConnectionStrings": {{
+    "Default": "Server=sql-internal.{listener};Database=Reporting;User Id=svc_reports;Password={token};"
+  }},
+  "Auth": {{
+    "ClientSecret": "{token}",
+    "Authority": "https://login.{listener}/"
+  }}
+}}
+""",
+    "pgpass": "db-internal.{listener}:5432:reporting:svc_reports:{token}\n",
+}
+
+DEFAULT_FILENAMES = {
+    "dotenv": ".env",
+    "aws": ".aws/credentials",
+    "credentials_json": "credentials.json",
+    "ssh_key": ".ssh/id_rsa",
+    "kubeconfig": ".kube/config",
+    "npmrc": ".npmrc",
+    "appsettings": "appsettings.Production.json",
+    "pgpass": ".pgpass",
+}
+
+
+def render(kind: str, secret: str, listener: str) -> tuple[Canary, str]:
+    if kind not in TEMPLATES:
+        raise KeyError(f"unknown canary kind {kind!r}; known: {', '.join(sorted(TEMPLATES))}")
+    cid, raw = mint_token(secret, kind)
+    key_id, secret_key = _aws_style(raw)
+    content = TEMPLATES[kind].format(
+        token=raw,
+        listener=listener,
+        key_id=key_id,
+        secret_key=secret_key,
+        pem=_fake_pem(raw),
+    )
+    value = key_id if kind == "aws" else raw
+    return Canary(id=cid, kind=kind, value=value, listener=listener), content
+
+
+def plant(
+    dest: str | os.PathLike[str],
+    kinds: list[str],
+    secret: str,
+    listener: str,
+    label: str = "",
+    registry: str | os.PathLike[str] = REGISTRY_DEFAULT,
+    overwrite: bool = False,
+) -> list[Canary]:
+    """Write canary files under ``dest`` and record them in the registry.
+
+    Refuses to overwrite an existing file unless asked. Planting a decoy on top
+    of a real ``.env`` would be a genuinely destructive accident, and the whole
+    point of the tool is to be safe to run against a live host.
+    """
+    root = Path(dest)
+    planted: list[Canary] = []
+    for kind in kinds:
+        canary, content = render(kind, secret, listener)
+        target = root / DEFAULT_FILENAMES[kind]
+        if target.exists() and not overwrite:
+            raise FileExistsError(
+                f"{target} already exists; refusing to overwrite. "
+                "Pass overwrite=True (or --force) only if you are certain it is not a real file."
+            )
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8", newline="\n")
+        # Best effort; Windows and some mounts will decline.
+        with contextlib.suppress(OSError):
+            os.chmod(target, 0o600)
+        st = target.stat()
+        canary.path = str(target.resolve())
+        canary.label = label
+        canary.mtime = st.st_mtime
+        canary.atime = st.st_atime
+        planted.append(canary)
+    save_registry(planted, registry, append=True)
+    return planted
+
+
+# -- registry ------------------------------------------------------------
+
+
+def load_registry(path: str | os.PathLike[str] = REGISTRY_DEFAULT) -> list[Canary]:
+    p = Path(path)
+    if not p.is_file():
+        return []
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+    return [Canary(**row) for row in data.get("canaries", []) if isinstance(row, dict)]
+
+
+def save_registry(
+    canaries: list[Canary],
+    path: str | os.PathLike[str] = REGISTRY_DEFAULT,
+    append: bool = False,
+) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    existing = load_registry(p) if append else []
+    by_id = {c.id: c for c in existing}
+    for c in canaries:
+        by_id[c.id] = c
+    payload = {"version": 1, "canaries": [c.to_dict() for c in by_id.values()]}
+    p.write_text(json.dumps(payload, indent=2), encoding="utf-8", newline="\n")
+
+
+def values(canaries: list[Canary]) -> set[str]:
+    """Credential strings to watch for in outbound or submitted data."""
+    return {c.value for c in canaries if c.value}

drosera/canary/watch.py

@@ -0,0 +1,217 @@
+"""Watch planted canaries for reads, and scan traffic for their use.
+
+Two detectors with very different strength, kept visibly separate so nobody
+confuses them:
+
+``FileWatcher``
+    Polls access/modification times of planted files. Immediate and dependency
+    free, but *soft*. Most Linux mounts use ``relatime``, so an access time
+    only advances once a day; ``noatime`` disables it entirely; backup agents,
+    antivirus and file indexers all touch files innocently. A hit here means
+    "worth looking at", never "confirmed".
+
+    Comparisons use integer nanosecond timestamps (``st_mtime_ns``) rather than
+    the float seconds a stat reports by default. Float seconds carry roughly
+    120ns of rounding error at current epoch values, which forces a tolerance --
+    and any tolerance big enough to absorb that noise is also big enough to miss
+    a fast edit. Integers need no tolerance at all.
+
+    File size is compared alongside mtime because on Windows a file timestamp
+    advances only on the system clock tick, about every 15.6ms. Two writes
+    inside one tick therefore share an mtime, and the edit is invisible to a
+    timestamp comparison. Size catches those. An edit that changes neither the
+    size nor the tick is genuinely undetectable this way -- one more reason
+    this channel is a hint and the credential-use channel is the evidence.
+
+``scan_for_canaries``
+    Looks for a planted credential appearing somewhere it should not -- a
+    request body, an outbound payload, a log line. This is *hard* evidence: the
+    value exists nowhere except inside bait, so its presence anywhere else
+    means the bait was read and the contents moved.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..util import stable_hash
+from .mint import Canary, load_registry, parse_token
+
+TOKEN_RE = re.compile(r"\bdrs[a-z0-9]{12}[a-f0-9]{10}\b")
+AWS_RE = re.compile(r"\bAKIA[A-Z2-7]{16}\b")
+
+
+# An access time must move by more than this to be reported. atime is a soft
+# signal on a coarse clock, so a full second of slack costs nothing.
+ATIME_TOLERANCE_NS = 1_000_000_000
+
+# How far ahead of the planting record an mtime must sit to count as "changed
+# while nobody was watching". Generous enough to ignore float rounding in the
+# registry, tight enough to still be meaningful.
+UNWATCHED_TOLERANCE_S = 1.0
+
+
+@dataclass
+class CanaryHit:
+    canary_id: str
+    kind: str
+    channel: str  # "file_read" | "file_modified" | "value_seen"
+    detail: str
+    path: str = ""
+    ts: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "ts": self.ts or time.time(),
+            "canary_id": self.canary_id,
+            "kind": self.kind,
+            "channel": self.channel,
+            "detail": self.detail,
+            "path": self.path,
+        }
+
+
+class FileWatcher:
+    """Polls planted files for access. Soft signal -- see module docstring."""
+
+    def __init__(self, registry: str | os.PathLike[str], quiet_atime: bool = True) -> None:
+        self.registry_path = registry
+        self.canaries: list[Canary] = load_registry(registry)
+        self.quiet_atime = quiet_atime
+        # (atime_ns, mtime_ns, size)
+        self._state: dict[str, tuple[int, int, int]] = {}
+        self._backlog: list[CanaryHit] = []
+        for c in self.canaries:
+            self._baseline(c)
+
+    def _baseline(self, canary: Canary) -> None:
+        """Record where a file stands as watching begins.
+
+        The baseline comes from a live stat rather than from the planting
+        record, so every later comparison is exact. Whatever happened between
+        planting and now is caught separately, by a coarse check that tolerates
+        the float rounding in the registry and surfaces on the first poll.
+        """
+        try:
+            st = Path(canary.path).stat() if canary.path else None
+        except OSError:
+            st = None
+        if st is None:
+            return
+        if canary.mtime and st.st_mtime > canary.mtime + UNWATCHED_TOLERANCE_S:
+            self._backlog.append(
+                CanaryHit(
+                    canary.id,
+                    canary.kind,
+                    "file_modified",
+                    f"{canary.path} was modified before watching began",
+                    canary.path,
+                    time.time(),
+                )
+            )
+        self._state[canary.id] = (st.st_atime_ns, st.st_mtime_ns, st.st_size)
+
+    def reload(self) -> None:
+        self.canaries = load_registry(self.registry_path)
+        for c in self.canaries:
+            if c.id not in self._state:
+                self._baseline(c)
+
+    def poll(self) -> list[CanaryHit]:
+        hits, self._backlog = self._backlog, []
+        now = time.time()
+        for c in self.canaries:
+            if not c.path:
+                continue
+            try:
+                st = Path(c.path).stat()
+            except OSError:
+                continue
+            prev = self._state.get(c.id)
+            if prev is None:
+                self._state[c.id] = (st.st_atime_ns, st.st_mtime_ns, st.st_size)
+                continue
+            prev_a, prev_m, prev_size = prev
+            changed = _describe_change(st.st_mtime_ns > prev_m, st.st_size != prev_size)
+            if changed:
+                hits.append(
+                    CanaryHit(c.id, c.kind, "file_modified", f"{changed} on {c.path}", c.path, now)
+                )
+            elif st.st_atime_ns > prev_a + ATIME_TOLERANCE_NS and not self.quiet_atime:
+                hits.append(
+                    CanaryHit(
+                        c.id,
+                        c.kind,
+                        "file_read",
+                        f"atime advanced on {c.path} (soft signal: relatime/backup agents also do this)",
+                        c.path,
+                        now,
+                    )
+                )
+            self._state[c.id] = (st.st_atime_ns, st.st_mtime_ns, st.st_size)
+        return hits
+
+    def run(
+        self,
+        on_hit: Callable[[CanaryHit], None],
+        interval: float = 5.0,
+        stop: Callable[[], bool] | None = None,
+    ) -> None:
+        while not (stop and stop()):
+            for hit in self.poll():
+                on_hit(hit)
+            time.sleep(interval)
+
+
+def _describe_change(mtime_moved: bool, size_moved: bool) -> str:
+    if mtime_moved and size_moved:
+        return "mtime and size changed"
+    if mtime_moved:
+        return "mtime advanced"
+    if size_moved:
+        return "size changed"
+    return ""
+
+
+def scan_for_canaries(text: str, secret: str, known: dict[str, Canary] | None = None) -> Iterator[CanaryHit]:
+    """Find planted credentials inside arbitrary text. Hard evidence.
+
+    Matches on shape first (cheap), then verifies the HMAC so an unrelated
+    string that happens to look like a token is not reported.
+    """
+    if not text:
+        return
+    seen: set[str] = set()
+    for m in TOKEN_RE.finditer(text):
+        raw = m.group(0)
+        if raw in seen:
+            continue
+        seen.add(raw)
+        cid = parse_token(secret, raw)
+        if not cid:
+            continue
+        kind = known[cid].kind if known and cid in known else "unknown"
+        yield CanaryHit(cid, kind, "value_seen", f"canary credential present in content: {raw[:8]}...", ts=time.time())
+    for m in AWS_RE.finditer(text):
+        raw = m.group(0)
+        if raw in seen or not known:
+            continue
+        seen.add(raw)
+        for c in known.values():
+            if c.value == raw:
+                yield CanaryHit(c.id, c.kind, "value_seen", f"canary access key present in content: {raw}", ts=time.time())
+                break
+
+
+def index(canaries: list[Canary]) -> dict[str, Canary]:
+    return {c.id: c for c in canaries}
+
+
+def correlation_key(remote_addr: str, salt: str = "") -> str:
+    """Stable key for tying a canary hit back to a session, without storing IPs."""
+    return stable_hash(salt, remote_addr)