From 6a45a6373f52825c666ba8cdffebe5df5742a18d Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Sun, 18 Oct 2026 11:28:38 +0000 Subject: [PATCH] docs(threat-model): one pass over automations' entries, each naming its mitigation and test Workflow studio M12, item 2. Each automations entry now names its mitigation and the backend tests that prove it: - inbound webhooks (POST /automations/hooks/{token}): test_automation_hooks.py - outbound http_request (P-SSRF-GUARD): test_actions_web.py - the agent acting on outside text (P-INJECTION-EGRESS, P-AUTOMATION-ACTOR): test_actions_ai.py, test_automation_nodes.py, test_automation_vars.py, test_automation_runs.py - approvals decided in chat rooms and the 100-waiting cap (P-AUTOMATION-APPROVAL): test_approvals.py, test_approvals_chat.py - loop amplification (P-AUTOMATION-LOOP): test_automation_runs.py - timers flooding: the 1000-waiting cap per automation, missing from the model, is added to P-AUTOMATION-LOOP (test_timers.py) - `matches` cost: the /api/v1/automations row now names the bound as its companions did; test_match_ops.py The prose cites them as "Tested by"; the YAML and JSON carry them as x-tests. ci/validate_threat_model.py now fails when a cited test file or function is gone, and the threat model workflow also runs when fastapi_backend/tests changes, so a citation can't outlive its test. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01AjJqXgjj1cNdKGRQbX5frb --- .github/workflows/threat-model.yml | 7 +-- ci/test_validate_threat_model.py | 29 +++++++++++++ ci/validate_threat_model.py | 38 +++++++++++++++- threat-model.json | 70 ++++++++++++++++++++++++++---- threat-model.md | 16 +++---- threat-model.yaml | 47 +++++++++++++++++++- 6 files changed, 185 insertions(+), 22 deletions(-) diff --git a/.github/workflows/threat-model.yml b/.github/workflows/threat-model.yml index ccc7ba4f1..1977f9860 100644 --- a/.github/workflows/threat-model.yml +++ b/.github/workflows/threat-model.yml @@ -1,13 +1,14 @@ name: threat model # Checks that threat-model.md (canonical), threat-model.yaml and threat-model.json agree: a change to the prose changes -# a companion too, the property ids in all three, and the open-question numbers. See ci/validate_threat_model.py. +# a companion too, the property ids in all three, the open-question numbers, and that the tests it cites exist (so it +# also runs when the backend tests change). See ci/validate_threat_model.py. on: push: branches: [main] - paths: [threat-model.md, threat-model.yaml, threat-model.json, ci/validate_threat_model.py, ci/test_validate_threat_model.py, .github/workflows/threat-model.yml] + paths: [threat-model.md, threat-model.yaml, threat-model.json, ci/validate_threat_model.py, ci/test_validate_threat_model.py, .github/workflows/threat-model.yml, "fastapi_backend/tests/**"] pull_request: - paths: [threat-model.md, threat-model.yaml, threat-model.json, ci/validate_threat_model.py, ci/test_validate_threat_model.py, .github/workflows/threat-model.yml] + paths: [threat-model.md, threat-model.yaml, threat-model.json, ci/validate_threat_model.py, ci/test_validate_threat_model.py, .github/workflows/threat-model.yml, "fastapi_backend/tests/**"] workflow_dispatch: concurrency: diff --git a/ci/test_validate_threat_model.py b/ci/test_validate_threat_model.py index e1255ca0d..c7e0486c0 100644 --- a/ci/test_validate_threat_model.py +++ b/ci/test_validate_threat_model.py @@ -194,6 +194,35 @@ def test_unknown_base_is_an_error(self): [error] = changed_since(self.model.root, "no-such-ref") self.assertIn("can't compare with 'no-such-ref'", error) + def test_cited_tests_must_exist(self): + tests = self.model.root / "fastapi_backend" / "tests" + tests.mkdir(parents=True) + (tests / "test_x.py").write_text( + "def test_a():\n pass\n\n\nasync def test_b():\n pass\n" + ) + cited = "Tested by `fastapi_backend/tests/test_x.py` `test_a`, `test_b`." + self.model.write( + PROSE.replace("| P-ONE | One. |", f"| P-ONE | One. {cited} |"), + {**SIDECAR, "x-tests": ["fastapi_backend/tests/test_x.py::test_a"]}, + ) + self.assertEqual(validate(self.model.root), []) + self.model.write( + PROSE.replace( + "| P-ONE | One. |", + "| P-ONE | One. Tested by `fastapi_backend/tests/test_x.py` `test_a`, `test_gone`. |", + ), + {**SIDECAR, "x-tests": ["fastapi_backend/tests/test_y.py::test_a"]}, + ) + errors = validate(self.model.root) + self.assertEqual(len(errors), 2, errors) + self.assertIn( + "threat-model.md:7 cites test_gone in fastapi_backend/tests/test_x.py", + errors[0], + ) + self.assertIn( + "cites fastapi_backend/tests/test_y.py, which doesn't exist", errors[1] + ) + def test_two_changes_to_the_prose_merge_cleanly(self): # Issue #507: each branch changes the prose and the companions in its own place, so they merge without a # conflict and the merge still validates. A hash of the whole prose in the YAML made every such pair conflict. diff --git a/ci/validate_threat_model.py b/ci/validate_threat_model.py index 24034d1e2..8081bdfa5 100644 --- a/ci/validate_threat_model.py +++ b/ci/validate_threat_model.py @@ -13,7 +13,8 @@ - the claimed (P-), disclaimed (N-) and known-non-finding (KNF-) ids are the same set in all three files, and the matrix-derived (MX-) ids are the same in both companions; - every P-, N-, KNF- or MX- id mentioned anywhere is one of those defined ids; -- the open questions are numbered Q1..Qn in the JSON, and every Qn cited anywhere is one of them. +- the open questions are numbered Q1..Qn in the JSON, and every Qn cited anywhere is one of them; +- every test cited (a "Tested by" in the prose, x-tests in the companions) is defined in the file it names. Usage: python ci/validate_threat_model.py [--base REF] [repo_root]. CI passes --base HEAD^1; locally, use --base origin/main. Exits 1 and lists every problem when anything disagrees. @@ -40,6 +41,13 @@ ) Q_RE = re.compile(r"(?fastapi_backend/tests/[\w/]+\.py)::(?Ptest_\w+)" +) +TEST_LIST_RE = re.compile( + r"`(?Pfastapi_backend/tests/[\w/]+\.py)`(?P(?:,? `test_\w+`)+)" +) YAML_KEYS = ( "schema prose_version components entry_points adversaries properties_claimed properties_disclaimed " @@ -175,9 +183,37 @@ def validate(root: Path) -> list[str]: errors.append( f"{name}:{line} cites {m.group(0)}; there are {count} open questions" ) + + # Cited tests exist, so a "Tested by" can't outlive the test it names. + for name, text in ( + ("threat-model.md", prose), + ("threat-model.yaml", yaml_text), + ("threat-model.json", json_text), + ): + for path, test, at in cited_tests(text): + source = root / path + if not source.is_file(): + problem = f"cites {path}, which doesn't exist" + elif not re.search( + rf"^\s*(?:async\s+)?def {test}\(", source.read_text(), re.MULTILINE + ): + problem = f"cites {test} in {path}, which doesn't define it" + else: + continue + errors.append(f"{name}:{text[:at].count(chr(10)) + 1} {problem}") return errors +def cited_tests(text: str) -> list[tuple[str, str, int]]: + """(path, test, offset) for each test cited: `path` `test_a`, `test_b` in the prose, path::test_a in the companions.""" + found = [(m["path"], m["test"], m.start()) for m in TEST_REF_RE.finditer(text)] + for m in TEST_LIST_RE.finditer(text): + found += [ + (m["path"], t, m.start()) for t in re.findall(r"`(test_\w+)`", m["tests"]) + ] + return found + + def changed_since(root: Path, base: str) -> list[str]: """Problems with a change since base: the prose changed but neither companion did.""" git = ["git", "-C", str(root)] diff --git a/threat-model.json b/threat-model.json index bbacc501a..72ffdcd79 100644 --- a/threat-model.json +++ b/threat-model.json @@ -573,7 +573,14 @@ "component": "optional", "caller_must_enforce": "the person keeps the address and secret to the services that call it; Lens keeps the token hashed, caps size and rate, checks signatures sent, and treats what was sent as outside text", "provenance": "documented", - "source": "docs/automations.md \"No webhook exists until an automation with such a trigger is saved\"" + "source": "docs/automations.md \"No webhook exists until an automation with such a trigger is saved\"", + "x-tests": [ + "fastapi_backend/tests/api/test_automation_hooks.py::test_a_hook_is_made_for_a_trigger_and_only_its_hash_kept", + "fastapi_backend/tests/api/test_automation_hooks.py::test_a_call_is_a_webhook_received_activity", + "fastapi_backend/tests/api/test_automation_hooks.py::test_size_and_rate_caps", + "fastapi_backend/tests/api/test_automation_hooks.py::test_signed_calls_and_retries", + "fastapi_backend/tests/api/test_automations.py::test_a_webhook_trigger_gets_its_address_when_saved_and_loses_it_when_dropped" + ] }, { "entry_point": "GET /feeds/public/{token}, /feeds/public/{token}/items/{item}/audio (a published feed)", @@ -708,7 +715,11 @@ "component": "assistant", "caller_must_enforce": "none — it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR); actions reaching outside Lens ask first; outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS); chains and bursts are bounded (P-AUTOMATION-LOOP); `matches` patterns refuse nested repeats and repeated alternatives that start alike, read at most 20,000 characters and give up after 50 ms", "provenance": "documented", - "source": "docs/automations.md \"Running automations\"" + "source": "docs/automations.md \"Running automations\"", + "x-tests": [ + "fastapi_backend/tests/domain/test_match_ops.py::test_checks_refuse_values_a_test_cant_use", + "fastapi_backend/tests/domain/test_match_ops.py::test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow" + ] }, { "entry_point": "admin sandbox gateway", @@ -1256,7 +1267,14 @@ "severity_tier": "security", "conditions": "URLs a non-admin sets (web import and extension http tools by editors; notification targets by owners; an automation's http_request by its person, within the notification networks; the page addresses the assistant's web_read reads, which the model picks for whoever uses the assistant) reach public addresses only, or networks the operator listed; web paths use ports 80 and 443, follow redirects only to http and https, re-check every redirect and sub-request, and connect to the checked address; an automation's http_request follows no redirect, takes 10 seconds and reads 64 KB at most, asks first unless the person set its node to run on its own, and passes the answer on as outside text", "provenance": "documented", - "source": "maintainer ruling, 2026-10" + "source": "maintainer ruling, 2026-10", + "x-tests-note": "an automation's http_request", + "x-tests": [ + "fastapi_backend/tests/api/test_actions_web.py::test_only_public_addresses_unless_an_admin_allowed_the_network", + "fastapi_backend/tests/api/test_actions_web.py::test_the_answer_is_capped_redirects_are_not_followed_and_it_waits_ten_seconds_at_most", + "fastapi_backend/tests/api/test_actions_web.py::test_it_reaches_outside_lens_so_it_asks_unless_the_node_runs_on_its_own", + "fastapi_backend/tests/api/test_actions_web.py::test_it_calls_an_address_and_passes_on_the_answer_as_outside_text" + ] }, { "property": "P-ADMIN-GUARD", @@ -1304,7 +1322,20 @@ "severity_tier": "security", "conditions": "an automation's action that asks first waits as an approval of the automation's person and nothing runs until they pick; approving, editing or always need them signed in, or (approving an action inside Lens) a yes in the private chat they were told in, from someone the channel lets approve, while it is the only one waiting there or named by number (API keys, apps, MCP and the assistant only list and decline); a decision is claimed once; at most 100 wait per automation, each tells the person once, and undecided ones expire after automations.approval_days", "provenance": "documented", - "source": "docs/automations.md \"Approvals\"" + "source": "docs/automations.md \"Approvals\"", + "x-tests": [ + "fastapi_backend/tests/api/test_approvals.py::test_an_automation_action_waits_as_an_approval_and_the_person_is_told_once", + "fastapi_backend/tests/api/test_approvals.py::test_approve_carries_the_action_out_and_the_run_records_it", + "fastapi_backend/tests/api/test_approvals.py::test_always_lets_the_node_run_on_its_own_and_only_signed_in", + "fastapi_backend/tests/api/test_approvals.py::test_agents_over_mcp_list_and_decline_but_never_approve", + "fastapi_backend/tests/api/test_approvals.py::test_the_assistant_lists_and_declines_but_never_approves", + "fastapi_backend/tests/api/test_approvals.py::test_a_flood_of_approvals_is_capped_per_automation", + "fastapi_backend/tests/api/test_approvals.py::test_undecided_approvals_expire_and_nothing_runs", + "fastapi_backend/tests/api/test_approvals_chat.py::test_a_yes_in_my_chat_decides_an_action_inside_lens", + "fastapi_backend/tests/api/test_approvals_chat.py::test_an_action_reaching_outside_lens_is_decided_on_its_card", + "fastapi_backend/tests/api/test_approvals_chat.py::test_with_two_waiting_a_bare_yes_names_them_and_a_number_picks_one", + "fastapi_backend/tests/api/test_approvals_chat.py::test_a_yes_counts_only_from_someone_let_in_to_approve" + ] }, { "property": "P-INJECTION-EGRESS", @@ -1312,7 +1343,16 @@ "severity_tier": "correctness", "conditions": "Once an assistant answer has read text from outside Lens (a tool result other than Lens's own, the page it was asked from, a namespace assistant's memories, a message in a chat room with no bridge.users, or an earlier answer in the conversation that read any of these), tools that could carry it out of Lens (the person's own read web tools, a web search or page read neither the person nor a tool gave it, other servers' MCP tools, Python tools with the network) and an admin setup conversation's own changes wait for the person's approval. A chat room's answer keeps a web address linkable only when the person, the archive, a tool or Lens wrote it. A bypass is VALID-HARDENING (Q26). An automation's model and agent actions (ask_model, call_tool, ask_agent) run with nobody reading along: the activity and earlier steps reach the model marked as data, every change they would make (notes included) is an approval of the automation's person, and anything that could carry data out of Lens asks first whatever the run read (docs/automations.md \"The model and the agent\"). A saved variable a run set from outside text stays marked as data in later runs' prompts, and an action whose params read it counts as reading outside text (docs/automations.md \"Saved variables\"). Within a research run the person approved, the plan's web searches and page reads, and code with the network when the plan names the code sandbox, don't ask again (P-RESEARCH).", "provenance": "documented", - "source": "docs/assistant.md \"it read out of Lens waits for your approval\"" + "source": "docs/assistant.md \"it read out of Lens waits for your approval\"", + "x-tests-note": "an automation's ask_model, call_tool and ask_agent, and saved variables", + "x-tests": [ + "fastapi_backend/tests/api/test_actions_ai.py::test_prompts_mark_what_the_run_read_from_outside_lens_as_data", + "fastapi_backend/tests/api/test_actions_ai.py::test_an_agent_with_nobody_reading_along_asks_before_anything_goes_out", + "fastapi_backend/tests/api/test_actions_ai.py::test_call_tool_reads_as_the_person_and_changes_only_by_asking_them", + "fastapi_backend/tests/api/test_actions_ai.py::test_ask_agent_works_on_what_happened_and_saves_the_conversation", + "fastapi_backend/tests/domain/test_automation_nodes.py::test_prompts_mark_outside_text_and_template_defaults_are_filled_in", + "fastapi_backend/tests/api/test_automation_vars.py::test_runs_read_their_own_and_their_namespace_s_variables" + ] }, { "property": "P-EXT-SCOPE", @@ -1488,15 +1528,27 @@ "severity_tier": "security", "conditions": "an automation acts only for its maker (run_as), with their permissions when it runs, in namespaces they edit, on activities they may see published after it was switched on; a maker who lost access fails its next run and switches it off; actions reaching outside Lens or other people ask first unless the person, signed in to the web app, set the node to auto (API keys, apps, agents and drafts cannot); the assistant saves automations switched off, and switching one on or running one waits for the person's approval", "provenance": "documented", - "source": "docs/automations.md \"Running automations\"" + "source": "docs/automations.md \"Running automations\"", + "x-tests": [ + "fastapi_backend/tests/domain/test_automation_runs.py::test_what_a_run_does_is_caused_by_it_and_acts_for_its_person", + "fastapi_backend/tests/domain/test_automation_runs.py::test_a_person_who_lost_access_stops_their_automation", + "fastapi_backend/tests/domain/test_automation_runs.py::test_the_guards_leave_activities_out", + "fastapi_backend/tests/api/test_automations.py::test_only_the_person_lets_a_node_run_on_its_own", + "fastapi_backend/tests/api/test_automation_tools.py::test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run" + ] }, { "property": "P-AUTOMATION-LOOP", "violation_symptom": "x-cap-exceeded", "severity_tier": "correctness", - "conditions": "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly", - "provenance": "documented", - "source": "docs/automations.md \"Running automations\"" + "conditions": "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly; an automation has at most 1000 timers waiting; setting more is refused", + "provenance": "documented", + "source": "docs/automations.md \"Running automations\"", + "x-tests": [ + "fastapi_backend/tests/domain/test_automation_runs.py::test_the_guards_leave_activities_out", + "fastapi_backend/tests/domain/test_automation_runs.py::test_the_if_limits_and_dry_runs", + "fastapi_backend/tests/domain/test_timers.py::test_an_automation_has_at_most_so_many_timers_waiting" + ] }, { "property": "P-BROWSER", diff --git a/threat-model.md b/threat-model.md index 3601affb4..650f5ea42 100644 --- a/threat-model.md +++ b/threat-model.md @@ -312,7 +312,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34. | MCP servers: `POST /extensions/mcp/read` (a config pasted from another app), `GET /extensions/mcp/presets` (ready-made ones), `POST /extensions/mcp/test`, MCP `mcp_servers` and `add_mcp_server`, saving an extension of kind `mcp`, `PATCH /extensions/{id}/tools` | config text (JSON or YAML), a server's address and headers, or a command, its arguments and env; a tool name and its switches | reading a config: any signed-in person (nothing is reached or run); testing, saving and switching: admins only (adding over MCP: an admin's API key with the write scope, never an app given access) | data, x-network-destination, x-credential, callback/code (a command) | admin is trusted with the address and the command; reading parses text only; a command runs only in the MCP runner, never next to Lens; credential values are sealed to the extension and where they go, and shown as `••••` (P-SECRETS); a tool switched off isn't offered, and every MCP tool still asks first after outside text (P-INJECTION-EGRESS); a server whose spec says `keep` reuses one session for every caller, which is the server's like its address and token | *(documented, docs/assistant.md "Adding an MCP server")* | | Python code tools, shipped and admin-created templates, workflows, pipelines, routines | Python, Jinja source, regexes | admin only | callback/code | admin is trusted | *(maintainer, 2026-10)* | | MQTT 1883, syslog 5514, `POST /sensors/push/{token}/{stream}` | payloads, hub logins, token in the path | yes, once enabled | data, size/rate, x-credential, x-prompt-injection | admin enables; operator firewalls; readings, alert patterns and new devices reach automations as outside text (`lens.untrusted`) | *(documented, docs/sensors.md "Sensors are off until an admin turns them on")* | -| `POST /automations/hooks/{token}` (an automation's webhook) | body (JSON, a form's text fields or text), query, Standard Webhooks headers, token in the path | yes, anyone given the address | data, size/rate, x-credential, x-prompt-injection | no hook exists until an automation with a webhook trigger is saved; the token is 256 random bits kept only as a hash, and revoked with its trigger; 64 KB and 60 calls a minute per hook; a signature, when sent (or required by a `signed` hook), must match the hook's sealed secret within five minutes; a retried message id is logged once; what was sent is outside text (`lens.untrusted`), wrapped as data in prompts | *(documented, docs/automations.md "No webhook exists until an automation with such a trigger is saved")* | +| `POST /automations/hooks/{token}` (an automation's webhook) | body (JSON, a form's text fields or text), query, Standard Webhooks headers, token in the path | yes, anyone given the address | data, size/rate, x-credential, x-prompt-injection | no hook exists until an automation with a webhook trigger is saved; the token is 256 random bits kept only as a hash, and revoked with its trigger; 64 KB and 60 calls a minute per hook; a signature, when sent (or required by a `signed` hook), must match the hook's sealed secret within five minutes; a retried message id is logged once; what was sent is outside text (`lens.untrusted`), wrapped as data in prompts | *(documented, docs/automations.md "No webhook exists until an automation with such a trigger is saved")*. Tested by `fastapi_backend/tests/api/test_automation_hooks.py` `test_a_hook_is_made_for_a_trigger_and_only_its_hash_kept`, `test_a_call_is_a_webhook_received_activity`, `test_size_and_rate_caps`, `test_signed_calls_and_retries`; `fastapi_backend/tests/api/test_automations.py` `test_a_webhook_trigger_gets_its_address_when_saved_and_loses_it_when_dropped` | | `GET /feeds/public/{token}`, `/feeds/public/{token}/items/{item}/audio` (a published feed) | token in the path, `Range`, `If-None-Match` | yes, anyone given the address | x-credential, resource-name | no feed exists until an editor of a namespace makes one; the token is 256 random bits, found by its hash and sealed with the server key so the namespace's readers see the address again, and a new one stops the old at once; the address reads that feed alone, whose items are bounded by who reads its namespace (P-FEEDS), and `Range` reads only the audio of an item the feed lists | *(documented, docs/feeds.md "Private by default")* | | automations' params and prompts, `POST /automations/preview` and `/automations/variables` | template text, a draft automation, an activity id | yes, anyone signed in (preview, the picker); the namespace editors who manage an automation (its params) | callback/code (declarative), data, x-prompt-injection | rendered in the Jinja sandbox (2 MB of output, `*` and `**` guarded; Q23); previews read only activities, namespaces and automations the person may see; prompts mark outside text as data | *(documented, docs/automations.md "The variable picker and preview")* | | NFS share (port 12049 on the host, 2049 in the worker) | NFS and MOUNT RPCs, client address | yes, once enabled, from `nfs.allowed_networks` | data, x-network-source | admin enables and picks the account; operator firewalls; files written are imported as that account would upload them, checked as uploads, never over what Lens made (`nfs.add_files` off: read-only) | *(documented, docs/file-shares.md "NFS has no login")* | @@ -328,7 +328,7 @@ classified by gate only *(inferred, Q8)*; unread modules are listed in Q34. | `/api/v1/scaling` (providers, groups, units), `PUT /api/v1/settings/scaling`, MCP and assistant scaling tools | provider credentials, a group's terms and rules, a unit id | admin only (MCP: with the write scope) | x-credential, x-env-config | admin is trusted; off until turned on; audited (`scaling.*`) and in the activity ledger; a provider's credentials are sealed per provider and field and shown only as set; a group launches nothing until a person signed in to the web app approves its terms, and agents act only within them (P-SCALING) | *(documented, docs/scaling.md "The person approves")* | | `PUT /api/v1/admin/sandbox`, MCP `set_sandbox_gateway` | `on` | admin only (MCP: with the write scope) | x-env-config | admin is trusted; audited (`lens.sandbox`); refused when the machine can't run the gateway (preflight); reaches the machine only as an inbox request (`action=services`, `profile=sandbox`) the agent checks again; off deletes every sandbox first | *(documented, docs/assistant.md "The gateway")* | | MCP `edit_entity`, `edit_topic`, `merge_topics`, `delete_topic`, `undo_topic_change`, `undo_graph_change`; assistant `propose_topic_change` | entity and topic ids, names, labels, definitions | yes, an agent with an editor's write-scope token; indirectly through content the model reads | data, x-prompt-injection | the curate permission in each namespace touched and a write-capable principal (the same route functions as the web app); the assistant's changes wait for the person's approval; merges and deletes are kept to undo, and audited | *(documented, docs/mcp.md "curate entities and topics as an editor does")* | -| `/api/v1/automations` (save, try, run now, decide, draft from a sentence), the MCP and assistant automation tools; the activities an automation runs on | triggers, `where` and If match trees, the event workflow graph (action params are Jinja templates), `policy`, `limits`, an activity id; the text of the activities themselves | yes: any editor, for automations in namespaces they edit; indirectly through activity text (mail, titles, chat) that reaches action params | callback/code (declarative), data, x-prompt-injection | none; it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR), actions reaching outside Lens ask first, outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS), and chains and bursts are bounded (P-AUTOMATION-LOOP) | *(documented, docs/automations.md "Running automations")* | +| `/api/v1/automations` (save, try, run now, decide, draft from a sentence), the MCP and assistant automation tools; the activities an automation runs on | triggers, `where` and If match trees, the event workflow graph (action params are Jinja templates), `policy`, `limits`, an activity id; the text of the activities themselves | yes: any editor, for automations in namespaces they edit; indirectly through activity text (mail, titles, chat) that reaches action params | callback/code (declarative), data, x-prompt-injection | none; it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR), actions reaching outside Lens ask first, outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS), chains and bursts are bounded (P-AUTOMATION-LOOP), and `matches` patterns refuse nested repeats and repeated alternatives that start alike, read at most 20,000 characters and give up after 50 ms | *(documented, docs/automations.md "Running automations")*. Tested by `fastapi_backend/tests/domain/test_match_ops.py` `test_checks_refuse_values_a_test_cant_use`, `test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow`; the rest under the properties it names | | Assistant code sandbox tools (`run_python`, `run_bash`, `sandbox_files`, `sandbox_nodes`, `share_sandbox_file`, `import_sandbox_file`) and the `sandbox.*` settings | code and scripts the model writes, attachment ids, a path in the sandbox, a compute node's id or name; the gateway address, image and hosts it may reach (admins) | yes: the people `sandbox.who` names, and indirectly through content the model reads | callback/code, data, x-prompt-injection | none; off by default; the code runs in the conversation's own OpenShell sandbox, which holds none of Lens's data or keys and reaches no network unless `sandbox.network` allows it (P-SANDBOX); with the network on, a run after outside text asks first (P-INJECTION-EGRESS); files go in only from the person's own attachments to that conversation, and come out only as an import the person approves or as a download for that person (`share_sandbox_file`); with compute nodes registered by the mesh, a run may go to a ready compute node's own gateway, reached only over the mesh, with the same sandbox settings, and only where the model passed `node` or the conversation's sandbox already is | *(documented, docs/assistant.md "Code sandbox")* | | `GET /api/v1/chats/{cid}/files/{fid}`: a file the code sandbox shared (`share_sandbox_file`) | a file id; the file's bytes, which code the model wrote produced | yes: the person whose conversation it is; indirectly through content the model reads | data, x-prompt-injection | none; served only to the conversation's person (404 for anyone else, or for an id of another conversation) as an `attachment` with `nosniff` and a `sandbox` content policy, never rendered by Lens; the id is random (96 bits) and checked against the conversation; kept encrypted (AES-256-GCM with a key derived from the server's secret, bound to the file and its conversation), at most 20 a conversation and 25 MB each, and deleted with the conversation or the person's account | *(documented, docs/assistant.md "Code sandbox")* | | assistant and MCP `lens_help` | a question's words, a docs page's name | yes, any signed-in person or agent with a read token; indirectly through content the model reads | data, x-prompt-injection | it only reads: the docs come from a fixed folder (a page is picked by name from the ones indexed, never opened by path), searched in an in-memory index; this server's facts are the version, addresses, on/off switches, the chat model's name and the asker's own namespaces, never keys, tokens or model server addresses, and the settings page of each only for admins | *(documented, docs/assistant.md "Questions about Lens itself")* | @@ -560,14 +560,14 @@ Paths in the Voided by column are relative to `fastapi_backend/app/`. Searches c | P-FRAME | The API sends a strict CSP. Only the player (`/embed/`, `/s/`) can be framed, and only by `server.embed_frame_ancestors`. | integrity-bypass | security-critical | *(documented, docs/configuration.md "can be framed")* | Voided by: `server.embed_frame_ancestors` — `core/middleware.py:72` (default `'self'`, `domain/store.py:185`). | | P-HARDENED | In the compose files the database, API and Fedora ports bind to 127.0.0.1, containers run non-root with `no-new-privileges`, and the web app sends `nosniff`, a referrer policy, a permissions policy and a frame policy (HSTS through Cloudflare). In `docker-compose.prod.yml` the DB password is random and the web app listens on this machine unless `LENS_BIND` is set. | x-missing-hardening | correctness-only | *(documented, docs/deployment.md "What's hardened already")* | Voided by: `LENS_BIND=0.0.0.0` — `docker-compose.prod.yml:153`, which an admin can also ask for from Settings (`PUT /api/v1/admin/install`); dev web port — `docker-compose.yml:95` (§1.3); the opt-in `sandbox` profile's `openshell-init`, `openshell-key` and `openshell-gateway` run as root, the gateway with the Docker socket (§1.6). | | P-SECRETS | Stored secrets (source credentials, notification secrets, model API keys, the Hugging Face token, iCal and news feed addresses, an automation's credential headers, sealed to that automation and the address they were saved for, an MCP server's credential headers and env values, sealed to its extension and the address or command they were saved for) are encrypted and write-only. The API reports whether one is set, never its value. A key from the environment is never shown. They do not leak through the API, logs, exports, or a redirect to another server. | info-leak | security-critical | *(documented, SECURITY.md "stored credentials for sources and model servers leaking")* | Voided by: `secret.key` or `ARCHIVE_SECRET_KEY` holders — `domain/settings.py:196-199` (Q14). An admin moving a model URL sends the key there — `domain/llm.py:30-32` (trusted). LLM errors name the URL as typed — `domain/llm.py:41` (Q18). An MCP server's values whose names don't say they carry a credential, and a secret written into its address or arguments, are kept as given — `domain/mcp_servers.py`. | -| P-SSRF-GUARD | URLs a non-admin sets (web import and extension `http` tools by editors; notification targets by owners; an automation's `http_request` by its person, within the notification networks; the page addresses the assistant's `web_read` reads, which the model picks for whoever uses the assistant) reach public addresses only, or networks the operator or an admin listed (an admin, in Settings, never loopback or link-local ones). Web paths use ports 80 and 443, follow redirects only to http and https, re-check every redirect and sub-request, and connect to the checked address. An automation's `http_request` follows no redirect, takes 10 seconds and reads 64 KB at most, asks first unless the person set its node to run on its own, and passes the answer on as outside text. | info-leak | security-critical | *(maintainer, 2026-10)* | Voided by: Operator networks — `domain/store.py:475-476`, `domain/netguard.py:40-41`; admin web networks — `domain/settings.py` `_web_networks`; admin notification networks — `domain/notify.py:286-288`; Chromium without sandbox — `domain/convert.py:273`. Search: `grep -rlE 'public_ip\|netguard\.(resolve\|Guard)\|web_networks' fastapi_backend/app` — `netguard.py`, `webcapture.py`, `feeds.py`, `extensions.py`, `notify.py`, `convert.py`, `store.py`, `web.py`, `routes/imports.py`; none disables the check. | +| P-SSRF-GUARD | URLs a non-admin sets (web import and extension `http` tools by editors; notification targets by owners; an automation's `http_request` by its person, within the notification networks; the page addresses the assistant's `web_read` reads, which the model picks for whoever uses the assistant) reach public addresses only, or networks the operator or an admin listed (an admin, in Settings, never loopback or link-local ones). Web paths use ports 80 and 443, follow redirects only to http and https, re-check every redirect and sub-request, and connect to the checked address. An automation's `http_request` follows no redirect, takes 10 seconds and reads 64 KB at most, asks first unless the person set its node to run on its own, and passes the answer on as outside text. | info-leak | security-critical | *(maintainer, 2026-10)* | Voided by: Operator networks — `domain/store.py:475-476`, `domain/netguard.py:40-41`; admin web networks — `domain/settings.py` `_web_networks`; admin notification networks — `domain/notify.py:286-288`; Chromium without sandbox — `domain/convert.py:273`. Search: `grep -rlE 'public_ip\|netguard\.(resolve\|Guard)\|web_networks' fastapi_backend/app` — `netguard.py`, `webcapture.py`, `feeds.py`, `extensions.py`, `notify.py`, `convert.py`, `store.py`, `web.py`, `routes/imports.py`; none disables the check. Tested by (an automation's `http_request`): `fastapi_backend/tests/api/test_actions_web.py` `test_only_public_addresses_unless_an_admin_allowed_the_network`, `test_the_answer_is_capped_redirects_are_not_followed_and_it_waits_ten_seconds_at_most`, `test_it_reaches_outside_lens_so_it_asks_unless_the_node_runs_on_its_own`, `test_it_calls_an_address_and_passes_on_the_answer_as_outside_text`. | | P-ADMIN-GUARD | Guards Lens documents on admin-set operands hold. iCal and news feeds are fetched like web captures: public addresses only (and `documents.web_networks`), ports 80 and 443, and the password never goes on to a server the calendar or feed redirects to, or to a feed a site's page names on another server *(documented, docs/processing.md "fetched the way web pages are captured")*. The telemetry endpoint cannot carry a user name or password or be a link-local address *(documented, domain/settings.py validation message "can't be a link-local address")*. | info-leak | security-critical | *(documented, docs/processing.md "fetched the way web pages are captured")* | Voided by: `documents.web_networks` widens the iCal and news feed guard — `domain/feeds.py:377`; telemetry checks — `domain/settings.py:751`, `domain/settings.py:757`. | | P-NO-FETCH | SPARQL refuses SERVICE and FROM and never loads a named graph. RDF import fetches nothing, refuses remote JSON-LD contexts and does not read RDF/XML. | info-leak | security-critical | *(documented, rdf_import.py docstring "Nothing is fetched while reading")* | Voided by: Process-global rdflib flag, set per call — `domain/rdf.py:576`; SERVICE refused — `domain/rdf.py:551`; remote contexts — `domain/rdf_import.py:54-56`. | | P-QUERY | Cypher is read-only and runs on the caller's readable namespaces. A query stops within 3 million steps or 8 seconds; paths run up to 8 hops. Threshold: running past the budget is a bug; slow within it is not. | integrity-bypass (writes, scope); hang (budget) | security-critical (scope, writes); correctness-only (budget) | *(documented, docs/graph.md "3 million steps")* | Voided by: Admins see every namespace; write refusals — `domain/cypher.py:39`; budgets — `domain/cypher.py:35-38`. | | P-RETRIEVAL | Chat, assistant tools and MCP return only what the person can read, within the conversation's scope, and the tool loop stops at `ai.max_steps` (or the tool calls a question allows, at most `ai.max_tool_calls`) and `ai.max_transcript_reads`. A namespace's chat completions answer from that namespace alone, with only the read tools its owners offered. | info-leak (scope); hang (caps) | security-critical (scope); correctness-only (caps) | *(documented, docs/assistant.md "limited to what the person can read")* | Voided by: Admins read everything; an admin setup conversation adds server tools and the `act` flag — `domain/ai_tools.py:287-289`; `ai.extensions: false` turns extensions off. | | P-APPROVAL | Assistant tools that change data wait for the person's approval, except notes and an admin's setup conversation. Inviting people and changing their access always wait, even there, and the assistant cannot remove an account. Only the person approves, signed in to Lens or in the chat it was asked in: an API key, an app, MCP and the assistant can only decline (`domain/approvals.py` `can`). | integrity-bypass | security-critical | *(documented, docs/assistant.md "Approvals")* | Voided by: Admins read everything; an admin setup conversation adds server tools and the `act` flag — `domain/ai_tools.py:287-289`; `ai.extensions: false` turns extensions off. | -| P-AUTOMATION-APPROVAL | An automation's action that asks first (effect `out`, or `lens` beyond the event's own object) waits as an approval of the automation's person, and nothing runs until they pick. Approving, editing or allowing a node from now on (`always`) needs them signed in to Lens, or (approving an action that stays inside Lens, effect `lens`) a yes in the private chat Lens told them in, from someone on that channel's `users` list with approving on, while it is the only thing waiting there or named by its number; an action that reaches outside Lens is approved on its card. API keys, apps, MCP and the assistant can only list and decline. A decision is claimed once (two at once can't both carry it out). At most 100 wait per automation and each tells the person once, so a flood of activities can't bury the inbox or their chat; undecided ones expire after `automations.approval_days` and nothing runs. | integrity-bypass | security-critical | *(documented, docs/automations.md "Approvals")* | Voided by: the person setting a node to `auto` (`always`, or the builder's toggle) — that node then runs without asking; an admin raising `automations.approval_days`. The summary and the message the person is told hold text the run read from outside Lens: links in it are broken up (P-INJECTION-EGRESS), and what runs is the intent the card shows. | -| P-INJECTION-EGRESS | Once an assistant answer has read text from outside Lens (a tool result other than Lens's own, the page it was asked from, a namespace assistant's memories, a message in a chat room with no `bridge.users`, or an earlier answer in the conversation that read any of these), tools that could carry it out of Lens (the person's own `read` web tools, a web search or page read neither the person nor a tool gave it, other servers' MCP tools, Python tools with the network, code in the code sandbox with its network on) and an admin setup conversation's own changes wait for the person's approval. A chat room's answer keeps a web address linkable only when the person, the archive, a tool or Lens wrote it. A bypass is `VALID-HARDENING` (Q26). An automation's model and agent actions (`ask_model`, `call_tool`, `ask_agent`) run with nobody reading along: the activity and earlier steps reach the model marked as data, every change they would make (notes included) is an approval of the automation's person, and anything that could carry data out of Lens asks first whatever the run read (docs/automations.md "The model and the agent"). A saved variable a run set from outside text stays marked as data in later runs' prompts, and an action whose params read it counts as reading outside text (docs/automations.md "Saved variables"). Within a research run the person approved, the plan's web searches and page reads, and code runs with the network when the plan names the code sandbox, don't ask again: approving the plan approved them (P-RESEARCH). | info-leak | correctness-only | *(documented, docs/assistant.md "it read out of Lens waits for your approval")* | Voided by: `ai.untrusted_asks: false` — `domain/ai_tools.py:519`; `bridge.safe_links: false` — `domain/bridge.py:298`. Notes and memories are written at once: they stay in Lens. Hooks run as their owners set them (P-EXT-SCOPE). An address the read text wrote itself stays linkable in a room. The person's browser asks first as P-BROWSER-GUARD says. | +| P-AUTOMATION-APPROVAL | An automation's action that asks first (effect `out`, or `lens` beyond the event's own object) waits as an approval of the automation's person, and nothing runs until they pick. Approving, editing or allowing a node from now on (`always`) needs them signed in to Lens, or (approving an action that stays inside Lens, effect `lens`) a yes in the private chat Lens told them in, from someone on that channel's `users` list with approving on, while it is the only thing waiting there or named by its number; an action that reaches outside Lens is approved on its card. API keys, apps, MCP and the assistant can only list and decline. A decision is claimed once (two at once can't both carry it out). At most 100 wait per automation and each tells the person once, so a flood of activities can't bury the inbox or their chat; undecided ones expire after `automations.approval_days` and nothing runs. | integrity-bypass | security-critical | *(documented, docs/automations.md "Approvals")* | Voided by: the person setting a node to `auto` (`always`, or the builder's toggle) — that node then runs without asking; an admin raising `automations.approval_days`. The summary and the message the person is told hold text the run read from outside Lens: links in it are broken up (P-INJECTION-EGRESS), and what runs is the intent the card shows. Tested by `fastapi_backend/tests/api/test_approvals.py` `test_an_automation_action_waits_as_an_approval_and_the_person_is_told_once`, `test_approve_carries_the_action_out_and_the_run_records_it`, `test_always_lets_the_node_run_on_its_own_and_only_signed_in`, `test_agents_over_mcp_list_and_decline_but_never_approve`, `test_the_assistant_lists_and_declines_but_never_approves`, `test_a_flood_of_approvals_is_capped_per_automation`, `test_undecided_approvals_expire_and_nothing_runs`; `fastapi_backend/tests/api/test_approvals_chat.py` `test_a_yes_in_my_chat_decides_an_action_inside_lens`, `test_an_action_reaching_outside_lens_is_decided_on_its_card`, `test_with_two_waiting_a_bare_yes_names_them_and_a_number_picks_one`, `test_a_yes_counts_only_from_someone_let_in_to_approve`. | +| P-INJECTION-EGRESS | Once an assistant answer has read text from outside Lens (a tool result other than Lens's own, the page it was asked from, a namespace assistant's memories, a message in a chat room with no `bridge.users`, or an earlier answer in the conversation that read any of these), tools that could carry it out of Lens (the person's own `read` web tools, a web search or page read neither the person nor a tool gave it, other servers' MCP tools, Python tools with the network, code in the code sandbox with its network on) and an admin setup conversation's own changes wait for the person's approval. A chat room's answer keeps a web address linkable only when the person, the archive, a tool or Lens wrote it. A bypass is `VALID-HARDENING` (Q26). An automation's model and agent actions (`ask_model`, `call_tool`, `ask_agent`) run with nobody reading along: the activity and earlier steps reach the model marked as data, every change they would make (notes included) is an approval of the automation's person, and anything that could carry data out of Lens asks first whatever the run read (docs/automations.md "The model and the agent"). A saved variable a run set from outside text stays marked as data in later runs' prompts, and an action whose params read it counts as reading outside text (docs/automations.md "Saved variables"). Within a research run the person approved, the plan's web searches and page reads, and code runs with the network when the plan names the code sandbox, don't ask again: approving the plan approved them (P-RESEARCH). | info-leak | correctness-only | *(documented, docs/assistant.md "it read out of Lens waits for your approval")* | Voided by: `ai.untrusted_asks: false` — `domain/ai_tools.py:519`; `bridge.safe_links: false` — `domain/bridge.py:298`. Notes and memories are written at once: they stay in Lens. Hooks run as their owners set them (P-EXT-SCOPE). An address the read text wrote itself stays linkable in a room. The person's browser asks first as P-BROWSER-GUARD says. Tested by (an automation's `ask_model`, `call_tool` and `ask_agent`, and saved variables): `fastapi_backend/tests/api/test_actions_ai.py` `test_prompts_mark_what_the_run_read_from_outside_lens_as_data`, `test_an_agent_with_nobody_reading_along_asks_before_anything_goes_out`, `test_call_tool_reads_as_the_person_and_changes_only_by_asking_them`, `test_ask_agent_works_on_what_happened_and_saves_the_conversation`; `fastapi_backend/tests/domain/test_automation_nodes.py` `test_prompts_mark_outside_text_and_template_defaults_are_filled_in`; `fastapi_backend/tests/api/test_automation_vars.py` `test_runs_read_their_own_and_their_namespace_s_variables`. | | P-EXT-SCOPE | Your own hooks run in your conversations; another person's hooks run only when an admin shared them. | integrity-bypass | security-critical | *(documented, docs/assistant.md "other people's run only when an admin shared them")* | Voided by: An admin sharing the extension — `domain/extensions.py:595-598`. | | P-NO-CODE | No non-admin can run code on the host. This covers owners, editors, viewers, API tokens, MCP agents, OAuth apps and model tool calls acting for one. Python tools are written by admins only and run only while an admin owns them. | integrity-bypass | security-critical | *(maintainer, 2026-10)* | Voided by: Making someone admin; authoring gate — `domain/extensions.py:129-130`; run gate — `domain/extensions.py:600-601`. `grep -rnE "eval\(\|exec\(\|pickle\|yaml\.load\(\|__import__" fastapi_backend/app` — one `exec`, inside the code-tool child. | | P-UPLOAD | Uploads accept only the types in `uploads.extensions` and are size-capped. Nothing uploaded is executed. Files are served as audio, video or a download, and names carry no folders. | bad-data-accepted | security-critical | *(documented, docs/configuration.md "Uploads accept only the types")* | Voided by: Admin-added types; check — `domain/uploads.py:157-158`. The `attachments` role takes any type (never executed). Bytes are not checked against the extension. | @@ -589,8 +589,8 @@ Paths in the Voided by column are relative to `fastapi_backend/app/`. Searches c | P-NOTIFY | Each notification event is claimed once across processes and retried with backoff. | wrong-output | correctness-only | *(documented, docs/notifications.md "claimed once")* | Voided by: none identified (not required for this symptom; no exhaustive search) | | P-HIERARCHY | Collections nest at most 8 deep, without cycles, 5000 per namespace. | bad-data-accepted | correctness-only | *(documented, docs/api.md "at most 8 deep")* | Voided by: Checks only in `_check_parent` — `domain/hierarchy.py:132`, `:142-143`. `grep -rln '"parent"\]' fastapi_backend/app/domain` — only `domain/hierarchy.py` writes it (Q34 covers unread movers). | | P-FLOW | Flow and tool graphs never loop back and run within a step budget. | hang | correctness-only | *(documented, domain/flow.py docstring "Graphs never loop back")* | Voided by: none identified (not required for this symptom; no exhaustive search) | -| P-AUTOMATION-ACTOR | An automation acts only for the person who made it (`run_as`), with that person's permissions as they are when it runs, in namespaces they can edit: it reacts only to activities that person may see in those namespaces, published after it was last switched on. If the person loses their account, their admin role (for one that works everywhere) or the right to edit one of its namespaces, its next run fails saying so and it is switched off. Actions that reach outside Lens or other people, or change something in Lens other than the event's own object, ask the person first unless the person, signed in to the web app, set that node to run on its own; API keys, apps, agents and drafts cannot. The assistant saves automations switched off, and switching one on or running one waits for the person's approval. | integrity-bypass | security-critical | *(documented, docs/automations.md "Running automations")* | Voided by: an admin manages every automation and can run one now on any activity in its namespaces that its person may see — `api/v1/routes/automations.py`; a node the person set to `auto` acts on outside text without asking (P-INJECTION-EGRESS still applies). | -| P-AUTOMATION-LOOP | Automations cannot set each other off without end: activities an automation made start another only when its trigger says `from_automations`, a chain stops at `automations.max_depth` runs (3), and each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all of them (60). A run over a limit does nothing, is counted, and is logged at most once an hour. | x-cap-exceeded | correctness-only | *(documented, docs/automations.md "Running automations")* | Voided by: limits count in fixed hours and minutes, so up to twice a limit can run across the turn of one; an admin can raise `max_depth` to 10 and `max_runs_per_minute` to 6000 (Settings → Automations). | +| P-AUTOMATION-ACTOR | An automation acts only for the person who made it (`run_as`), with that person's permissions as they are when it runs, in namespaces they can edit: it reacts only to activities that person may see in those namespaces, published after it was last switched on. If the person loses their account, their admin role (for one that works everywhere) or the right to edit one of its namespaces, its next run fails saying so and it is switched off. Actions that reach outside Lens or other people, or change something in Lens other than the event's own object, ask the person first unless the person, signed in to the web app, set that node to run on its own; API keys, apps, agents and drafts cannot. The assistant saves automations switched off, and switching one on or running one waits for the person's approval. | integrity-bypass | security-critical | *(documented, docs/automations.md "Running automations")* | Voided by: an admin manages every automation and can run one now on any activity in its namespaces that its person may see — `api/v1/routes/automations.py`; a node the person set to `auto` acts on outside text without asking (P-INJECTION-EGRESS still applies). Tested by `fastapi_backend/tests/domain/test_automation_runs.py` `test_what_a_run_does_is_caused_by_it_and_acts_for_its_person`, `test_a_person_who_lost_access_stops_their_automation`, `test_the_guards_leave_activities_out`; `fastapi_backend/tests/api/test_automations.py` `test_only_the_person_lets_a_node_run_on_its_own`; `fastapi_backend/tests/api/test_automation_tools.py` `test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run`. | +| P-AUTOMATION-LOOP | Automations cannot set each other off without end: activities an automation made start another only when its trigger says `from_automations`, a chain stops at `automations.max_depth` runs (3), and each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all of them (60). A run over a limit does nothing, is counted, and is logged at most once an hour. An automation has at most 1000 timers waiting (its schedules, joins and actions that wait); setting more is refused, saying so (docs/automations.md "Timers"). | x-cap-exceeded | correctness-only | *(documented, docs/automations.md "Running automations")* | Voided by: limits count in fixed hours and minutes, so up to twice a limit can run across the turn of one; an admin can raise `max_depth` to 10 and `max_runs_per_minute` to 6000 (Settings → Automations). Tested by `fastapi_backend/tests/domain/test_automation_runs.py` `test_the_guards_leave_activities_out`, `test_the_if_limits_and_dry_runs`; `fastapi_backend/tests/domain/test_timers.py` `test_an_automation_has_at_most_so_many_timers_waiting`. | | P-BROWSER | The assistant uses a person's browser only from that person's own conversations and API calls, while their own Lens side panel is connected (seen in the last 20 seconds, not closed). Only that person sees the session's actions and answers them, once each. `ai.browser` off refuses new sessions and offers no browser tools. | integrity-bypass | security-critical | *(documented, docs/browser-assistant.md "Only you")* | Voided by: The side panel carries out what it's asked: which sites it acts on, and what it asks the person first, is the extension's (docs/browser-assistant.md); an agent holding the person's write token can ask too — `api/v1/routes/browser.py`. | | P-BROWSER-GUARD | The Lens extension's side panel reads and acts only on sites the person allowed in it (and the browser granted), and opens an address only on such a site. It asks the person before a click, submit or Enter that the model marks consequential or whose control's words or posting form look so, and, once the answer has read text from outside Lens (`ai.untrusted_asks`), before opening or downloading an address or typing text the person's own message doesn't contain. It never types into password, card or file fields, never reports their values, and shows each action as it happens. | integrity-bypass | security-critical | *(documented, docs/browser-assistant.md "Letting it use your browser")* | Voided by: The consequential check is the model's flag plus a word list (`extensions/browser/src/core/act.js`): a control with no telling words that a misled model doesn't mark runs without asking; synthetic events reach only the page's own handlers. Removing a site from the options stops the side panel acting there, but leaves the browser's access to it for the clipper. Lens sends the ask (`confirm`) and the extension honours it: an extension older than this doesn't ask. | | P-SANDBOX | Code the assistant runs (`run_python`, `run_bash`; `sandbox.enabled`, off by default) runs only for people `sandbox.who` allows (editors and admins, or admins; never viewers), in a sandbox of that conversation's own on the OpenShell gateway, never in Lens's processes. The sandbox gets none of Lens's data, keys or database address: only the code and the files a run copies in, which must be attached to that conversation by that person (25 MB each, 100 MB a run). Its policy allows no egress with `sandbox.network: off`, only pypi.org, files.pythonhosted.org and registry.npmjs.org on 443 with `packages`, and those and the names in `sandbox.hosts` on 80 and 443 with `hosts`; every endpoint is held to public addresses (no private, loopback, link-local or reserved range), so a listed name that resolves to one is refused. A file leaves it only as one of the person's held uploads (25 MB) placed in a namespace by an `import_files` approval, or as a download (`share_sandbox_file`, 25 MB, 20 a conversation) kept encrypted with the conversation, served only to its person as an attachment with `nosniff`, and deleted with the conversation or their account. A sandbox stops after `sandbox.idle_minutes` idle and is deleted after `sandbox.keep_hours` unused or with its conversation. | integrity-bypass | security-critical | *(documented, docs/assistant.md "Code sandbox")* | Voided by: isolation inside the sandbox is OpenShell's (§1.9); `landlock.compatibility: best_effort` runs without Landlock on a kernel that lacks it — `domain/sandbox.py`; whoever the gateway lets in can run sandboxes of their own (in the `sandbox` profile, a holder of its client certificate); a file shared to download is readable by whoever holds `secret.key` or `ARCHIVE_SECRET_KEY` (Q14); what the code prints reaches the model as third-party text (N-PROMPT). | @@ -664,7 +664,7 @@ its person can read; "read" does not mean "public". upload size and page caps (N-BOMBS). **ReDoS**: Cypher refuses nested repeats heuristically; admin regexes are trusted (Q25). Patterns in automations' conditions (`matches`, which members write and which run on outside text) refuse nested repeats and repeated alternatives that start alike, read at most 20,000 characters and give up after - 50 ms each. **XXE and billion laughs**: RDF/XML is refused (N-RDF-XML); docx XML goes to the stdlib parser (Q22). + 50 ms each (tested by `fastapi_backend/tests/domain/test_match_ops.py` `test_checks_refuse_values_a_test_cant_use`, `test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow`). **XXE and billion laughs**: RDF/XML is refused (N-RDF-XML); docx XML goes to the stdlib parser (Q22). - **SSRF**: in model for non-admin URLs (P-SSRF-GUARD) and guarded admin operands (P-ADMIN-GUARD); out for other admin URLs (N-ADMIN). **CSRF**: no cookies on the API (N-CSRF), except the IIIF flow (Q1). - **Brute force and volume DoS**: out beyond the sign-in throttles (N-VOLUME, N-THROTTLE-SCOPE). **Clickjacking**: diff --git a/threat-model.yaml b/threat-model.yaml index 1dba6f48c..48379d033 100644 --- a/threat-model.yaml +++ b/threat-model.yaml @@ -495,6 +495,12 @@ entry_points: obligation_id: keep-hook-addresses-secret caller_must_enforce: "the person keeps the address and secret to the services that call it; Lens keeps the token hashed, caps size and rate, checks signatures sent, and treats what was sent as outside text" provenance: {kind: documented, source: 'docs/automations.md "No webhook exists until an automation with such a trigger is saved"'} + x-tests: + - "fastapi_backend/tests/api/test_automation_hooks.py::test_a_hook_is_made_for_a_trigger_and_only_its_hash_kept" + - "fastapi_backend/tests/api/test_automation_hooks.py::test_a_call_is_a_webhook_received_activity" + - "fastapi_backend/tests/api/test_automation_hooks.py::test_size_and_rate_caps" + - "fastapi_backend/tests/api/test_automation_hooks.py::test_signed_calls_and_retries" + - "fastapi_backend/tests/api/test_automations.py::test_a_webhook_trigger_gets_its_address_when_saved_and_loses_it_when_dropped" - id: "GET /feeds/public/{token}, /feeds/public/{token}/items/{item}/audio (a published feed)" component: optional parameters: @@ -703,6 +709,9 @@ entry_points: control_kinds: [callback/code, data, x-prompt-injection] caller_must_enforce: "none — it runs as its maker with their permissions at run time (P-AUTOMATION-ACTOR); actions reaching outside Lens ask first; outside text marks intents untrusted and breaks up links (P-INJECTION-EGRESS); chains and bursts are bounded (P-AUTOMATION-LOOP); `matches` patterns refuse nested repeats and repeated alternatives that start alike, read at most 20,000 characters and give up after 50 ms" provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} + x-tests: + - "fastapi_backend/tests/domain/test_match_ops.py::test_checks_refuse_values_a_test_cant_use" + - "fastapi_backend/tests/domain/test_match_ops.py::test_a_pattern_reads_a_long_value_only_so_far_and_gives_up_when_slow" - id: "code sandbox" component: assistant parameters: @@ -1726,6 +1735,12 @@ properties_claimed: violation_symptoms: [info-leak] x-voided-by: "operator networks (domain/store.py:475-476, domain/netguard.py:40-41); admin notification networks (domain/notify.py:286-288); Chromium without sandbox (domain/convert.py:273)" provenance: {kind: maintainer, date: "2026-10"} + x-tests-note: "an automation's http_request" + x-tests: + - "fastapi_backend/tests/api/test_actions_web.py::test_only_public_addresses_unless_an_admin_allowed_the_network" + - "fastapi_backend/tests/api/test_actions_web.py::test_the_answer_is_capped_redirects_are_not_followed_and_it_waits_ten_seconds_at_most" + - "fastapi_backend/tests/api/test_actions_web.py::test_it_reaches_outside_lens_so_it_asks_unless_the_node_runs_on_its_own" + - "fastapi_backend/tests/api/test_actions_web.py::test_it_calls_an_address_and_passes_on_the_answer_as_outside_text" - id: P-ADMIN-GUARD kind: confidentiality components: [outbound] @@ -1777,6 +1792,18 @@ properties_claimed: violation_symptoms: [integrity-bypass] x-voided-by: "the person setting a node to auto (always, or the builder's toggle); an admin raising automations.approval_days; the summary and the message told hold outside text, with links broken up (P-INJECTION-EGRESS)" provenance: {kind: documented, source: 'docs/automations.md "Approvals"'} + x-tests: + - "fastapi_backend/tests/api/test_approvals.py::test_an_automation_action_waits_as_an_approval_and_the_person_is_told_once" + - "fastapi_backend/tests/api/test_approvals.py::test_approve_carries_the_action_out_and_the_run_records_it" + - "fastapi_backend/tests/api/test_approvals.py::test_always_lets_the_node_run_on_its_own_and_only_signed_in" + - "fastapi_backend/tests/api/test_approvals.py::test_agents_over_mcp_list_and_decline_but_never_approve" + - "fastapi_backend/tests/api/test_approvals.py::test_the_assistant_lists_and_declines_but_never_approves" + - "fastapi_backend/tests/api/test_approvals.py::test_a_flood_of_approvals_is_capped_per_automation" + - "fastapi_backend/tests/api/test_approvals.py::test_undecided_approvals_expire_and_nothing_runs" + - "fastapi_backend/tests/api/test_approvals_chat.py::test_a_yes_in_my_chat_decides_an_action_inside_lens" + - "fastapi_backend/tests/api/test_approvals_chat.py::test_an_action_reaching_outside_lens_is_decided_on_its_card" + - "fastapi_backend/tests/api/test_approvals_chat.py::test_with_two_waiting_a_bare_yes_names_them_and_a_number_picks_one" + - "fastapi_backend/tests/api/test_approvals_chat.py::test_a_yes_counts_only_from_someone_let_in_to_approve" - id: P-INJECTION-EGRESS kind: confidentiality components: [assistant] @@ -1785,6 +1812,14 @@ properties_claimed: violation_symptoms: [info-leak] x-voided-by: "ai.untrusted_asks: false (domain/ai_tools.py:519); bridge.safe_links: false (domain/bridge.py:298); notes and memories are written at once; hooks run as their owners set them (P-EXT-SCOPE); an address the read text wrote itself stays linkable in a room; the person's browser asks first as P-BROWSER-GUARD says" provenance: {kind: documented, source: 'docs/assistant.md "it read out of Lens waits for your approval"'} + x-tests-note: "an automation's ask_model, call_tool and ask_agent, and saved variables" + x-tests: + - "fastapi_backend/tests/api/test_actions_ai.py::test_prompts_mark_what_the_run_read_from_outside_lens_as_data" + - "fastapi_backend/tests/api/test_actions_ai.py::test_an_agent_with_nobody_reading_along_asks_before_anything_goes_out" + - "fastapi_backend/tests/api/test_actions_ai.py::test_call_tool_reads_as_the_person_and_changes_only_by_asking_them" + - "fastapi_backend/tests/api/test_actions_ai.py::test_ask_agent_works_on_what_happened_and_saves_the_conversation" + - "fastapi_backend/tests/domain/test_automation_nodes.py::test_prompts_mark_outside_text_and_template_defaults_are_filled_in" + - "fastapi_backend/tests/api/test_automation_vars.py::test_runs_read_their_own_and_their_namespace_s_variables" - id: P-EXT-SCOPE kind: integrity components: [assistant] @@ -1964,14 +1999,24 @@ properties_claimed: violation_symptoms: [integrity-bypass] x-voided-by: "an admin manages every automation and can run one now on any activity in its namespaces its person may see (api/v1/routes/automations.py); a node set to auto acts on outside text without asking (P-INJECTION-EGRESS still applies)" provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} + x-tests: + - "fastapi_backend/tests/domain/test_automation_runs.py::test_what_a_run_does_is_caused_by_it_and_acts_for_its_person" + - "fastapi_backend/tests/domain/test_automation_runs.py::test_a_person_who_lost_access_stops_their_automation" + - "fastapi_backend/tests/domain/test_automation_runs.py::test_the_guards_leave_activities_out" + - "fastapi_backend/tests/api/test_automations.py::test_only_the_person_lets_a_node_run_on_its_own" + - "fastapi_backend/tests/api/test_automation_tools.py::test_the_assistant_saves_at_once_and_asks_to_switch_on_or_run" - id: P-AUTOMATION-LOOP kind: correctness components: [assistant] tier: correctness-only - conditions: "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly" + conditions: "activities an automation made start another only with from_automations; a chain stops at automations.max_depth runs (3); each automation has a cooldown and a most runs an hour (60) under a most runs a minute for all (60); a run over a limit does nothing, is counted and logged at most hourly; an automation has at most 1000 timers waiting; setting more is refused" violation_symptoms: [x-cap-exceeded] x-voided-by: "fixed hour and minute windows let up to twice a limit run across the turn of one; an admin can raise max_depth to 10 and max_runs_per_minute to 6000" provenance: {kind: documented, source: 'docs/automations.md "Running automations"'} + x-tests: + - "fastapi_backend/tests/domain/test_automation_runs.py::test_the_guards_leave_activities_out" + - "fastapi_backend/tests/domain/test_automation_runs.py::test_the_if_limits_and_dry_runs" + - "fastapi_backend/tests/domain/test_timers.py::test_an_automation_has_at_most_so_many_timers_waiting" - id: P-BROWSER kind: integrity components: [assistant]