firstwatch 0.1.0__py3-none-any.whl

firstwatch/__init__.py

@@ -0,0 +1,51 @@
+"""firstwatch: first line of defence for AI agents.
+
+    from firstwatch import scan, watch
+
+    scan(page_html)                  # {"level": "clean"|"note"|"stop", "findings": [...]}
+    watch(page_html, url=url)        # scans, saves a capture on a stop, returns the result + "saved"
+
+Same rules and capture format as the Node package (https://github.com/dave8172/firstwatch).
+"""
+
+from ._rules import RULES_VERSION
+from .capture import SPEC, VERSION, build, capture_dir, to_otlp, validate, write_capture, write_note
+from .redact import redact
+from .scan import scan
+
+__version__ = VERSION
+__all__ = ["scan", "watch", "build", "validate", "write_capture", "write_note", "to_otlp", "redact", "capture_dir", "SPEC", "RULES_VERSION", "__version__"]
+
+
+def watch(text, *, url=None, file=None, tool=None, kind=None, task=None, steps=None, session_id=None, agent_name=None, dir=None, raw=None):
+    """Scan one piece of outside content and record what it finds.
+
+    A stop is saved as a capture folder, a note as one line in notes.jsonl.
+    Returns the scan result plus "saved" (the folder or notes file, or None when clean).
+    Your code decides what to do next; on a stop, don't pass the content on as instructions.
+    """
+    result = scan(text)
+    result["saved"] = None
+    if result["level"] == "clean":
+        return result
+    from .capture import primary
+
+    top = primary(result["findings"])
+    repro = [f"Fetch {url} as raw HTML (no JavaScript)." if url else f"Open {file}." if file else "Feed the same content to the agent."]
+    repro.append(f'Find the text: "{top["excerpt"][:160]}"')
+    rec = build({
+        "level": result["level"],
+        "findings": result["findings"],
+        "source": {"kind": kind or ("web" if url else "file" if file else "tool" if tool else "other"), "url": url, "file": file, "tool": tool, "where": top["where"]},
+        "payload": {"text": top["excerpt"], "hidden": top["hidden"], "hidden_how": top["hidden_how"]},
+        "caught_by": "scanner",
+        "outcome": "blocked" if result["level"] == "stop" else "unknown",
+        "trace": {"task": task, "steps": steps or []},
+        "repro": repro,
+        "context": {"session_id": session_id, "agent_name": agent_name},
+    })
+    if result["level"] == "stop":
+        result["saved"] = write_capture(rec, dir=dir, raw=raw if raw is not None else text, raw_kind="html" if "<" in (raw or text) else "text")
+    else:
+        result["saved"] = write_note(rec, dir=dir)
+    return result

firstwatch/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

firstwatch/_rules.py

@@ -0,0 +1,37 @@
+"""Loads the shared detection rules (rules.json, the same file the Node package uses)."""
+
+import json
+import re
+from importlib import resources
+
+_data = json.loads(resources.files("firstwatch").joinpath("rules.json").read_text(encoding="utf-8"))
+
+
+def _rx(p):
+    # re.ASCII keeps \w and \b the same as JavaScript regexes without the u flag.
+    flags = re.ASCII
+    if "i" in p["flags"]:
+        flags |= re.IGNORECASE
+    return re.compile(p["source"], flags)
+
+
+RULES_VERSION = _data["version"]
+ATLAS = _data["atlas"]
+OWASP = _data["owasp"]
+AGENT_RE = _rx(_data["agent"])
+HIDDEN_STYLE = [(_rx(h), h["label"]) for h in _data["hidden_style"]]
+DISCUSSION_RE = _rx(_data["discussion"])
+DISCUSSION_MIN = _data["discussion"]["min"]
+PRIORITY = _data["priority"]
+BUILTIN = {b["id"]: b for b in _data["builtin"]}
+
+RULES = []
+for _r in _data["rules"]:
+    _rule = dict(_r)
+    if "pattern" in _r:
+        _rule["re"] = _rx(_r["pattern"])
+    else:
+        _rule["agent_re"] = _rx(_r["agent"])
+        _rule["imperative_re"] = _rx(_r["imperative"])
+        _rule["danger_re"] = _rx(_r["danger"])
+    RULES.append(_rule)

firstwatch/capture.py

