PyPI - anonproxy - Versions diffs - 0.1.1__py3-none-any.whl - Mend

anonproxy 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

anonproxy/__init__.py +22 -0
anonproxy/__main__.py +4 -0
anonproxy/audit.py +195 -0
anonproxy/cli.py +365 -0
anonproxy/config.py +156 -0
anonproxy/detectors/__init__.py +145 -0
anonproxy/detectors/anonymizer_slm.py +119 -0
anonproxy/detectors/gliner2_detector.py +89 -0
anonproxy/detectors/gliner_detector.py +76 -0
anonproxy/detectors/llm_detector.py +219 -0
anonproxy/detectors/openai_pii_detector.py +82 -0
anonproxy/detectors/piiranha_detector.py +83 -0
anonproxy/detectors/regex_detector.py +190 -0
anonproxy/detectors/scope_detector.py +98 -0
anonproxy/engine.py +253 -0
anonproxy/profiles.py +228 -0
anonproxy/proxy/__init__.py +1 -0
anonproxy/proxy/app.py +296 -0
anonproxy/proxy/streaming.py +137 -0
anonproxy/proxy/transform.py +115 -0
anonproxy/restorer.py +197 -0
anonproxy/surrogates.py +279 -0
anonproxy/vault.py +165 -0
anonproxy/verify.py +273 -0
anonproxy/wizard.py +226 -0
anonproxy-0.1.1.dist-info/METADATA +544 -0
anonproxy-0.1.1.dist-info/RECORD +31 -0
anonproxy-0.1.1.dist-info/WHEEL +5 -0
anonproxy-0.1.1.dist-info/entry_points.txt +2 -0
anonproxy-0.1.1.dist-info/licenses/LICENSE +21 -0
anonproxy-0.1.1.dist-info/top_level.txt +1 -0

anonproxy/__init__.py ADDED Viewed

@@ -0,0 +1,22 @@
+"""
+Anonproxy — a reversible anonymization layer for sending pentest data to LLMs.
+A more reliable successor to the match/replace approach: deterministic
+format-preserving surrogates, a session-consistent vault, multi-pass detection
+(regex floor + optional local LLM + known-entity rescan), and — most importantly
+— a *tolerant, streaming-safe restorer* that puts the real values back even when
+the model mangles a surrogate (markdown, backticks, line wraps, case changes) or
+splits it across streaming chunks.
+Public API:
+    from anonproxy import Engine
+    eng = Engine(engagement="acme-2026")
+    safe = eng.anonymize(text)            # real -> surrogate
+    back = eng.deanonymize(safe)          # surrogate -> real (tolerant)
+"""
+from .engine import Engine
+from .config import Settings
+__all__ = ["Engine", "Settings"]
+__version__ = "0.1.0"

anonproxy/__main__.py ADDED Viewed

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

anonproxy/audit.py ADDED Viewed

