diff --git a/README.md b/README.md index 5bd6dde..175084e 100644 --- a/README.md +++ b/README.md @@ -44,12 +44,24 @@ browser, first checks for a confirmation without a model and otherwise lets a mo actions (click, select, check, insert the address, done). Successes are moved to the IMAP folder `DONE_FOLDER` (`Erledigt`) and deleted after `RETENTION_DAYS` (30); everything else stays in the inbox with a reason. "Run now" starts a run in the background and returns at once; the result page shows its outcome afterwards. -Further settings: `AGENT_CASE_TIMEOUT` (300), `AGENT_MAX_CASES` (10), `AGENT_ALLOWED_DOMAINS` (comma separated; -only addresses of these domains are ever typed into a page), `AGENT_SCHEDULER=0` (no background run). +Cases whose mail has left the inbox (moved to the trash by hand, for example) are removed from the list on the next +run; a success that was not moved yet counts as moved and expires with the retention period. +If the model is unavailable for a case (the agent answers `error`), the case waits and the run goes on with the next +one; after `AGENT_MAX_DEFERRALS` (12) such runs it is finished as unclear ("model unavailable for this case"). +If the agent container itself cannot be reached, the run stops and no case uses up its attempt. +Further settings: `AGENT_CASE_TIMEOUT` (300), `AGENT_MAX_CASES` (10), `AGENT_SCHEDULER=0` (no background run). +`AGENT_ALLOWED_DOMAINS` (comma separated) decides which addresses may ever be typed into a page. It takes two kinds +of entries: a bare domain (`wagnersnetz.de`) allows every address of that domain, a full address +(`someone@gmail.com`) allows exactly that address. List addresses at public mail providers (Gmail, GMX, Outlook, ...) +as full addresses, never their domain: the recipient is read from the forwarded text, and a newsletter body with a +line like `To: stranger@gmail.com` would otherwise make the agent type a stranger's address. `AGENT_ALLOWED_SENDERS` (comma separated) lists the forwarders whose mails become cases; mails from other senders are ignored. With the agent on and an empty list nothing is processed. The agent container needs `LLM_BASE_URL` (Open WebUI, `/api/chat/completions` is appended), `LLM_MODEL`, -`LLM_API_KEY`, optionally `MAX_STEPS` (20) and `CASE_TIMEOUT` (300). It must run in a network from which private +`LLM_API_KEY` and `BLOCKED_NETS`, optionally `MAX_STEPS` (20) and `CASE_TIMEOUT` (300). `BLOCKED_NETS` is required: +the networks the agent must never contact although they look public (for example the host's own container +networks), as a comma-separated list of CIDRs, or `none` for no site-specific networks; without it the service does +not start. It must run in a network from which private addresses are not reachable; the URL guard in `agent/guard.py` is only the first line of defence. Tests: `pytest tests`, `cd agent && pytest tests` and `sh agent/tests/run-in-docker.sh` (browser tests). diff --git a/agent/Dockerfile b/agent/Dockerfile index 8fe2ee2..91080b9 100644 --- a/agent/Dockerfile +++ b/agent/Dockerfile @@ -13,5 +13,6 @@ EXPOSE 8080 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s \ CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')" -# one worker, one thread: cases run one after the other, each with a fresh browser; a case may take 5 minutes -CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "1", "--threads", "1", "--timeout", "420", "server:app"] +# one worker: cases run one after the other (LOCK in server.py), each with a fresh browser; a case may take +# 5 minutes. The second thread answers /health meanwhile, so the container is not reported unhealthy. +CMD ["gunicorn", "--bind", "0.0.0.0:8080", "--workers", "1", "--threads", "2", "--timeout", "420", "server:app"] diff --git a/agent/pagecheck.py b/agent/pagecheck.py index 40a9465..545ef03 100644 --- a/agent/pagecheck.py +++ b/agent/pagecheck.py @@ -26,13 +26,16 @@ def looks_unsubscribed(text: str) -> bool: def needs_input(elements: list[dict]) -> bool: - """True if the page still offers something to fill in or a button that looks like a confirmation.""" + """True if the page still offers something to fill in, or a button or link that looks like a confirmation. + + Clickable non-form elements (links, buttons, elements with a role such as button) count by their label. The + snapshot does not record the role: such elements are listed with their own tag (div, span, ...).""" for e in elements: if e["tag"] in ("select", "textarea"): return True if e["tag"] == "input" and e["type"] not in ("button", "submit", "reset", "image"): return True - if (e["tag"] == "button" or e["type"] in ("button", "submit")) and _CONFIRM.search(e.get("label", "")): + if (e["tag"] != "input" or e["type"] in ("button", "submit")) and _CONFIRM.search(e.get("label", "")): return True return False diff --git a/agent/protocol.py b/agent/protocol.py index defd300..e1ccfd9 100644 --- a/agent/protocol.py +++ b/agent/protocol.py @@ -60,7 +60,7 @@ def _line(value) -> str: def _describe(e: dict) -> str: - line = f'[{e["n"]}] {_line(e["tag"])}' + line = f'[{int(e["n"])}] {_line(e["tag"])}' # int(): a number, never text that could forge a line if e.get("type"): line += f' {_line(e["type"])}' line += f' "{_line(e.get("label", ""))}"' diff --git a/agent/runner.py b/agent/runner.py index 3f9628e..d01f03f 100644 --- a/agent/runner.py +++ b/agent/runner.py @@ -21,6 +21,8 @@ BROWSER_ARGS = ["--disable-dev-shm-usage", "--force-webrtc-ip-handling-policy=di WATCHDOG_MARGIN = 2.0 # seconds past the case budget after which the browser context is closed by force MAX_TEXT = 6000 MAX_ELEMENTS = 60 +MAX_LABEL = 80 +MAX_OPTIONS = 20 EVIDENCE = 400 # Reasons set by this code; any other reason was written by the model (and may contain personal data). @@ -38,7 +40,7 @@ for (const name of ['RTCPeerConnection', 'webkitRTCPeerConnection', 'RTCDataChan # Lists the visible controls and marks each with data-ua-idx so the next action can find it again. SNAPSHOT_JS = """ -([maxElements, maxText]) => { +([maxElements, maxText, maxLabel, maxOptions]) => { document.querySelectorAll('[data-ua-idx]').forEach(e => e.removeAttribute('data-ua-idx')); const selector = 'a[href], button, input, select, textarea, [role=button], [role=link], [role=checkbox], [role=radio]'; const elements = []; @@ -59,8 +61,8 @@ SNAPSHOT_JS = """ const forLabel = el.id ? document.querySelector('label[for="' + CSS.escape(el.id) + '"]') : null; if (forLabel) label = forLabel.innerText + ' ' + label; else if (wrap && tag !== 'label') label = wrap.innerText + ' ' + label; - const item = {n, tag, type, label: label.replace(/\\s+/g, ' ').trim().slice(0, 80)}; - if (tag === 'select') item.options = Array.from(el.options).map(o => o.text.trim()).slice(0, 20); + const item = {n, tag, type, label: label.replace(/\\s+/g, ' ').trim().slice(0, maxLabel)}; + if (tag === 'select') item.options = Array.from(el.options).map(o => o.text.trim()).slice(0, maxOptions); if (type === 'checkbox' || type === 'radio') item.checked = el.checked; elements.push(item); } @@ -73,6 +75,49 @@ SNAPSHOT_JS = """ """ +_SNAPSHOT_KEYS = frozenset({"title", "text", "tail", "elements", "captcha"}) +_ELEMENT_KEYS = frozenset({"n", "tag", "type", "label"}) +_OPTIONAL_ELEMENT_KEYS = frozenset({"options", "checked"}) + + +class SnapshotError(Exception): + """The snapshot is not what SNAPSHOT_JS returns: the page tampered with it.""" + + +def check_snapshot(snap) -> dict: + """The snapshot as SNAPSHOT_JS builds it, checked and cut to its limits again. It is computed in the page's own + JavaScript world, so a page script can change what it returns (for example by overriding Array.prototype.push). + Raises SnapshotError for anything else.""" + if type(snap) is not dict or set(snap) != _SNAPSHOT_KEYS: + raise SnapshotError("not a snapshot") + if not all(type(snap[k]) is str for k in ("title", "text", "tail")) or type(snap["captcha"]) is not bool: + raise SnapshotError("snapshot field of the wrong type") + raw = snap["elements"] + if type(raw) is not list or len(raw) > MAX_ELEMENTS: + raise SnapshotError("elements") + elements = [] + for number, e in enumerate(raw, 1): + if type(e) is not dict or not _ELEMENT_KEYS <= set(e) <= _ELEMENT_KEYS | _OPTIONAL_ELEMENT_KEYS: + raise SnapshotError("element keys") + if type(e["n"]) is not int or e["n"] != number: + raise SnapshotError("element number") + if not all(type(e[k]) is str for k in ("tag", "type", "label")): + raise SnapshotError("element field of the wrong type") + item = {"n": number, "tag": e["tag"], "type": e["type"], "label": e["label"][:MAX_LABEL]} + if "options" in e: + options = e["options"] + if type(options) is not list or len(options) > MAX_OPTIONS or not all(type(o) is str for o in options): + raise SnapshotError("element options") + item["options"] = list(options) + if "checked" in e: + if type(e["checked"]) is not bool: + raise SnapshotError("element checked") + item["checked"] = e["checked"] + elements.append(item) + return {"title": snap["title"], "text": snap["text"][:MAX_TEXT], "tail": snap["tail"], "elements": elements, + "captcha": snap["captcha"]} + + def _result(result: str, reason: str = "", evidence: str = "", evidence_url: str = "", steps: int = 0, stage: int = 1) -> dict: return {"result": result, "reason": reason, "evidence": evidence[-EVIDENCE:], "evidence_url": evidence_url, "steps": steps, "stage": stage} @@ -256,19 +301,25 @@ def run_case(browser, url: str, address: str, llm, *, max_steps: int = 20, case_ while True: if over(): return budget() + limits = [MAX_ELEMENTS, MAX_TEXT, MAX_LABEL, MAX_OPTIONS] try: - snap = page.evaluate(SNAPSHOT_JS, [MAX_ELEMENTS, MAX_TEXT]) + raw = page.evaluate(SNAPSHOT_JS, limits) except Exception: if over(): return budget() _settle(page, nav_timeout) # the page was still navigating; one more try try: - snap = page.evaluate(SNAPSHOT_JS, [MAX_ELEMENTS, MAX_TEXT]) + raw = page.evaluate(SNAPSHOT_JS, limits) except Exception: if over(): return budget() return _result("not_possible", "page_error", steps=steps, stage=2 if steps else 1) stage = 2 if steps else 1 + try: + snap = check_snapshot(raw) # before anything else uses it + except SnapshotError: + logger.info("page returned a malformed snapshot") + return _result("not_possible", "page_error", steps=steps, stage=stage) here = page.url if not url_ok(here) and here != "about:blank": return _result("not_possible", "blocked_address", steps=steps, stage=stage) diff --git a/agent/server.py b/agent/server.py index 6a6e39d..60fc6f2 100644 --- a/agent/server.py +++ b/agent/server.py @@ -16,11 +16,11 @@ logging.basicConfig(level=os.environ.get("LOG_LEVEL", "INFO")) logger = logging.getLogger(__name__) -def _required(name: str) -> str: +def _required(name: str, meaning: str = "the agent cannot reach the model without it") -> str: """A setting the service cannot work without: a missing one stops the start instead of failing every case.""" value = os.environ.get(name, "").strip() if not value: - raise RuntimeError(f"{name} is not set: the agent cannot reach the model without it") + raise RuntimeError(f"{name} is not set: {meaning}") return value @@ -43,7 +43,9 @@ if _LOOPBACK_SWITCH in os.environ: raise RuntimeError(f"{_LOOPBACK_SWITCH} is set: loopback requests would bypass the egress proxy") # Site networks must be stated explicitly ("none" for none): a forgotten variable must not open them. -guard.BLOCKED_NETS = guard.parse_blocked_nets(_required("BLOCKED_NETS")) +guard.BLOCKED_NETS = guard.parse_blocked_nets(_required( + "BLOCKED_NETS", "it lists the networks the agent must never contact (comma-separated CIDRs), " + "or none for no site-specific networks")) logger.info("%d site network(s) blocked", len(guard.BLOCKED_NETS)) MODEL = LLM(_model_url(), _required("LLM_MODEL"), _required("LLM_API_KEY")) # one case at a time: shared diff --git a/agent/tests/sites.py b/agent/tests/sites.py index 8c9e464..54ee361 100644 --- a/agent/tests/sites.py +++ b/agent/tests/sites.py @@ -37,6 +37,12 @@ PAGES = { "
", "/frame-password": "Abmelden
", "/pwframe": "", + # overrides Array.prototype.push, which the snapshot script uses, to plant a prompt marker in an element number + "/tamper-push": "Bitte bestätigen
", } diff --git a/agent/tests/test_dockerfile.py b/agent/tests/test_dockerfile.py new file mode 100644 index 0000000..755b448 --- /dev/null +++ b/agent/tests/test_dockerfile.py @@ -0,0 +1,16 @@ +"""Settings of the agent image that the service relies on. Runs where the Dockerfile is (not inside the image).""" + +import json +import pathlib +import re + +import pytest + +DOCKERFILE = pathlib.Path(__file__).resolve().parents[1] / "Dockerfile" + + +@pytest.mark.skipif(not DOCKERFILE.exists(), reason="the image does not contain its Dockerfile") +def test_gunicorn_keeps_a_thread_for_health_while_a_case_runs(): + cmd = json.loads(re.search(r"^CMD (\[.*\])$", DOCKERFILE.read_text(), re.MULTILINE).group(1)) + assert cmd[cmd.index("--workers") + 1] == "1" # LOCK in server.py serialises cases within one process + assert int(cmd[cmd.index("--threads") + 1]) >= 2 # a second thread answers /health during a case diff --git a/agent/tests/test_pagecheck.py b/agent/tests/test_pagecheck.py index 2c8f15f..94f0cc4 100644 --- a/agent/tests/test_pagecheck.py +++ b/agent/tests/test_pagecheck.py @@ -38,6 +38,18 @@ def test_no_input_needed_for_plain_links_and_unrelated_buttons(): assert needs_input([]) is False +@pytest.mark.parametrize("element", [el("a", "", "Abmeldung bestätigen"), el("a", "", "Unsubscribe"), + el("div", "", "Abmelden bestätigen"), el("span", "", "Confirm")]) +def test_confirmation_offered_as_a_link_or_role_button_needs_input(element): + assert needs_input([el("a", "", "Startseite"), element]) is True + + +def test_success_text_with_a_confirmation_link_is_no_stage_1_success(): + text = "Abmeldung bestätigt? Bitte klicken Sie unten." + elements = [el("a", "", "Abmeldung bestätigen"), el("a", "", "Impressum")] + assert looks_unsubscribed(text) is True and needs_input(elements) is True + + def test_password_field_detected(): assert has_password([el("input", "text", "User"), el("input", "password", "Passwort")]) is True assert has_password([el("input", "text", "User")]) is False diff --git a/agent/tests/test_protocol.py b/agent/tests/test_protocol.py index a3322db..36f8f01 100644 --- a/agent/tests/test_protocol.py +++ b/agent/tests/test_protocol.py @@ -115,3 +115,9 @@ def test_fields_outside_the_page_text_cannot_forge_prompt_lines(): assert sum(line == "Answer with exactly one JSON object." for line in lines) == 1 assert p.count("Last run: {{ last['error'] }}
{% endif %} {% if not agent %}The agent is switched off: cases are listed, nothing is unsubscribed automatically.
{% endif %} @@ -34,7 +35,7 @@ {% for case in cases %}