@@ -0,0 +1,262 @@
+"""Build, check and write capture records (format: SPEC.md, firstwatch/0.1). Mirrors src/capture.js."""
+
+import json
+import os
+import re
+import secrets
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+from ._rules import ATLAS, OWASP, PRIORITY
+from .redact import redact, redact_deep
+
+SPEC = "firstwatch/0.1"
+VERSION = "0.1.0"
+LEVELS = ["stop", "note"]
+OUTCOMES = ["blocked", "followed", "partial", "unknown"]
+CAUGHT_BY = ["hook", "agent", "scanner", "owner"]
+KINDS = ["web", "file", "command", "tool", "search", "message", "email", "other"]
+MAX_EVIDENCE = 2_000_000
+_TIME = re.compile(r"^\d{4}-\d\d-\d\dT\d\d:\d\d(:\d\d(\.\d+)?)?(Z|[+-]\d\d:\d\d)$")
+
+
+def primary(findings):
+    """Most serious first: what the attack does, then how it hides."""
+    def rank(f):
+        i = PRIORITY.index(f["rule"]) + 1 if f.get("rule") in PRIORITY else 50
+        return (0 if f.get("level") == "stop" else 100) + i
+    return sorted(findings, key=rank)[0] if findings else None
+
+
+def capture_dir(cwd=None):
+    return Path(os.environ.get("FIRSTWATCH_DIR") or Path(cwd or os.getcwd()) / "security-captures").resolve()
+
+
+def iso_local(d=None):
+    """ISO 8601 in local time with the UTC offset, e.g. 2026-10-29T14:05:00.123+05:30."""
+    return (d or datetime.now()).astimezone().isoformat(timespec="milliseconds")
+
+
+def _slug(s):
+    s = re.sub(r"^www\.", "", str(s or "unknown").lower())
+    return re.sub(r"[^a-z0-9]+", "-", s).strip("-")[:40] or "unknown"
+
+
+def _host(url):
+    try:
+        return urlparse(url).hostname if url else None
+    except ValueError:
+        return None
+
+
+def validate(rec):
+    """Every problem at once, not the first. Returns a list of strings (empty = valid)."""
+    if not isinstance(rec, dict):
+        return ["record must be an object"]
+    p = []
+
+    def need(cond, msg):
+        if not cond:
+            p.append(msg)
+
+    src, pay = rec.get("source") or {}, rec.get("payload") or {}
+    need(rec.get("spec") == SPEC, f'spec must be "{SPEC}"')
+    need(isinstance(rec.get("id"), str) and rec["id"], "id is required")
+    need(isinstance(rec.get("time"), str) and _TIME.match(rec["time"]), "time must be ISO 8601 with a UTC offset")
+    need(rec.get("level") in LEVELS, f"level must be one of {', '.join(LEVELS)}")
+    need(isinstance(rec.get("summary"), str) and rec["summary"].strip(), "summary is required")
+    need(src.get("kind") in KINDS, f"source.kind must be one of {', '.join(KINDS)}")
+    need(isinstance(pay.get("text"), str) and pay["text"], "payload.text (the exact text) is required")
+    need(isinstance(pay.get("hidden"), bool), "payload.hidden must be true or false")
+    need(isinstance(rec.get("findings"), list), "findings must be a list")
+    need(rec.get("outcome") in OUTCOMES, f"outcome must be one of {', '.join(OUTCOMES)}")
+    need(rec.get("caught_by") in CAUGHT_BY, f"caught_by must be one of {', '.join(CAUGHT_BY)}")
+    need(isinstance(rec.get("repro"), list), "repro must be a list of steps")
+    return p
+
+
+def build(data):
+    """Turn partial input (from a hook, an agent or your code) into a full record. Redacts as it goes."""
+    now = datetime.now(timezone.utc)
+    findings = data.get("findings") or []
+    top = primary(findings) or {}
+    source = data.get("source") or {}
+    payload_in = data.get("payload") or {}
+    url = source.get("url")
+    text, n1 = redact(payload_in.get("text") or top.get("excerpt") or "", keep_emails=True)
+    trace, n2 = redact_deep(data.get("trace") or {})
+    intent = data.get("intent") or top.get("what") or ""
+    hidden = payload_in.get("hidden", bool(top.get("hidden")))
+    where = f" on {_host(url)}" if url else (f" in {os.path.basename(source['file'])}" if source.get("file") else "")
+    rec = {
+        "spec": SPEC,
+        "id": f"fw_{now.strftime('%Y%m%dT%H%M%S')}_{secrets.token_hex(3)}",
+        "time": data.get("time") or iso_local(),
+        "level": data.get("level") or ("stop" if any(f.get("level") == "stop" for f in findings) else "note"),
+        "summary": data.get("summary") or f"{'Hidden text' if hidden else 'Text'}{where}: {intent or 'targets AI agents'}",
+        "source": {
+            "kind": source.get("kind") or ("web" if url else "other"),
+            "url": url,
+            "tool": source.get("tool"),
+            "where": source.get("where") or top.get("where"),
+            "file": source.get("file"),
+        },
+        "payload": {"text": text, "hidden": hidden, "hidden_how": payload_in.get("hidden_how", top.get("hidden_how", []))},
+        "findings": findings,
+        "intent": intent,
+        "outcome": data.get("outcome") or "unknown",
+        "caught_by": data.get("caught_by") or "agent",
+        "trace": trace,
+        "repro": data.get("repro") or [],
+        "evidence": [],
+        "redactions": n1 + n2,
+    }
+    if data.get("notes"):
+        rec["notes"] = redact(data["notes"])[0]
+    rec["attributes"] = _attributes(rec, data.get("context") or {})
+    return rec
+
+
+def _attributes(rec, ctx):
+    """Flat attributes: OpenTelemetry names where a convention exists, firstwatch.* where none does."""
+    def uniq(xs):
+        return list(dict.fromkeys(xs))
+
+    a = {
+        "event.name": "firstwatch.capture",
+        "firstwatch.spec": SPEC,
+        "firstwatch.capture.id": rec["id"],
+        "firstwatch.level": rec["level"],
+        "firstwatch.outcome": rec["outcome"],
+        "firstwatch.caught_by": rec["caught_by"],
+        "firstwatch.hidden": rec["payload"]["hidden"],
+        "firstwatch.rules": uniq(f["rule"] for f in rec["findings"]),
+        "firstwatch.atlas.techniques": uniq(t for f in rec["findings"] for t in f.get("atlas", [])),
+        "firstwatch.owasp.ids": uniq(t for f in rec["findings"] for t in f.get("owasp", [])),
+    }
+    if rec["source"]["url"]:
+        a["url.full"] = rec["source"]["url"]
+        if _host(rec["source"]["url"]):
+            a["server.address"] = _host(rec["source"]["url"])
+    if ctx.get("session_id"):
+        a["gen_ai.conversation.id"] = ctx["session_id"]
+    if rec["source"]["tool"]:
+        a["gen_ai.operation.name"] = "execute_tool"
+        a["gen_ai.tool.name"] = rec["source"]["tool"]
+    if ctx.get("tool_use_id"):
+        a["gen_ai.tool.call.id"] = ctx["tool_use_id"]
+    if ctx.get("agent_name"):
+        a["gen_ai.agent.name"] = ctx["agent_name"]
+    return a
+
+
+def _readme(rec):
+    s, p = rec["source"], rec["payload"]
+    via = f" (via {s['tool']})" if s.get("tool") else ""
+    lines = [
+        f"# {rec['level'].upper()}: {rec['summary']}",
+        "",
+        f"- **Time:** {rec['time']}",
+        f"- **Source:** {s.get('url') or s.get('file') or s['kind']}{via}",
+        f"- **Where:** {s.get('where') or 'not recorded'}",
+        f"- **Hidden from people:** {('yes (' + (', '.join(p['hidden_how']) or 'how not recorded') + ')') if p['hidden'] else 'no'}",
+        f"- **What it tried:** {rec['intent'] or 'not recorded'}",
+        f"- **Outcome:** {rec['outcome']} · **caught by:** {rec['caught_by']}",
+        "",
+        "## Exact text",
+        "",
+        "```text",
+        p["text"].replace("```", "'''"),
+        "```",
+        "",
+    ]
+    if rec["findings"]:
+        lines += ["## Findings", "", "| Rule | Level | Where | ATLAS | OWASP |", "|---|---|---|---|---|"]
+        for f in rec["findings"]:
+            atlas = "; ".join(f"{t} {ATLAS.get(t, '')}".strip() for t in f.get("atlas", []))
+            owasp = "; ".join(f"{t} {OWASP.get(t, '')}".strip() for t in f.get("owasp", []))
+            lines.append(f"| {f['rule']} | {f['level']} | {f.get('where') or ''} | {atlas} | {owasp} |")
+        lines.append("")
+    if rec["repro"]:
+        lines += ["## Reproduce", ""] + [f"{i + 1}. {x}" for i, x in enumerate(rec["repro"])] + [""]
+    steps = (rec.get("trace") or {}).get("steps") or []
+    if steps:
+        lines += ["## Trace", ""]
+        if rec["trace"].get("task"):
+            lines += [f"Task: {rec['trace']['task']}", ""]
+        lines += [f"{i + 1}. `{x.get('tool')}` {x.get('summary') or ''}".strip() for i, x in enumerate(steps)] + [""]
+    if rec["evidence"]:
+        lines += ["## Evidence", ""] + [f"- {e}" for e in rec["evidence"]] + [""]
+    if rec.get("notes"):
+        lines += ["## Notes", "", rec["notes"], ""]
+    lines += ["---", "", f"Recorded by firstwatch {VERSION}. {rec['redactions']} value(s) masked before saving. Raw page source is stored as .txt so it never opens in a browser by mistake. Keep this folder private unless you choose to share it.", ""]
+    return "\n".join(lines)
+
+
+def _append(path, obj):
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(obj, ensure_ascii=False) + "\n")
+
+
+def write_capture(rec, dir=None, raw=None, raw_kind="html"):
+    """Write a stop capture as a folder. Returns the folder path."""
+    problems = validate(rec)
+    if problems:
+        raise ValueError("invalid capture:\n- " + "\n- ".join(problems))
+    d = Path(dir) if dir else capture_dir()
+    where = _slug(_host(rec["source"].get("url")) or (rec["source"].get("file") and os.path.basename(rec["source"]["file"])) or rec["source"].get("tool") or rec["source"]["kind"])
+    name = _slug((primary(rec["findings"]) or {}).get("rule") or "capture")
+    folder = d / f"{rec['time'][:10]}-{where}-{name}"
+    n = 2
+    while folder.exists():
+        folder = d / f"{rec['time'][:10]}-{where}-{name}-{n}"
+        n += 1
+    folder.mkdir(parents=True)
+    if raw:
+        file = "raw.html.txt" if raw_kind == "html" else "raw.txt"
+        masked, count = redact(raw[:MAX_EVIDENCE], keep_emails=True)
+        (folder / file).write_text(masked, encoding="utf-8")
+        rec["evidence"].append(file)
+        rec["redactions"] += count
+    (folder / "capture.json").write_text(json.dumps(rec, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (folder / "README.md").write_text(_readme(rec), encoding="utf-8")
+    _append(d / "index.jsonl", {"time": rec["time"], "level": rec["level"], "id": rec["id"], "folder": str(folder), "summary": rec["summary"]})
+    return str(folder)
+
+
+def write_note(rec, dir=None):
+    """A note is one line in notes.jsonl, not a folder."""
+    d = Path(dir) if dir else capture_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    _append(d / "notes.jsonl", {"time": rec["time"], "level": "note", "id": rec["id"], "source": rec["source"], "rules": [f["rule"] for f in rec["findings"]], "excerpt": rec["payload"]["text"][:300], "hidden_how": rec["payload"]["hidden_how"]})
+    return str(d / "notes.jsonl")
+
+
+def to_otlp(rec):
+    """One OTLP/JSON log record, ready to POST to a collector's /v1/logs. No network here."""
+    def value(v):
+        if isinstance(v, list):
+            return {"arrayValue": {"values": [value(x) for x in v]}}
+        if isinstance(v, bool):
+            return {"boolValue": v}
+        if isinstance(v, (int, float)):
+            return {"doubleValue": v}
+        return {"stringValue": str(v)}
+
+    t = datetime.fromisoformat(rec["time"].replace("Z", "+00:00"))
+    stop = rec["level"] == "stop"
+    return {"resourceLogs": [{
+        "resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "firstwatch"}}]},
+        "scopeLogs": [{
+            "scope": {"name": "firstwatch", "version": VERSION},
+            "logRecords": [{
+                "timeUnixNano": str(int(t.timestamp() * 1000) * 1_000_000),
+                "severityNumber": 13 if stop else 9,
+                "severityText": "WARN" if stop else "INFO",
+                "eventName": "firstwatch.capture",
+                "body": {"stringValue": rec["summary"]},
+                "attributes": [{"key": k, "value": value(v)} for k, v in (rec.get("attributes") or {}).items()],
+            }],
+        }],
+    }]}

firstwatch/cli.py

@@ -0,0 +1,116 @@
+"""firstwatch command line (Python). Same commands as the Node CLI, minus the Claude Code hook."""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+from . import VERSION, build, capture_dir, scan, to_otlp, validate, write_capture, write_note
+
+HELP = f"""firstwatch {VERSION}: watch, record and stop attacks aimed at AI agents
+
+  firstwatch scan [file]                 scan a file (or stdin) and print findings as JSON
+  firstwatch capture                     read a capture as JSON on stdin, check it, save it
+  firstwatch list                        list saved captures
+  firstwatch validate <capture.json>     check a capture against the format
+  firstwatch export otlp <capture.json>  print it as an OpenTelemetry (OTLP/JSON) log record
+  firstwatch clear [--session <id>]      lift the approval gate for one session, or all
+
+Captures go to ./security-captures, or FIRSTWATCH_DIR if set.
+The Claude Code hook ships in the Node package: npx firstwatch hook claude-code"""
+
+
+def _fail(msg):
+    sys.stderr.write(f"firstwatch: {msg}\n")
+    sys.exit(1)
+
+
+def _print(v):
+    sys.stdout.write((v if isinstance(v, str) else json.dumps(v, indent=2, ensure_ascii=False)) + "\n")
+
+
+def _read(path):
+    return Path(path).read_text(encoding="utf-8")
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    cmd = args.pop(0) if args else None
+    if cmd in (None, "-h", "--help", "help"):
+        return _print(HELP)
+    if cmd in ("-v", "--version"):
+        return _print(VERSION)
+
+    if cmd == "scan":
+        text = _read(args[0]) if args and args[0] != "-" else sys.stdin.read()
+        return _print(scan(text))
+
+    if cmd == "capture":
+        try:
+            data = json.loads(sys.stdin.read())
+        except ValueError as e:
+            _fail(f"stdin must be JSON: {e}")
+        text = (data.get("payload") or {}).get("text") or data.get("text")
+        if not text:
+            _fail("payload.text (the exact text of the attack) is required")
+        data["payload"] = {"hidden": False, "hidden_how": [], **(data.get("payload") or {}), "text": text}
+        found = scan(text)["findings"]
+        data["findings"] = (data.get("findings") or []) + found
+        data["level"] = data.get("level") or ("stop" if any(f["level"] == "stop" for f in found) else "note")
+        rec = build(data)
+        problems = validate(rec)
+        if problems:
+            _fail("capture is incomplete:\n- " + "\n- ".join(problems))
+        raw_file = data.get("raw_file")
+        raw = _read(raw_file) if raw_file and os.path.exists(raw_file) else None
+        if rec["level"] == "stop":
+            where = write_capture(rec, raw=raw, raw_kind="html" if re.search(r"\.html?$", raw_file or "", re.I) else "text")
+        else:
+            where = write_note(rec)
+        return _print({"level": rec["level"], "saved": where, "findings": len(rec["findings"])})
+
+    if cmd == "list":
+        f = capture_dir() / "index.jsonl"
+        if not f.exists():
+            return _print("No captures yet.")
+        for line in f.read_text(encoding="utf-8").strip().splitlines():
+            try:
+                r = json.loads(line)
+            except ValueError:
+                continue
+            _print(f"{r['time']}  {r['level'].upper()}  {r['summary']}\n    {r['folder']}")
+        return None
+
+    if cmd == "validate":
+        if not args:
+            _fail("usage: firstwatch validate <capture.json>")
+        problems = validate(json.loads(_read(args[0])))
+        if problems:
+            _fail("not valid:\n- " + "\n- ".join(problems))
+        return _print("valid")
+
+    if cmd == "export":
+        if len(args) < 2 or args[0] != "otlp":
+            _fail("usage: firstwatch export otlp <capture.json>")
+        return _print(to_otlp(json.loads(_read(args[1]))))
+
+    if cmd == "clear":
+        d = capture_dir() / ".sessions"
+        if not d.exists():
+            return _print("No gated sessions.")
+        if "--session" in args:
+            sid = args[args.index("--session") + 1]
+            files = [d / (re.sub(r"[^a-z0-9]+", "-", sid.lower()) + ".json")]
+        else:
+            files = list(d.iterdir())
+        for f in files:
+            f.unlink(missing_ok=True)
+        return _print("Lifted the gate for " + (f"session {sid}" if "--session" in args else "all sessions") + ".")
+
+    _fail(f'unknown command "{cmd}"\n\n{HELP}')
+    return None
+
+
+if __name__ == "__main__":
+    main()

firstwatch/redact.py

@@ -0,0 +1,69 @@
+"""Mask secrets before anything is written to disk. Emails are masked too unless the
+caller keeps them (an attacker's address in the payload is evidence). Mirrors src/redact.js."""
+
+import re
+
+_A = re.ASCII
+SECRETS = [
+    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----"),
+    re.compile(r"\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}", _A),
+    re.compile(r"\b(?:ghp|gho|ghs|ghu|ghr)_[A-Za-z0-9]{30,}\b", _A),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{40,}\b", _A),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b", _A),
+    re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}", _A),
+    re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b", _A),
+    re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}", _A),
+    re.compile(r"\b(?:hf|npm|glpat|pypi)[-_][A-Za-z0-9_-]{20,}", _A),
+]
+BEARER = re.compile(r"\b(Bearer|Basic)\s+[A-Za-z0-9._~+/-]{16,}=*", _A)
+ASSIGNED = re.compile(r"\b([\w-]*(?:api[_-]?key|token|secret|passw(?:or)?d|pwd|auth)[\w-]*)([\"']?\s*[:=]\s*[\"']?)([^\s\"',;]{8,})", re.I | _A)
+EMAIL = re.compile(r"\b[\w.+-]+@[\w-]+(?:\.[\w-]+)+\b", _A)
+
+
+def redact(text, keep_emails=False):
+    """Return (masked_text, count)."""
+    if not isinstance(text, str):
+        return text, 0
+    count = 0
+
+    def sub(rx, repl, s):
+        nonlocal count
+        out, n = rx.subn(repl, s)
+        count += n
+        return out
+
+    out = text
+    for rx in SECRETS:
+        out = sub(rx, "[REDACTED:secret]", out)
+    out = sub(BEARER, lambda m: f"{m.group(1)} [REDACTED:secret]", out)
+
+    def assigned(m):
+        nonlocal count
+        if m.group(3).startswith("[REDACTED"):
+            return m.group(0)
+        count += 1
+        return f"{m.group(1)}{m.group(2)}[REDACTED:secret]"
+
+    out = ASSIGNED.sub(assigned, out)
+    if not keep_emails:
+        out = sub(EMAIL, "[REDACTED:email]", out)
+    return out, count
+
+
+def redact_deep(value, keep_emails=False):
+    """Redact every string inside a JSON-like value. Returns (value, count)."""
+    total = 0
+
+    def walk(v):
+        nonlocal total
+        if isinstance(v, str):
+            out, n = redact(v, keep_emails)
+            total += n
+            return out
+        if isinstance(v, list):
+            return [walk(x) for x in v]
+        if isinstance(v, dict):
+            return {k: walk(x) for k, x in v.items()}
+        return v
+
+    return walk(value), total