@@ -0,0 +1,195 @@
+"""
+Audit dashboard — a self-contained page for reviewing what was anonymized.
+Served by the proxy at ``/audit``.  It shows the live ``original → surrogate``
+mapping for the current engagement, filterable by entity type, with counts, so
+you can verify coverage at a glance during an engagement and export the table
+for your evidence trail at close.
+Security: the page exposes the reverse lookup, so it is bound to the proxy's
+listen address (localhost by default — reach a VPS instance only over the SSH
+tunnel) and honours ``ANONPROXY_API_TOKEN`` if set.  Disable entirely with
+``ANONPROXY_AUDIT=false``.
+"""
+from __future__ import annotations
+import html
+import json
+def render_page(engagement: str, token_required: bool) -> str:
+    # token (if any) is read from the page URL ?token=... and forwarded as a
+    # header on the data fetch, so it never needs to be embedded server-side.
+    return _PAGE.replace("__ENGAGEMENT__", html.escape(engagement)) \
+                .replace("__TOKEN_REQUIRED__", json.dumps(token_required))
+_PAGE = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Anonproxy audit — __ENGAGEMENT__</title>
+<style>
+  :root { color-scheme: dark; }
+  body { font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+         margin: 0; background: #0d1117; color: #c9d1d9; }
+  header { padding: 16px 20px; border-bottom: 1px solid #21262d;
+           display: flex; gap: 20px; align-items: baseline; flex-wrap: wrap; }
+  h1 { font-size: 16px; margin: 0; color: #58a6ff; }
+  .eng { color: #8b949e; }
+  .toolbar { padding: 12px 20px; display: flex; gap: 10px; flex-wrap: wrap;
+             align-items: center; border-bottom: 1px solid #21262d; }
+  input, select, button { background: #161b22; color: #c9d1d9;
+            border: 1px solid #30363d; border-radius: 6px; padding: 6px 10px;
+            font: inherit; }
+  button { cursor: pointer; }
+  button:hover { border-color: #58a6ff; }
+  .stats { padding: 10px 20px; color: #8b949e; display: flex; gap: 16px;
+           flex-wrap: wrap; }
+  .pill { background: #161b22; border: 1px solid #30363d; border-radius: 999px;
+          padding: 2px 10px; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 8px 20px; border-bottom: 1px solid #21262d;
+           vertical-align: top; word-break: break-all; }
+  th { position: sticky; top: 0; background: #0d1117; color: #8b949e;
+       font-weight: 600; cursor: pointer; }
+  tr:hover td { background: #11161d; }
+  .type { color: #d2a8ff; }
+  .orig { color: #ff7b72; }
+  .surr { color: #7ee787; }
+  .muted { color: #6e7681; }
+  .err { color: #ff7b72; padding: 20px; }
+</style>
+</head>
+<body>
+<header>
+  <h1>🛡️ Anonproxy audit</h1>
+  <span class="eng">engagement: <b>__ENGAGEMENT__</b></span>
+  <span class="muted" id="updated"></span>
+</header>
+<div class="toolbar">
+  <input id="q" placeholder="filter (original / surrogate / type)" size="34">
+  <select id="type"><option value="">all types</option></select>
+  <button id="refresh">↻ refresh</button>
+  <button id="csv">⬇ export CSV</button>
+  <label class="muted"><input type="checkbox" id="auto"> auto-refresh 5s</label>
+</div>
+<div class="stats" id="stats"></div>
+<table>
+  <thead><tr>
+    <th data-k="entity_type">type</th>
+    <th data-k="original">original</th>
+    <th data-k="surrogate">surrogate</th>
+  </tr></thead>
+  <tbody id="rows"></tbody>
+</table>
+<div id="error" class="err"></div>
+<script>
+const TOKEN_REQUIRED = __TOKEN_REQUIRED__;
+// token via ?token= (legacy) or #token= (preferred — fragments are never sent
+// to the server, so they stay out of access logs; they do land in history
+// either way, so clear the URL after reading)
+const params = new URLSearchParams(location.search);
+let token = params.get("token") || "";
+if (!token && location.hash.startsWith("#token=")) {
+  try { token = decodeURIComponent(location.hash.slice("#token=".length)); }
+  catch { token = location.hash.slice("#token=".length); }
+}
+if (token) history.replaceState(null, "", location.pathname + location.search);
+let data = [], sortKey = "entity_type", sortAsc = true, timer = null;
+function headers() {
+  const h = {};
+  if (TOKEN_REQUIRED && token) h["X-Anonproxy-Token"] = token;
+  return h;
+}
+async function load() {
+  document.getElementById("error").textContent = "";
+  try {
+    const [ex, st] = await Promise.all([
+      fetch("/anonproxy/export", {headers: headers()}),
+      fetch("/anonproxy/stats", {headers: headers()}),
+    ]);
+    if (!ex.ok) throw new Error("export " + ex.status + (ex.status===401?" — add ?token=…":""));
+    data = (await ex.json()).mappings || [];
+    renderStats(await st.json());
+    populateTypes();
+    render();
+    document.getElementById("updated").textContent =
+      "updated " + new Date().toLocaleTimeString();
+  } catch (e) {
+    document.getElementById("error").textContent = "Error: " + e.message;
+  }
+}
+function renderStats(s) {
+  const el = document.getElementById("stats");
+  const parts = [`<span class="pill">total: <b>${s.total||0}</b></span>`];
+  // entity types can originate from LLM output parsed out of hostile client
+  // traffic — never interpolate them into innerHTML unescaped
+  for (const [k, v] of Object.entries(s.by_type || {}))
+    parts.push(`<span class="pill">${esc(k)}: ${v}</span>`);
+  for (const [k, v] of Object.entries(s.detector_failures || {}))
+    if (v) parts.push(`<span class="pill" style="border-color:#f85149;color:#ff7b72">⚠ ${esc(k)} failed ×${v}</span>`);
+  el.innerHTML = parts.join("");
+}
+function populateTypes() {
+  const sel = document.getElementById("type");
+  const cur = sel.value;
+  const types = [...new Set(data.map(d => d.entity_type))].sort();
+  sel.innerHTML = '<option value="">all types</option>' +
+    types.map(t => `<option ${t===cur?"selected":""}>${esc(t)}</option>`).join("");
+}
+function render() {
+  const q = document.getElementById("q").value.toLowerCase();
+  const t = document.getElementById("type").value;
+  let rows = data.filter(d =>
+    (!t || d.entity_type === t) &&
+    (!q || (d.original+d.surrogate+d.entity_type).toLowerCase().includes(q)));
+  rows.sort((a,b) => {
+    const x=(a[sortKey]||"").toString(), y=(b[sortKey]||"").toString();
+    return sortAsc ? x.localeCompare(y) : y.localeCompare(x);
+  });
+  document.getElementById("rows").innerHTML = rows.map(d => `<tr>
+    <td class="type">${esc(d.entity_type)}</td>
+    <td class="orig">${esc(d.original)}</td>
+    <td class="surr">${esc(d.surrogate)}</td></tr>`).join("") ||
+    '<tr><td colspan="3" class="muted">no mappings yet</td></tr>';
+}
+function esc(s){return (s||"").replace(/[&<>]/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;"}[c]));}
+function toCSV() {
+  const head = "entity_type,original,surrogate\n";
+  const body = data.map(d =>
+    [d.entity_type, d.original, d.surrogate]
+      .map(v => '"'+(v||"").replace(/"/g,'""')+'"').join(",")).join("\n");
+  const blob = new Blob([head+body], {type:"text/csv"});
+  const a = document.createElement("a");
+  a.href = URL.createObjectURL(blob);
+  a.download = "anonproxy-__ENGAGEMENT__.csv";
+  a.click();
+}
+document.getElementById("q").oninput = render;
+document.getElementById("type").onchange = render;
+document.getElementById("refresh").onclick = load;
+document.getElementById("csv").onclick = toCSV;
+document.getElementById("auto").onchange = e => {
+  clearInterval(timer);
+  if (e.target.checked) timer = setInterval(load, 5000);
+};
+document.querySelectorAll("th[data-k]").forEach(th => th.onclick = () => {
+  const k = th.dataset.k;
+  sortAsc = sortKey === k ? !sortAsc : true;
+  sortKey = k; render();
+});
+load();
+</script>
+</body>
+</html>"""

anonproxy/cli.py ADDED Viewed

@@ -0,0 +1,365 @@
+"""Command line entrypoint.
+    python -m anonproxy serve                 # start the proxy
+    python -m anonproxy anon  < file.txt      # anonymize stdin
+    python -m anonproxy deanon < file.txt     # restore stdin
+    python -m anonproxy stats                 # vault stats
+    python -m anonproxy export                # dump mappings as JSON
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+import time
+from dataclasses import asdict
+from pathlib import Path
+from .config import Settings
+from .engine import Engine
+def _load_dotenv(path: str = ".env") -> None:
+    """Load KEY=VALUE pairs without overriding real env vars.
+    Searched in order: ``path`` (the cwd convention), then the repo root
+    next to the installed package — so the CLI picks up your settings from
+    any working directory, and after moving/renaming the repo.
+    """
+    candidates = [Path(path)]
+    pkg_root_env = Path(__file__).resolve().parent.parent / ".env"
+    if pkg_root_env.resolve() != Path(path).resolve():
+        candidates.append(pkg_root_env)
+    for p in candidates:
+        if not p.exists():
+            continue
+        for line in p.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            os.environ.setdefault(key.strip(), val.strip())
+def main(argv=None) -> int:
+    _load_dotenv()
+    p = argparse.ArgumentParser(prog="anonproxy", description="Reversible LLM anonymization proxy")
+    p.add_argument("--engagement", help="engagement id (overrides $ENGAGEMENT_ID)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("serve", help="run the reverse proxy")
+    s.add_argument("--host", default=None)
+    s.add_argument("--port", type=int, default=None)
+    s.add_argument("--model", default=None,
+                   help="Ollama model to use (overrides OLLAMA_MODEL), e.g. qwen3:4b, qwen3.6:27b")
+    s.add_argument("--scope", default=None,
+                   help="comma list of client domains/hostnames/orgs to always anonymize")
+    s.add_argument("--scope-file", default=None, dest="scope_file",
+                   help="path to a scope file (one term per line, optional value=TYPE)")
+    sub.add_parser("wizard", help="interactive local setup")
+    sub.add_parser("audit", help="open the audit dashboard in a browser")
+    v = sub.add_parser("verify", help="run tool-output fixtures and report leaks")
+    v.add_argument("--no-llm", action="store_true", help="regex-only (skip Ollama)")
+    v.add_argument("--model", default=None, help="Ollama model to verify with")
+    v.add_argument("--scope", default=None, help="comma list of scope terms")
+    v.add_argument("--scope-file", default=None, dest="scope_file", help="path to a scope file")
+    v.add_argument("--show-mappings", "--audit", action="store_true", dest="show_mappings",
+                   help="print the anonymized output + original→surrogate table")
+    a = sub.add_parser("anon", help="anonymize stdin")
+    a.add_argument("--scope", default=None, help="comma list of scope terms")
+    a.add_argument("--scope-file", default=None, dest="scope_file", help="path to a scope file")
+    sub.add_parser("deanon", help="deanonymize stdin")
+    sub.add_parser("stats", help="show vault stats")
+    sub.add_parser("export", help="dump mappings")
+    # --- profiles: per-test context, one JSON each ---------------------------
+    prof = sub.add_parser("profile", help="manage engagement profiles")
+    pp = prof.add_subparsers(dest="pcmd", required=True)
+    pnew = pp.add_parser("new", help="create a profile")
+    pnew.add_argument("name", help="profile/engagement name (e.g. acme-web)")
+    pnew.add_argument("--scope", default="", help="comma list of scope terms")
+    pnew.add_argument("--scope-file", default=None, dest="scope_file")
+    pnew.add_argument("--detectors", default=None, help="comma chain (default regex,ollama)")
+    pnew.add_argument("--model", default=None, help="Ollama model")
+    pnew.add_argument("--ephemeral", action="store_true",
+                      help="in-memory vault for this engagement (nothing on disk)")
+    pnew.add_argument("--port", type=int, default=8099)
+    pnew.add_argument("--notes", default="")
+    pp.add_parser("list", help="list profiles")
+    pshow = pp.add_parser("show", help="print one profile as JSON")
+    pshow.add_argument("name")
+    ped = pp.add_parser("edit", help="open a profile's JSON in your editor")
+    ped.add_argument("name")
+    prm = pp.add_parser("rm", help="delete a profile (vault/exports untouched)")
+    prm.add_argument("name")
+    up = sub.add_parser("up", help="start the proxy from a profile (default: most recent)")
+    up.add_argument("profile", nargs="?", default=None)
+    up.add_argument("--daemon", action="store_true",
+                    help="run detached; manage with `anonproxy stop`")
+    up.add_argument("--host", default=None)
+    sub.add_parser("stop", help="stop daemonized `up` instance(s)")
+    envp = sub.add_parser("env", help="print/copy client env lines for a profile")
+    envp.add_argument("profile", nargs="?", default=None)
+    envp.add_argument("--copy", action="store_true", dest="do_copy")
+    closep = sub.add_parser("close", help="export mappings to evidence files + wipe vault")
+    closep.add_argument("profile", nargs="?", default=None)
+    closep.add_argument("--keep-vault", action="store_true", dest="keep_vault")
+    args = p.parse_args(argv)
+    if args.cmd == "wizard":
+        from .wizard import run as wizard_run
+        return wizard_run()
+    # --- profiles: pure file management, no Settings needed ------------------
+    from .profiles import (Profile, ProfileStore, client_env_lines,
+                           close_engagement, copy_to_clipboard, open_in_editor,
+                           sanitize_name)
+    store = ProfileStore()
+    def _resolve_profile(name: str | None) -> Profile:
+        prof = store.get(name) if name else store.most_recent()
+        if prof is None and name is None:
+            prof = Profile(name="default")   # first run: sensible starter
+            store.save(prof)
+        if prof is None:
+            known = ", ".join(pr.name for pr in store.list()) or "(none yet)"
+            raise SystemExit(f"no profile {name!r} — known: {known}\n"
+                             f"create one: anonproxy profile new {name}")
+        return prof
+    if args.cmd == "profile":
+        if args.pcmd == "new":
+            name = sanitize_name(args.name)
+            if store.exists(name):
+                raise SystemExit(f"profile {name!r} already exists "
+                                 f"({store.path(name)})")
+            prof = Profile(name=name, notes=args.notes, port=args.port,
+                           ephemeral=args.ephemeral,
+                           scope_file=args.scope_file or "")
+            if args.scope:
+                prof.scope_terms = [x.strip() for x in args.scope.split(",") if x.strip()]
+            if args.detectors:
+                prof.detectors = [x.strip() for x in args.detectors.split(",") if x.strip()]
+            if args.model:
+                prof.ollama_model = args.model
+            path = store.save(prof)
+            print(f"saved {path}")
+            print(f"start it:   anonproxy up {name}"
+                  + ("  (--daemon to detach)" if not args.ephemeral else ""))
+            print(f"client env: anonproxy env {name}")
+            return 0
+        if args.pcmd == "list":
+            rows = store.list()
+            if not rows:
+                print("no profiles yet — create one: anonproxy profile new <name>")
+                return 0
+            print(f"{'NAME':<24} {'PORT':<6} {'DETECTORS':<28} EPHEMERAL  NOTES")
+            for pr in rows:
+                last = time.strftime("%Y-%m-%d", time.localtime(pr.last_used_at)) \
+                    if pr.last_used_at else "never"
+                notes = f"{pr.notes} (last used {last})" if pr.notes else \
+                    (f"(last used {last})" if pr.last_used_at else "")
+                print(f"{pr.name:<24} {pr.port:<6} "
+                      f"{','.join(pr.detectors):<28} "
+                      f"{'yes' if pr.ephemeral else 'no':<9}  {notes}")
+            return 0
+        if args.pcmd == "show":
+            prof = _resolve_profile(args.name)
+            print(json.dumps(asdict(prof), indent=2))
+            return 0
+        if args.pcmd == "edit":
+            prof = _resolve_profile(args.name)
+            open_in_editor(store.path(prof.name))
+            print(f"opened {store.path(prof.name)}")
+            return 0
+        if args.pcmd == "rm":
+            if store.delete(args.name):
+                print(f"deleted {args.name} (vault/exports untouched)")
+                return 0
+            raise SystemExit(f"no profile {args.name!r}")
+        raise SystemExit(f"unknown profile command {args.pcmd!r}")
+    settings = Settings()
+    if args.engagement:
+        settings.engagement_id = args.engagement
+    if getattr(args, "model", None):
+        settings.ollama_model = args.model
+    if getattr(args, "scope", None):
+        settings.scope_terms = [x.strip() for x in args.scope.split(",") if x.strip()]
+    if getattr(args, "scope_file", None):
+        settings.scope_file = args.scope_file
+    if args.cmd == "up":
+        prof = _resolve_profile(args.profile)
+        store.touch(prof.name)
+        prof.apply(settings)
+        if getattr(args, "host", None):
+            settings.host = args.host
+        if args.daemon:
+            return _spawn_daemon(["up", prof.name], settings)
+        _print_banner(settings)
+        _serve(settings)
+        return 0
+    if args.cmd == "stop":
+        return _stop_daemons()
+    if args.cmd == "env":
+        prof = _resolve_profile(args.profile)
+        lines = client_env_lines(prof, host=settings.host)
+        text = "\n".join(lines)
+        if args.do_copy:
+            ok = copy_to_clipboard(text + "\n")
+            print(("copied to clipboard:\n" if ok else "clipboard unavailable, print only:\n")
+                  + text)
+        else:
+            print(text)
+        audit = f"http://{settings.host}:{prof.port}/audit"
+        print(f"# audit: {audit}" +
+              ("  (token-gated: see ANONPROXY_API_TOKEN)" if settings.engine_api_token else ""))
+        return 0
+    if args.cmd == "close":
+        prof = _resolve_profile(args.profile)
+        prof.apply(settings)
+        result = close_engagement(settings, keep_vault=args.keep_vault)
+        if not result["count"]:
+            print("no mappings on disk for this engagement (ephemeral session? "
+                  "close while the proxy still holds them)")
+        print(f"mappings exported: {result['count']}")
+        print(f"  json: {result['json']}")
+        print(f"  csv : {result['csv']}")
+        print(f"vault removed: {'yes' if result['vault_removed'] else 'no'}"
+              + (" (--keep-vault)" if args.keep_vault else ""))
+        return 0
+    if args.cmd == "verify":
+        from . import verify
+        report = verify.run(settings, use_llm=not args.no_llm)
+        verify.print_report(report, show_mappings=args.show_mappings)
+        tcp = report["tool_call_probe"]
+        hard_fail = (report["total_leaks"] or report["roundtrip_failures"]
+                     or report["preserved_failures"]
+                     or report["adversarial"]["leaked"]
+                     or tcp["anthropic_tool_use_leak"] or tcp["openai_tool_call_leak"])
+        return 1 if hard_fail else 0
+    if args.cmd == "audit":
+        import webbrowser
+        from urllib.parse import quote
+        url = f"http://{settings.host}:{settings.port}/audit"
+        if settings.engine_api_token:
+            # fragment, not query: #fragments are never sent to the server, so
+            # the token stays out of access logs; the page reads location.hash.
+            url += "#token=" + quote(settings.engine_api_token, safe="")
+        print(f"Opening {url}")
+        webbrowser.open(url)
+        return 0
+    if args.cmd == "serve":
+        import uvicorn
+        from .proxy.app import create_app
+        if args.host:
+            settings.host = args.host
+        if args.port:
+            settings.port = args.port
+        _print_banner(settings)
+        _serve(settings)
+        return 0
+    engine = Engine(settings=settings)
+    if args.cmd == "anon":
+        sys.stdout.write(engine.anonymize(sys.stdin.read()))
+    elif args.cmd == "deanon":
+        sys.stdout.write(engine.deanonymize(sys.stdin.read()))
+    elif args.cmd == "stats":
+        print(json.dumps(engine.stats(), indent=2))
+    elif args.cmd == "export":
+        print(json.dumps(engine.export(), indent=2))
+    return 0
+def _print_banner(settings) -> None:
+    print(f"Anonproxy listening on http://{settings.host}:{settings.port} "
+          f"(engagement={settings.engagement_id})", file=sys.stderr)
+    print("  Claude Code:  export ANTHROPIC_BASE_URL=http://"
+          f"{settings.host}:{settings.port}", file=sys.stderr)
+    print("  OpenAI SDK:   base_url=http://"
+          f"{settings.host}:{settings.port}/v1", file=sys.stderr)
+def _serve(settings) -> None:
+    import uvicorn
+    from .proxy.app import create_app
+    uvicorn.run(create_app(settings), host=settings.host,
+                port=settings.port, log_level="info")
+def _run_dir() -> Path:
+    d = Path.home() / ".anonproxy" / "run"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+def _spawn_daemon(child_argv: list[str], settings) -> int:
+    """Detach `up` so the terminal is free; `anonproxy stop` reaps it later."""
+    import subprocess
+    log_dir = Path.home() / ".anonproxy" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = log_dir / f"{settings.engagement_id}.log"
+    with open(log_path, "ab") as logf:
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "anonproxy", *child_argv],
+            stdin=subprocess.DEVNULL, stdout=logf, stderr=subprocess.STDOUT,
+            start_new_session=True, cwd=os.getcwd(),
+        )
+    pidfile = _run_dir() / f"up-{settings.port}.pid"
+    pidfile.write_text(str(proc.pid))
+    print(f"started pid {proc.pid} (engagement={settings.engagement_id}, "
+          f"port={settings.port})")
+    print(f"  logs: {log_path}")
+    print(f"  stop: anonproxy stop")
+    return 0
+def _stop_daemons() -> int:
+    import signal
+    import time as _time
+    stopped = 0
+    for pidfile in sorted(_run_dir().glob("*.pid")):
+        try:
+            pid = int(pidfile.read_text().strip())
+        except ValueError:
+            pidfile.unlink()
+            continue
+        try:
+            os.kill(pid, signal.SIGTERM)
+            for _ in range(20):          # up to ~2s for a clean shutdown
+                try:
+                    os.kill(pid, 0)
+                except ProcessLookupError:
+                    break
+                _time.sleep(0.1)
+            else:
+                os.kill(pid, signal.SIGKILL)
+            stopped += 1
+            print(f"stopped pid {pid} ({pidfile.name})")
+        except (ProcessLookupError, PermissionError):
+            print(f"pid {pid} not running — clearing stale pidfile")
+        finally:
+            try:
+                pidfile.unlink()
+            except FileNotFoundError:
+                pass
+    if not stopped:
+        print("no daemonized instances found "
+              "(menubar-managed proxies stop from the menu)")
+    return 0
+if __name__ == "__main__":
+    raise SystemExit(main())