Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/threat-model.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
29 changes: 29 additions & 0 deletions ci/test_validate_threat_model.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
38 changes: 37 additions & 1 deletion ci/validate_threat_model.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -40,6 +41,13 @@
)
Q_RE = re.compile(r"(?<![A-Za-z0-9_-])Q(\d+)(?![0-9])")
ROW_RE = re.compile(r"^\|\s*((?:P|N|KNF)-[A-Z0-9-]+)\s*\|", re.MULTILINE)
# A cited test: path::test in the companions, `path` `test`, `test` in the prose. Paths are from the repository root.
TEST_REF_RE = re.compile(
r"(?P<path>fastapi_backend/tests/[\w/]+\.py)::(?P<test>test_\w+)"
)
TEST_LIST_RE = re.compile(
r"`(?P<path>fastapi_backend/tests/[\w/]+\.py)`(?P<tests>(?:,? `test_\w+`)+)"
)

YAML_KEYS = (
"schema prose_version components entry_points adversaries properties_claimed properties_disclaimed "
Expand Down Expand Up @@ -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)]
Expand Down
70 changes: 61 additions & 9 deletions threat-model.json
Original file line number Diff line number Diff line change
Expand Up @@ -574,7 +574,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)",
Expand Down Expand Up @@ -709,7 +716,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",
Expand Down Expand Up @@ -1266,7 +1277,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; a workflow's HTTP call node by admins, with its host written out; 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; a workflow's HTTP call node seals credential headers to their header and host and never sends them to another server, reads 200,000 characters at most, and passes the answer on marked 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",
Expand Down Expand Up @@ -1314,15 +1332,37 @@
"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",
"violation_symptom": "info-leak",
"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",
Expand Down Expand Up @@ -1498,15 +1538,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",
Expand Down
Loading
Loading