firstwatch/rules.json

@@ -0,0 +1,289 @@
+{
+  "version": "0.1.0",
+  "_about": "firstwatch detection rules. Shared by the Node and Python packages; edit here only. Patterns use the common subset of JavaScript and Python regex syntax. Levels: visible = when people can see the text (null = only when hidden or addressed to an AI), hidden = when the text is hidden from people.",
+  "atlas": {
+    "AML.T0051.001": "LLM Prompt Injection: Indirect",
+    "AML.T0054": "LLM Jailbreak",
+    "AML.T0057": "LLM Data Leakage",
+    "AML.T0068": "LLM Prompt Obfuscation",
+    "AML.T0081": "Modify AI Agent Configuration",
+    "AML.T0086": "Exfiltration via AI Agent Tool Invocation",
+    "AML.T0100": "AI Agent Clickbait"
+  },
+  "owasp": {
+    "LLM01:2025": "Prompt Injection",
+    "LLM02:2025": "Sensitive Information Disclosure",
+    "LLM06:2025": "Excessive Agency",
+    "LLM07:2025": "System Prompt Leakage"
+  },
+  "agent": {
+    "source": "(?:\\b(?:ai|llms?|gpt|claude|gemini|chatgpt|copilot)\\b|\\blanguage models?\\b|\\b(?:assistants?|chatbots?)\\b)",
+    "flags": "i"
+  },
+  "rules": [
+    {
+      "id": "override-instructions",
+      "what": "tells the agent to ignore or replace its instructions",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:ignore|disregard|forget|override|bypass)\\b[^.\\n]{0,40}?\\b(?:previous|prior|above|earlier|all|any|your|system|original|preceding)\\b[^.\\n]{0,20}?\\b(?:instructions?|prompts?|rules|directions|guidelines|directives|context|constraints)\\b",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "role-hijack",
+      "what": "tries to switch the agent into an unrestricted role",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0054"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ],
+      "pattern": {
+        "source": "\\byou are now (?:in )?(?:dan\\b|an? (?:unrestricted|unfiltered|jailbroken)|unrestricted|jailbroken|in developer mode)|\\b(?:enter|enable|activate) (?:dan|god|jailbreak) mode\\b|\\bact as dan\\b",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "new-instructions",
+      "what": "announces new instructions for the reader",
+      "visible": "note",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:new|updated|real|actual|true|secret|hidden|additional) (?:system )?(?:instructions?|directives?|orders|task)\\s*[:\\-]",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "conceal-from-user",
+      "what": "tells the agent to hide something from its user",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:do not|don'?t|never)\\s+(?:tell|inform|mention|reveal|show|alert|notify|let)\\b[^.\\n]{0,30}?\\b(?:the )?(?:user|human|owner|operator|anyone)\\b|\\bwithout (?:telling|informing|alerting|notifying|asking)\\b[^.\\n]{0,20}?\\b(?:the )?(?:user|human|owner|operator)\\b",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "exfiltrate-secrets",
+      "what": "asks for secrets to be sent to an outside address",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0086",
+        "AML.T0057"
+      ],
+      "owasp": [
+        "LLM02:2025",
+        "LLM06:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:send|e-?mail|post|upload|share|forward|transmit|exfiltrate|leak|paste|include|append|attach|submit)\\b[^\\n]{0,80}?(?:\\.env\\b|api[ _-]?keys?|access[ _-]?tokens?|auth(?:entication)?[ _-]?tokens?|secrets?|passwords?|credentials?|private[ _-]?keys?|ssh[ _-]?keys?|id_rsa|aws_[a-z_]+|session[ _-]?(?:tokens?|cookies?)|cookies|seed[ _-]?phrase|wallet)[^\\n]{0,80}?(?:[\\w.+-]+@[\\w-]+\\.[\\w.]+|https?:\\/\\/\\S+|\\bto (?:this|the following|our|my) (?:address|url|endpoint|webhook|server|email)|\\bin (?:your|the) (?:reply|response|answer|output))|(?:\\.env\\b|api[ _-]?keys?|access[ _-]?tokens?|auth(?:entication)?[ _-]?tokens?|secrets?|passwords?|credentials?|private[ _-]?keys?|ssh[ _-]?keys?|id_rsa|aws_[a-z_]+|session[ _-]?(?:tokens?|cookies?)|cookies|seed[ _-]?phrase|wallet)[^\\n]{0,40}?\\b(?:send|e-?mail|post|upload|share|forward|transmit|exfiltrate|leak|paste|include|append|attach|submit)\\b[^\\n]{0,60}?(?:[\\w.+-]+@[\\w-]+\\.[\\w.]+|https?:\\/\\/\\S+|\\bto (?:this|the following|our|my) (?:address|url|endpoint|webhook|server|email)|\\bin (?:your|the) (?:reply|response|answer|output))",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "reveal-instructions",
+      "what": "asks the agent to reveal its instructions",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0057"
+      ],
+      "owasp": [
+        "LLM07:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:reveal|print|output|repeat|show|disclose|leak|share|tell me)\\b[^.\\n]{0,30}?\\b(?:(?:your|the) system prompt|your (?:instructions|initial prompt|hidden prompt|rules|configuration)|the (?:initial|hidden) prompt)\\b",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "remote-code",
+      "what": "pipes a download straight into a shell",
+      "visible": null,
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM06:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:curl|wget)\\b[^\\n|]{0,200}\\|\\s*(?:sudo\\s+)?(?:ba|z)?sh\\b|\\b(?:iex|invoke-expression)\\b[^\\n]{0,40}\\b(?:iwr|invoke-webrequest|downloadstring)\\b",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "image-exfiltration",
+      "what": "markdown image whose URL carries a data placeholder",
+      "visible": "stop",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0086"
+      ],
+      "owasp": [
+        "LLM02:2025"
+      ],
+      "pattern": {
+        "source": "!\\[[^\\]]*\\]\\(\\s*https?:\\/\\/[^)\\s]*[?&][\\w-]+=\\s*(?:\\{|\\[|<|%7b|\\$\\{)",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "modify-agent-config",
+      "what": "asks for changes to the agent's own setup",
+      "visible": "note",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0081"
+      ],
+      "owasp": [
+        "LLM06:2025"
+      ],
+      "pattern": {
+        "source": "\\b(?:edit|modify|update|append|write|add|overwrite|replace)\\b[^\\n]{0,100}?(?:\\bCLAUDE\\.md\\b|\\bAGENTS\\.md\\b|\\.cursorrules\\b|\\bsettings\\.json\\b|\\bMEMORY\\.md\\b|\\byour (?:memory|instructions|system prompt|hooks?|rules)\\b|\\.bashrc\\b|\\.zshrc\\b|\\bcrontab\\b|\\bauthorized_keys\\b)",
+        "flags": "i"
+      }
+    },
+    {
+      "id": "agent-imperative",
+      "what": "gives orders to AI agents",
+      "visible": "note",
+      "hidden": "stop",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ],
+      "agent": {
+        "source": "(?:\\b(?:ai|llms?|gpt|claude|gemini|chatgpt|copilot)\\b|\\blanguage models?\\b|\\b(?:assistants?|chatbots?)\\b)",
+        "flags": "i"
+      },
+      "imperative": {
+        "source": "(?:\\byou (?:must|should|need to|are required to|will|have to)\\b|\\bdo not\\b|\\bdon'?t\\b|\\bnever\\b|\\balways\\b|\\bimmediately\\b|\\bbefore (?:you )?(?:answer|respond|reply|continue|proceed)\\b|\\bmake sure\\b)",
+        "flags": "i"
+      },
+      "danger": {
+        "source": "\\b(?:send|e-?mail|forward|upload|transfer|wire|pay|buy|purchase|delete|wipe|reveal|disclose|grant|authori[sz]e|approve|sign ?up|subscribe|share (?:your|the|all))\\b",
+        "flags": "i"
+      }
+    }
+  ],
+  "hidden_style": [
+    {
+      "label": "css:display-none",
+      "source": "display\\s*:\\s*none",
+      "flags": "i"
+    },
+    {
+      "label": "css:visibility-hidden",
+      "source": "visibility\\s*:\\s*hidden",
+      "flags": "i"
+    },
+    {
+      "label": "css:tiny-text",
+      "source": "font-size\\s*:\\s*(?:0|0?\\.\\d+|1)(?:px|pt|em|rem)?\\s*(?:;|$|!)",
+      "flags": "i"
+    },
+    {
+      "label": "css:opacity-0",
+      "source": "opacity\\s*:\\s*0(?:\\.0+)?\\s*(?:;|$|!)",
+      "flags": "i"
+    },
+    {
+      "label": "css:off-screen",
+      "source": "(?:left|top|right|text-indent|margin-left)\\s*:\\s*-\\d{3,}",
+      "flags": "i"
+    },
+    {
+      "label": "css:white-or-transparent-text",
+      "source": "(?:^|[;\\s])color\\s*:\\s*(?:#fff\\b|#ffffff\\b|white\\b|transparent\\b|rgba\\([^)]*,\\s*0\\s*\\))",
+      "flags": "i"
+    },
+    {
+      "label": "css:zero-size",
+      "source": "(?:height|width)\\s*:\\s*0(?:px)?\\s*;[^\\\"']*overflow\\s*:\\s*hidden",
+      "flags": "i"
+    }
+  ],
+  "discussion": {
+    "_about": "A page that mentions these words this many times in visible text discusses attacks: its visible stops become notes. Hidden text still stops.",
+    "source": "prompt[ -]?injections?|jailbreak",
+    "flags": "gi",
+    "min": 3
+  },
+  "priority": [
+    "exfiltrate-secrets",
+    "image-exfiltration",
+    "remote-code",
+    "modify-agent-config",
+    "override-instructions",
+    "role-hijack",
+    "reveal-instructions",
+    "unicode-tag-smuggling",
+    "conceal-from-user",
+    "agent-imperative",
+    "new-instructions",
+    "hidden-agent-text",
+    "bidi-control"
+  ],
+  "builtin": [
+    {
+      "id": "unicode-tag-smuggling",
+      "what": "hides text in invisible Unicode tag characters",
+      "level": "stop",
+      "atlas": [
+        "AML.T0068",
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ]
+    },
+    {
+      "id": "bidi-control",
+      "what": "contains characters that reorder text on screen",
+      "level": "note",
+      "atlas": [
+        "AML.T0068"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ]
+    },
+    {
+      "id": "hidden-agent-text",
+      "what": "hidden text that mentions AI agents",
+      "level": "note",
+      "atlas": [
+        "AML.T0051.001"
+      ],
+      "owasp": [
+        "LLM01:2025"
+      ]
+    }
+  ]
+}

