feat(orchestrator): firewall view with signed settings changes (001 S6)
Requirement 001 S6: the hub gets a Firewall view of the Claude Code permission and sandbox settings. The operator signs each change with the passkey; a host settings writer (systemd path unit) applies only exact, signed changes to allowlisted settings files through O_NOFOLLOW directory and file descriptors, and a timer refreshes the view. Every signed text and every page sink refuses or marks hidden characters: Cc, Cf, Zl, Zp, every space but U+0020 and the Default_Ignorable set, with U+FE0E/U+FE0F allowed only after one of the 359 non-ASCII emoji bases of Unicode 16 (shared table, validated at import, the same pair rule on the page). Removal of a deny, ask or denyRead entry is exempt only as an exact single remove. The permission hook prints the hub's refusal reason, cleaned of hidden characters. Accepted MEDUSA false positives (independent review, operator pick): 38 this round, mainly the Unicode defence tables read as attack patterns, generic MM-SCAN-058 heuristics, WEB-FLASK-004 at view.py:213 (ints from the validated table via tojson), EXF26-TOOL-004 on the non-secret WebAuthn challenge, PRIV-SCAN-060 on the office-action shape check and PQC007 on a picker key. 🎯 Fix: 95 % 💥 Break: 3 % 💸 Cost: – ⏱️ Time: – 🛡️ Security: 100 % 🏆 Score: 92 🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
3418738993
commit
9742884308
54 files changed
+3920
-168
No files matched your search
@@ -1,10 +1,12 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import base64
|
||||
import copy
|
||||
import fnmatch
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
import unicodedata
|
||||
from pathlib import Path
|
||||
|
||||
RP_ID = "localhost"
|
||||
@@ -35,6 +37,28 @@ GATE_BRANCH = re.compile(r"(?![-/])(?!.*\.\.)(?!.*@\{)(?!.*//)[^\x00-\x20\x7f~^:
|
||||
TOKEN_FREE_MERGE = "ancestor"
|
||||
APPROVAL_KEYS = {"v", "kind", "items", "nonce", "expires"}
|
||||
RULE_KEYS = {"v", "kind", "id", "kinds", "tool", "pattern", "scope", "expires"}
|
||||
TARGET = "agents"
|
||||
ALL_AGENTS = "*"
|
||||
AGENT_LIMIT = 50
|
||||
SETTINGS_FILE = "/.claude/settings.json"
|
||||
SETTINGS_KEYS = ("file", "base", "changes")
|
||||
SETTINGS_SECTIONS = ("permissions", "sandbox")
|
||||
SETTINGS_LISTS = ("permissions.allow", "permissions.ask", "permissions.deny", "sandbox.filesystem.allowWrite", "sandbox.filesystem.denyRead", "sandbox.network.allowedDomains")
|
||||
SETTINGS_OPS = ("add", "remove")
|
||||
CHANGE_KEYS = ("list", "op", "entry")
|
||||
CHANGE_LIMIT = 50
|
||||
ENTRY = re.compile(r"(?=[^\x00-\x1f\x7f\ud800-\udfff]*\S)[^\x00-\x1f\x7f\ud800-\udfff]{1,500}")
|
||||
SETTINGS_PATH = re.compile(r"/[^\x00-\x1f\x7f\ud800-\udfff]{0,4095}")
|
||||
SURROGATE = re.compile(r"[\ud800-\udfff]")
|
||||
UNSEEN = ("Cc", "Cf", "Zl", "Zp")
|
||||
DEFAULT_IGNORABLE = ((0xAD, 0xAD), (0x34F, 0x34F), (0x61C, 0x61C), (0x115F, 0x1160), (0x17B4, 0x17B5), (0x180B, 0x180F), (0x200B, 0x200F), (0x202A, 0x202E), (0x2060, 0x206F), (0x3164, 0x3164), (0xFE00, 0xFE0F), (0xFEFF, 0xFEFF), (0xFFA0, 0xFFA0), (0xFFF0, 0xFFF8), (0x1BCA0, 0x1BCA3), (0x1D173, 0x1D17A), (0xE0000, 0xE0FFF))
|
||||
IGNORABLE = frozenset(code for start, end in DEFAULT_IGNORABLE for code in range(start, end + 1))
|
||||
EMOJI_TABLE = Path(__file__).with_name("emoji-variation.json")
|
||||
HEX_CODE = re.compile(r"[0-9A-F]{4,6}")
|
||||
PRESENTATION = (chr(0xFE0E), chr(0xFE0F))
|
||||
FREE_TEXT = ("command", "text", "reason", "question", "description")
|
||||
BREAKS = "\t\n"
|
||||
DEPTH_LIMIT = 64
|
||||
WARNINGS = (
|
||||
("deletes recursively", re.compile(r"\brm\s+(?:-\S+\s+)*-\S*[rR]")),
|
||||
("forces", re.compile(r"--force\b|\bpush\b.*\s-f\b")),
|
||||
@@ -280,6 +304,283 @@ def rule_payload(rule_id: str, kinds: list[str], tool: str, pattern: str, scope:
|
||||
return {"v": VERSION, "kind": "rule", "id": rule_id, "kinds": kinds, "tool": tool, "pattern": pattern, "scope": scope, "expires": expires}
|
||||
|
||||
|
||||
def targeted(rule: dict, agents: list[str]) -> dict:
|
||||
"""Args:
|
||||
rule: a rule_payload().
|
||||
agents: [ALL_AGENTS], or the sorted session ids of one agent or of a
|
||||
named group, resolved when the operator signs.
|
||||
|
||||
Returns:
|
||||
The rule payload limited to those agents.
|
||||
"""
|
||||
return {**rule, TARGET: agents}
|
||||
|
||||
|
||||
def enable_item(rule: dict) -> dict:
|
||||
"""Args:
|
||||
rule: the signed payload of a stored rule.
|
||||
|
||||
Returns:
|
||||
The item a fresh approval lists to turn exactly that rule on again.
|
||||
"""
|
||||
return {"kind": "enable", "rule": rule}
|
||||
|
||||
|
||||
def agents_problem(agents: object) -> str | None:
|
||||
"""Returns:
|
||||
Why agents is neither [ALL_AGENTS] nor 1 to AGENT_LIMIT sorted,
|
||||
distinct session ids, or None.
|
||||
"""
|
||||
if agents == [ALL_AGENTS]:
|
||||
return None
|
||||
if not isinstance(agents, list) or not 1 <= len(agents) <= AGENT_LIMIT or not all(isinstance(agent, str) and SESSION.fullmatch(agent) for agent in agents):
|
||||
return f'agents must be ["{ALL_AGENTS}"] or 1 to {AGENT_LIMIT} session ids'
|
||||
return None if agents == sorted(set(agents)) else "agents must be sorted and distinct"
|
||||
|
||||
|
||||
def checked_target(rule: dict) -> None:
|
||||
"""Raises:
|
||||
Refused when the rule carries agents that agents_problem() refuses.
|
||||
"""
|
||||
problem = agents_problem(rule[TARGET]) if TARGET in rule else None
|
||||
if problem:
|
||||
raise Refused(f"the rule names no target: {problem}")
|
||||
|
||||
|
||||
def item_sessions(item: dict) -> set[str]:
|
||||
"""Returns:
|
||||
The session an ask comes from; empty for every other item, which
|
||||
names none.
|
||||
"""
|
||||
return {item["session"]} if item["kind"] == "ask" else set()
|
||||
|
||||
|
||||
def reaches(rule: dict, sessions: set[str]) -> bool:
|
||||
"""Args:
|
||||
rule: a checked rule payload.
|
||||
sessions: the sessions the item comes from; empty when the item names
|
||||
none, which only a rule for every agent reaches.
|
||||
|
||||
Returns:
|
||||
True when the rule carries no agents or [ALL_AGENTS], or names one of
|
||||
the sessions.
|
||||
"""
|
||||
return TARGET not in rule or rule[TARGET] == [ALL_AGENTS] or bool(sessions & set(rule[TARGET]))
|
||||
|
||||
|
||||
def settings_item(file: str, base: str, changes: list[dict]) -> dict:
|
||||
return {"kind": "settings", "file": file, "base": base, "changes": changes}
|
||||
|
||||
|
||||
def unseen(char: str) -> bool:
|
||||
"""Returns:
|
||||
True for a character no prompt shows as itself: a category of UNSEEN,
|
||||
a space separator other than the space, or a code point of
|
||||
DEFAULT_IGNORABLE; page-reveal.js marks the same set.
|
||||
"""
|
||||
category = unicodedata.category(char)
|
||||
return category in UNSEEN or (category == "Zs" and char != " ") or ord(char) in IGNORABLE
|
||||
|
||||
|
||||
def emoji_base(code: int) -> bool:
|
||||
return 0x7F < code <= 0x10FFFF and not 0xD800 <= code <= 0xDFFF and not unseen(chr(code))
|
||||
|
||||
|
||||
def variation_table(path: Path) -> frozenset[int]:
|
||||
"""Args:
|
||||
path: the emoji variation table, a JSON object whose bases list the
|
||||
hex code points of emoji-variation-sequences.txt.
|
||||
|
||||
Returns:
|
||||
The bases as code points.
|
||||
|
||||
Raises:
|
||||
ValueError when bases is no list of hex strings, or names an ASCII
|
||||
code point, a surrogate or one unseen() names; like a missing file,
|
||||
this stops the module from loading, so no selector is ever accepted
|
||||
after an unchecked base.
|
||||
"""
|
||||
bases = json.loads(path.read_text(encoding="utf-8"))["bases"]
|
||||
if not isinstance(bases, list) or not all(isinstance(code, str) and HEX_CODE.fullmatch(code) for code in bases):
|
||||
raise ValueError(f"{path}: bases must be a list of hex code points")
|
||||
codes = frozenset(int(code, 16) for code in bases)
|
||||
wrong = sorted(code for code in codes if not emoji_base(code))
|
||||
if wrong:
|
||||
raise ValueError(f"{path}: U+{wrong[0]:04X} is no visible non-ASCII emoji base")
|
||||
return codes
|
||||
|
||||
|
||||
EMOJI_BASES = variation_table(EMOJI_TABLE)
|
||||
|
||||
|
||||
def presented(text: str, index: int) -> bool:
|
||||
"""Returns:
|
||||
True when text[index] is a variation selector of PRESENTATION right
|
||||
after a code point of EMOJI_BASES, a standardized emoji variation
|
||||
sequence such as the stopwatch of the score block that every prompt
|
||||
draws as the symbol itself; page-reveal.js skips the same pairs.
|
||||
"""
|
||||
return text[index] in PRESENTATION and index > 0 and ord(text[index - 1]) in EMOJI_BASES
|
||||
|
||||
|
||||
def hidden_char(text: str, name: str) -> str | None:
|
||||
"""Returns:
|
||||
The first character of text that unseen() names, a tab or a line
|
||||
break only outside the FREE_TEXT fields, and no presented() selector;
|
||||
None when there is none.
|
||||
"""
|
||||
allowed = BREAKS if name in FREE_TEXT else ""
|
||||
return next((char for index, char in enumerate(text) if unseen(char) and char not in allowed and not presented(text, index)), None)
|
||||
|
||||
|
||||
def removal(value: dict) -> bool:
|
||||
return set(value) == set(CHANGE_KEYS) and value["op"] == "remove" and value["list"] in SETTINGS_LISTS
|
||||
|
||||
|
||||
def hidden_problem(value: object, name: str) -> str | None:
|
||||
"""Args:
|
||||
value: a text, or an object or list of them, that reaches a signed
|
||||
payload or the approval prompt; an object's texts are named by
|
||||
their keys. Only the entry of a settings change of op remove is
|
||||
exempt: removing an allow entry narrows access, but removing a
|
||||
deny, ask or denyRead entry widens it, and that is safe only
|
||||
because the writer removes exactly the signed text and the page
|
||||
marks every character unseen() names.
|
||||
name: the field a text sits in.
|
||||
|
||||
Returns:
|
||||
Why the first text holding a character unseen() names (a bidi
|
||||
control, a zero-width character, a carriage return, a no-break space,
|
||||
a Hangul filler) is refused, since the prompt would show other text
|
||||
than what is signed; None when no text holds one.
|
||||
"""
|
||||
if isinstance(value, dict):
|
||||
named = {key: child for key, child in value.items() if not (key == "entry" and removal(value))}
|
||||
return next(filter(None, (hidden_problem(child, str(key)) for key, child in named.items())), None)
|
||||
if isinstance(value, list):
|
||||
return next(filter(None, (hidden_problem(child, name) for child in value)), None)
|
||||
hidden = hidden_char(value, name) if isinstance(value, str) else None
|
||||
return None if hidden is None else f"{name} must hold no invisible, format, control or look-alike character such as U+{ord(hidden):04X}, which shows other text than what is signed"
|
||||
|
||||
|
||||
def settings_file_problem(file: object) -> str | None:
|
||||
if not isinstance(file, str) or not SETTINGS_PATH.fullmatch(file) or not file.endswith(SETTINGS_FILE):
|
||||
return f"file must be the absolute path of a {SETTINGS_FILE.lstrip('/')}"
|
||||
if any(part in f"{file}/" for part in ("/../", "/./", "//")):
|
||||
return "file must name no . or .. and no empty part"
|
||||
return hidden_problem(file, "file")
|
||||
|
||||
|
||||
def change_problem(change: object) -> str | None:
|
||||
if not isinstance(change, dict) or set(change) != set(CHANGE_KEYS) or not all(isinstance(change[name], str) for name in CHANGE_KEYS):
|
||||
return "a change holds exactly list, op and entry as text"
|
||||
if change["list"] not in SETTINGS_LISTS or change["op"] not in SETTINGS_OPS:
|
||||
return f"list must be one of {', '.join(SETTINGS_LISTS)} and op one of {', '.join(SETTINGS_OPS)}"
|
||||
return hidden_problem(change, "change") if ENTRY.fullmatch(change["entry"]) else "entry must be one line of 1 to 500 characters"
|
||||
|
||||
|
||||
def settings_problem(item: object) -> str | None:
|
||||
"""Args:
|
||||
item: {"file", "base", "changes"}: file the absolute path of a
|
||||
.claude/settings.json, base the sha256 of its bytes or "" while it
|
||||
is missing, changes 1 to CHANGE_LIMIT {"list", "op", "entry"},
|
||||
each list and entry once.
|
||||
|
||||
Returns:
|
||||
Why the item is malformed, or None; the hub and the writer check it
|
||||
the same way.
|
||||
"""
|
||||
if not isinstance(item, dict) or set(item) != set(SETTINGS_KEYS):
|
||||
return "a settings change holds exactly file, base and changes"
|
||||
if not isinstance(item["base"], str) or not (item["base"] == "" or HASH.fullmatch(item["base"])):
|
||||
return "base must be the sha256 of the file, or empty for a missing file"
|
||||
return settings_file_problem(item["file"]) or changes_problem(item["changes"])
|
||||
|
||||
|
||||
def changes_problem(changes: object) -> str | None:
|
||||
if not isinstance(changes, list) or not 1 <= len(changes) <= CHANGE_LIMIT:
|
||||
return f"changes must list 1 to {CHANGE_LIMIT} changes"
|
||||
problem = next(filter(None, map(change_problem, changes)), None)
|
||||
if problem:
|
||||
return problem
|
||||
pairs = {(change["list"], change["entry"]) for change in changes}
|
||||
return None if len(pairs) == len(changes) else "each list and entry is changed once"
|
||||
|
||||
|
||||
def settings_view(settings: dict) -> dict:
|
||||
"""Returns:
|
||||
The permissions and sandbox sections of a settings object, the only
|
||||
part of the file the Agent Orchestrator receives.
|
||||
"""
|
||||
return {name: settings[name] for name in SETTINGS_SECTIONS if isinstance(settings.get(name), dict)}
|
||||
|
||||
|
||||
def plain_problem(value: object, depth: int) -> str | None:
|
||||
"""Args:
|
||||
value: a parsed JSON value.
|
||||
depth: how many objects and lists hold it.
|
||||
|
||||
Returns:
|
||||
Why value is unsafe to copy or write, a lone surrogate in any text or
|
||||
more than DEPTH_LIMIT levels, or None.
|
||||
"""
|
||||
if isinstance(value, str):
|
||||
return "the file holds a lone surrogate" if SURROGATE.search(value) else None
|
||||
if not isinstance(value, (dict, list)):
|
||||
return None
|
||||
if depth >= DEPTH_LIMIT:
|
||||
return f"the file nests deeper than {DEPTH_LIMIT} levels"
|
||||
children = [*value, *value.values()] if isinstance(value, dict) else value
|
||||
return next(filter(None, (plain_problem(child, depth + 1) for child in children)), None)
|
||||
|
||||
|
||||
def plain_copy(settings: dict) -> dict:
|
||||
"""Raises:
|
||||
Refused for settings plain_problem() refuses, before deepcopy could
|
||||
recurse into them.
|
||||
"""
|
||||
problem = plain_problem(settings, 0)
|
||||
if problem:
|
||||
raise Refused(problem)
|
||||
return copy.deepcopy(settings)
|
||||
|
||||
|
||||
def apply_changes(settings: dict, changes: list[dict]) -> dict:
|
||||
"""Args:
|
||||
settings: the parsed settings object.
|
||||
changes: changes settings_problem() accepts.
|
||||
|
||||
Returns:
|
||||
A copy of settings with each change applied in order and every other
|
||||
key kept.
|
||||
|
||||
Raises:
|
||||
Refused when settings nest deeper than DEPTH_LIMIT or hold a lone
|
||||
surrogate, an object on a list's path is no object, a list holds
|
||||
anything but text, an added entry is listed already or a removed one
|
||||
is not.
|
||||
"""
|
||||
result = plain_copy(settings)
|
||||
for change in changes:
|
||||
*path, leaf = change["list"].split(".")
|
||||
node = result
|
||||
for name in path:
|
||||
node = node.setdefault(name, {})
|
||||
if not isinstance(node, dict):
|
||||
raise Refused(f"{name} is no object")
|
||||
entries = node.setdefault(leaf, [])
|
||||
if not isinstance(entries, list) or not all(isinstance(entry, str) for entry in entries):
|
||||
raise Refused(f"{change['list']} is no list of texts")
|
||||
listed = change["entry"] in entries
|
||||
if listed == (change["op"] == "add"):
|
||||
raise Refused(f"{change['list']} {'lists' if listed else 'does not list'} {change['entry']}")
|
||||
if listed:
|
||||
entries.remove(change["entry"])
|
||||
else:
|
||||
entries.append(change["entry"])
|
||||
return result
|
||||
|
||||
|
||||
def warnings(command: str) -> list[str]:
|
||||
return [label for label, pattern in WARNINGS if pattern.search(command)]
|
||||
|
||||
@@ -307,8 +608,9 @@ def checked_approval(payload: object, now: float) -> dict:
|
||||
|
||||
|
||||
def checked_rule(payload: object, now: float) -> dict:
|
||||
if not isinstance(payload, dict) or set(payload) != RULE_KEYS or payload["v"] != VERSION or payload["kind"] != "rule":
|
||||
if not isinstance(payload, dict) or set(payload) - {TARGET} != RULE_KEYS or payload["v"] != VERSION or payload["kind"] != "rule":
|
||||
raise Refused("the payload is no rule")
|
||||
checked_target(payload)
|
||||
if not isinstance(payload["id"], str) or not ID.fullmatch(payload["id"]):
|
||||
raise Refused("the rule holds no id")
|
||||
kinds = payload["kinds"]
|
||||
@@ -321,6 +623,10 @@ def checked_rule(payload: object, now: float) -> dict:
|
||||
|
||||
|
||||
def rule_allows(rule: dict, item: dict, gate: str, now: float) -> bool:
|
||||
return reaches(rule, item_sessions(item)) and pattern_allows(rule, item, gate, now)
|
||||
|
||||
|
||||
def pattern_allows(rule: dict, item: dict, gate: str, now: float) -> bool:
|
||||
if rule["expires"] <= now or item["kind"] not in rule["kinds"]:
|
||||
return False
|
||||
if item["kind"] == "ask":
|
||||
|
||||
Reference in new issue
Block a user