firstwatch/scan.py

@@ -0,0 +1,240 @@
+"""Scan text or HTML for attacks aimed at AI agents. Pure: text in, findings out.
+
+No network, no model. It splits the input into what people see and what they
+don't, then runs the rules on each part. Mirrors src/scan.js in the Node package.
+"""
+
+import base64
+import html
+import re
+
+from ._rules import AGENT_RE, BUILTIN, DISCUSSION_MIN, DISCUSSION_RE, HIDDEN_STYLE, RULES
+
+ZERO_WIDTH = re.compile("[\u200B-\u200D\u2060-\u2064\uFEFF\u00AD]")
+BIDI = re.compile("[\u202A-\u202E\u2066-\u2069]")
+TAG_CHARS = re.compile("[\U000e0000-\U000e007f]+")
+LEVELS = {"clean": 0, "note": 1, "stop": 2}
+_SPACE = re.compile(r"\s+")
+
+
+def decode_entities(s):
+    def num(m, base):
+        try:
+            return chr(int(m.group(1), base))
+        except (ValueError, OverflowError):
+            return ""
+
+    s = re.sub(r"&#x([0-9a-f]+);", lambda m: num(m, 16), s, flags=re.I)
+    s = re.sub(r"&#(\d+);", lambda m: num(m, 10), s)
+    for a, b in (("&nbsp;", " "), ("&quot;", '"'), ("&#39;", "'"), ("&apos;", "'"), ("&lt;", "<"), ("&gt;", ">"), ("&amp;", "&")):
+        s = s.replace(a, b)
+    return s
+
+
+def _strip_tags(s):
+    return _SPACE.sub(" ", decode_entities(re.sub(r"<[^>]*>", " ", s))).strip()
+
+
+def _inside(ranges, i):
+    return any(a <= i < b for a, b in ranges)
+
+
+def segments(text):
+    """Split input into segments: dicts with text, hidden, how, where, offset, quoted."""
+    out = []
+    for m in TAG_CHARS.finditer(text):
+        decoded = "".join(chr(ord(c) - 0xE0000) for c in m.group(0))
+        out.append({"text": decoded, "hidden": True, "how": ["unicode-tag-characters"], "where": "invisible characters", "offset": m.start()})
+    s = TAG_CHARS.sub("", text)
+    if not re.search(r"</?[a-z][\w-]*[^>]*>|<!--", s, re.I):
+        out.append({"text": s, "hidden": False, "how": [], "where": "text", "offset": 0})
+        return _with_base64(out, s)
+
+    lower = s.lower()
+    removed = []
+    for m in re.finditer(r"<!--([\s\S]*?)-->", s):
+        out.append({"text": m.group(1).strip(), "hidden": True, "how": ["html-comment"], "where": "HTML comment", "offset": m.start()})
+        removed.append((m.start(), m.end()))
+    for m in re.finditer(r"<(script|style|template)\b[^>]*>[\s\S]*?</\1>", s, re.I):
+        removed.append((m.start(), m.end()))
+
+    for m in re.finditer(r"<([a-z][\w-]*)\b([^>]*)>", s, re.I | re.ASCII):
+        tag, attrs = m.group(1).lower(), m.group(2)
+        how = []
+        style = re.search(r"\bstyle\s*=\s*(\"([^\"]*)\"|'([^']*)')", attrs, re.I)
+        if style:
+            value = style.group(2) if style.group(2) is not None else style.group(3)
+            how += [label for rx, label in HIDDEN_STYLE if rx.search(value)]
+        if re.search(r"(?:^|\s)hidden(?:\s|=|$)", attrs, re.I):
+            how.append("attr:hidden")
+        if re.search(r"aria-hidden\s*=\s*[\"']?true", attrs, re.I):
+            how.append("attr:aria-hidden")
+        if re.search(r"\bclass\s*=\s*[\"'][^\"']*\b(?:hidden|d-none|invisible)\b", attrs, re.I):
+            how.append("class:hidden")
+        for a in re.finditer(r"\b(alt|title|aria-label|content|data-[\w-]+)\s*=\s*(\"([^\"]*)\"|'([^']*)')", attrs, re.I | re.ASCII):
+            val = decode_entities(a.group(3) if a.group(3) is not None else a.group(4)).strip()
+            if len(val) > 15:
+                name = a.group(1).lower()
+                out.append({"text": val, "hidden": True, "how": [f"attribute:{name}"], "where": f"<{tag}> {name} attribute", "offset": m.start()})
+        if not how or re.fullmatch(r"br|img|input|meta|link|hr", tag):
+            continue
+        start = m.end()
+        close = lower.find(f"</{tag}", start)
+        end = min(len(s), start + 4000) if close == -1 else close
+        inner = _strip_tags(s[start:end])
+        if inner:
+            out.append({"text": inner, "hidden": True, "how": how, "where": f"hidden <{tag}>", "offset": m.start()})
+        removed.append((m.start(), end))
+
+    # Code blocks are quoted examples: a match there is a note, not a stop.
+    for m in re.finditer(r"<(pre|code)\b[^>]*>([\s\S]*?)</\1>", s, re.I):
+        if _inside(removed, m.start()):
+            continue
+        inner = _strip_tags(m.group(2))
+        if inner:
+            out.append({"text": inner, "hidden": False, "how": [], "where": f"<{m.group(1).lower()}> block", "offset": m.start(), "quoted": True})
+        removed.append((m.start(), m.end()))
+
+    visible, pos = [], 0
+    for a, b in sorted(removed):
+        if a > pos:
+            visible.append(s[pos:a] + " ")
+        pos = max(pos, b)
+    visible.append(s[pos:])
+    vis = _strip_tags("".join(visible))
+    if vis:
+        out.append({"text": vis, "hidden": False, "how": [], "where": "visible text", "offset": 0})
+    return _with_base64(out, s)
+
+
+def _with_base64(out, s):
+    for m in re.finditer(r"(?<![A-Za-z0-9+/=])[A-Za-z0-9+/]{40,}={0,2}(?![A-Za-z0-9+/=])", s):
+        blob = m.group(0).rstrip("=")
+        if len(blob) % 4 == 1:
+            blob = blob[:-1]
+        try:
+            decoded = base64.b64decode(blob + "=" * (-len(blob) % 4)).decode("utf-8", errors="replace")
+        except ValueError:
+            continue
+        printable = len(re.sub(r"[^\x20-\x7e\n\t]", "", decoded)) / max(len(decoded), 1)
+        if printable > 0.95 and re.search(r"[a-z]{3,} [a-z]{3,}", decoded, re.I):
+            out.append({"text": decoded, "hidden": True, "how": ["base64"], "where": "base64-encoded text", "offset": m.start()})
+    return out
+
+
+def _excerpt(text, index, length):
+    a = max(0, index - 80)
+    b = min(len(text), index + length + 80)
+    return ("…" if a > 0 else "") + text[a:b] + ("…" if b < len(text) else "")
+
+
+def _in_quotes(text, i):
+    """Is position i inside a quotation? Counts open quotes in the 300 characters before it."""
+    before = text[max(0, i - 300):i]
+    return before.count('"') % 2 == 1 or (before.count("“") + before.count("«")) > (before.count("”") + before.count("»"))
+
+
+def _level_for(rule, seg, text, index, near):
+    level = rule["hidden"] if seg["hidden"] else rule["visible"]
+    if level is None:
+        level = "stop" if AGENT_RE.search(near) else None
+    if not level:
+        return None
+    # A quoted example in visible text is someone talking about an attack, not making one.
+    if level == "stop" and not seg["hidden"] and (seg.get("quoted") or _in_quotes(text, index)):
+        level = "note"
+    return level
+
+
+def _finding(rule, level, seg, ex):
+    atlas = list(rule["atlas"])
+    if any(h in ("base64", "zero-width-characters") for h in seg["how"]) and "AML.T0068" not in atlas:
+        atlas.append("AML.T0068")
+    return {
+        "rule": rule["id"],
+        "what": rule["what"],
+        "level": level,
+        "hidden": bool(seg["hidden"]),
+        "hidden_how": seg["how"],
+        "where": seg["where"],
+        "offset": seg["offset"],
+        "excerpt": ex,
+        "atlas": atlas,
+        "owasp": list(rule["owasp"]),
+    }
+
+
+def scan(text):
+    """Scan a string. Returns {"level": "clean"|"note"|"stop", "findings": [...]}."""
+    if not isinstance(text, str) or not text:
+        return {"level": "clean", "findings": []}
+    findings, seen = [], set()
+    segs = segments(text)
+    if BIDI.search(text):
+        findings.append(_finding(BUILTIN["bidi-control"], "note", {"hidden": True, "how": ["bidi-control-characters"], "where": "text", "offset": 0}, "(bidirectional control characters present)"))
+
+    ai = next(r for r in RULES if r["id"] == "agent-imperative")
+    for seg in segs:
+        raw = seg["text"]
+        t = ZERO_WIDTH.sub("", raw)
+        how = list(seg["how"])
+        if t != raw:
+            how.append("zero-width-characters")
+        sf = dict(seg, how=how)
+        hit = False
+
+        if "unicode-tag-characters" in seg["how"]:
+            findings.append(_finding(BUILTIN["unicode-tag-smuggling"], "stop", sf, t[:240]))
+            hit = True
+
+        for rule in RULES:
+            if rule["id"] == "agent-imperative":
+                continue
+            m = rule["re"].search(t)
+            if not m:
+                continue
+            near = t[max(0, m.start() - 200):m.end() + 200]
+            level = _level_for(rule, sf, t, m.start(), near)
+            if not level:
+                continue
+            ex = _excerpt(t, m.start(), len(m.group(0)))
+            if (rule["id"] + ex) in seen:
+                continue
+            seen.add(rule["id"] + ex)
+            findings.append(_finding(rule, level, sf, ex))
+            hit = True
+
+        at = 0
+        for sentence in re.split(r"(?<=[.!?])\s+|\n+", t):
+            index = t.find(sentence, at)
+            at = index + len(sentence)
+            if not ai["agent_re"].search(sentence) or not ai["imperative_re"].search(sentence):
+                continue
+            level = "stop" if sf["hidden"] or ai["danger_re"].search(sentence) else "note"
+            if level == "stop" and not sf["hidden"] and (sf.get("quoted") or _in_quotes(t, index + 1)):
+                level = "note"
+            ex = sentence.strip()[:300]
+            if (ai["id"] + ex) in seen:
+                continue
+            seen.add(ai["id"] + ex)
+            findings.append(_finding(ai, level, sf, ex))
+            hit = True
+
+        # Hidden menus often name AI products; only a comment or invisible characters aimed at AI is worth a note.
+        if not hit and seg["hidden"] and AGENT_RE.search(t) and (seg["how"][:1] in (["html-comment"], ["unicode-tag-characters"])):
+            findings.append(_finding(BUILTIN["hidden-agent-text"], "note", sf, t[:240]))
+
+    # A page that talks about these attacks at length quotes them in visible text.
+    # Its visible examples become notes; anything hidden still stops.
+    visible = " ".join(x["text"] for x in segs if not x["hidden"])
+    if len(DISCUSSION_RE.findall(visible)) >= DISCUSSION_MIN:
+        for f in findings:
+            if f["level"] == "stop" and not f["hidden"]:
+                f["level"] = "note"
+                f["context"] = "page discusses attacks"
+
+    level = "clean"
+    for f in findings:
+        if LEVELS[f["level"]] > LEVELS[level]:
+            level = f["level"]
+    return {"level": level, "findings": findings}

firstwatch-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: firstwatch
+Version: 0.1.0
+Summary: First line of defence for AI agents: spots attacks hidden in pages, files and tool results, and records each one as evidence in an open, OpenTelemetry-ready format with MITRE ATLAS and OWASP IDs. No dependencies.
+Project-URL: Homepage, https://github.com/dave8172/firstwatch
+Project-URL: Documentation, https://github.com/dave8172/firstwatch/tree/main/docs
+Project-URL: Source, https://github.com/dave8172/firstwatch
+Project-URL: Issues, https://github.com/dave8172/firstwatch/issues
+Project-URL: Changelog, https://github.com/dave8172/firstwatch/blob/main/CHANGELOG.md
+Author: dave8172
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-security,ai-agents,guardrails,llm-security,mitre-atlas,opentelemetry,owasp,prompt-injection,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# firstwatch
+
+**First line of defence for AI agents.** Scans pages, files and tool results for attacks aimed at agents (in the text people see and the text they don't), and records each one as evidence in an open, OpenTelemetry-ready format with MITRE ATLAS and OWASP IDs.
+
+No dependencies. Python 3.9+.
+
+```bash
+pip install firstwatch
+```
+
+```python
+from firstwatch import scan, watch
+
+scan(page_html)
+# {"level": "stop", "findings": [{"rule": "exfiltrate-secrets", "hidden": True,
+#   "hidden_how": ["css:tiny-text"], "atlas": ["AML.T0086", ...], ...}]}
+
+result = watch(page_html, url=url, tool="fetch")   # scan + save a capture on a stop
+if result["level"] == "stop":
+    ...  # don't hand the page to the model as instructions; tell the user
+```
+
+Command line:
+
+```bash
+firstwatch scan page.html
+firstwatch list
+firstwatch export otlp security-captures/<folder>/capture.json
+```
+
+It catches instruction overrides, role hijacks, orders to hide things from the user, requests to send secrets out, requests to reveal the system prompt, `curl | sh` in hidden text, markdown image data leaks, edits to the agent's own setup, and orders aimed at AI assistants. It looks in HTML comments, CSS-hidden elements, attributes, invisible Unicode tag characters, zero-width characters and base64.
+
+The Node package (`npm install firstwatch`) uses the same rules and format, and adds Claude Code hooks that block actions after an attack.
+
+**Docs, examples and the capture format:** https://github.com/dave8172/firstwatch
+
+MIT licensed. Made by [@dave8172](https://x.com/dave8172).

firstwatch-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+firstwatch/__init__.py,sha256=4aA7kX_RUGucGeKGqpH2vvk-96AqKXWKQbK3LBWTKvg,2488
+firstwatch/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+firstwatch/_rules.py,sha256=qT3msZJf49VcW17Tf9I9ild8lvOQww9EdFlg6pUM1Ww,1112
+firstwatch/capture.py,sha256=d57H0_qwvK_grd4g3NzhMZ-7aY75qsxwlt1x8azZV-g,11711
+firstwatch/cli.py,sha256=cRNozfLPoxq4olaFGIm3xNOCzdvrrZ8_nbRTBHcB88I,4441
+firstwatch/redact.py,sha256=PmqQqN9UiHYx4-mcOoHVOIaXTERY5BqRZMrmzIzv1Mc,2363
+firstwatch/rules.json,sha256=Bb6AKqiX_sph0zlWXb9vjpPBl1KOhVmF-tJ-ZSXWA18,9953
+firstwatch/scan.py,sha256=V7lB6p0s_3ZswemM710kfLUNk66nLvldRX5XK6_M6so,10144
+firstwatch-0.1.0.dist-info/METADATA,sha256=2qjvTBT1cWFSo2_OIWM6tEclgUeI7F6xlZsVALUzrVQ,3042
+firstwatch-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+firstwatch-0.1.0.dist-info/entry_points.txt,sha256=1da0Y_MWNUPkkD450ZlM-cIGrEtjo4RC3iIM0CqR5tc,51
+firstwatch-0.1.0.dist-info/licenses/LICENSE,sha256=SaJIEtWVZ-SL5sXsd4HaAwLAUZrnZsMGZOiSK0kZt3I,1065
+firstwatch-0.1.0.dist-info/RECORD,,

firstwatch-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

firstwatch-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+firstwatch = firstwatch.cli:main

firstwatch-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dave8172
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.