@yahyahammad/venastine 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- package/tui/widgets.py +1239 -0
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
"""
|
|
2
|
+
security/capability.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §28. The generic half of the shell approval gate: what a call
|
|
5
|
+
is able to do (`CommandProfile`), what the harness can confine it to
|
|
6
|
+
(`CONTAINED` / `UNCONTAINED` / `UNAVAILABLE`), and the one rule that turns
|
|
7
|
+
those two into "does a human have to say yes".
|
|
8
|
+
|
|
9
|
+
Nothing here knows what a shell command is. That is deliberate (G2):
|
|
10
|
+
`write`, `edit` and MCP tools have the same shape of question -- this call
|
|
11
|
+
can reach these things, and the harness can confine it this far -- and the
|
|
12
|
+
audit found the same defect (#67/#133) twice already by letting each site
|
|
13
|
+
answer it separately. The SHELL-specific part, deciding which capabilities
|
|
14
|
+
a particular command string has, lives in security/sandbox.py.
|
|
15
|
+
|
|
16
|
+
Note the direction of the dependency: sandbox.py imports this module, not
|
|
17
|
+
the other way round. A second producer of profiles must not have to import
|
|
18
|
+
the shell sandbox to describe a file write.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
from dataclasses import dataclass
|
|
24
|
+
|
|
25
|
+
# ---------------------------------------------------------------------------
|
|
26
|
+
# ---- Containment ----------------------------------------------------------
|
|
27
|
+
# ---------------------------------------------------------------------------
|
|
28
|
+
|
|
29
|
+
# How far the harness can confine a call it is about to make. Three values,
|
|
30
|
+
# not a boolean, because "cannot run this at all" is a real third answer and
|
|
31
|
+
# it changes what the gate should do: asking about a call that is going to
|
|
32
|
+
# fail regardless burns a turn and teaches the model to retry.
|
|
33
|
+
CONTAINED = "contained" # confined to the workspace (a Docker container)
|
|
34
|
+
UNCONTAINED = "uncontained" # runs with the user's own authority (host)
|
|
35
|
+
UNAVAILABLE = "unavailable" # no backend can run it
|
|
36
|
+
|
|
37
|
+
# ---------------------------------------------------------------------------
|
|
38
|
+
# ---- Approval modes -------------------------------------------------------
|
|
39
|
+
# ---------------------------------------------------------------------------
|
|
40
|
+
|
|
41
|
+
ALWAYS = "always"
|
|
42
|
+
TIERED = "tiered"
|
|
43
|
+
NEVER = "never"
|
|
44
|
+
|
|
45
|
+
APPROVAL_MODES = (ALWAYS, TIERED, NEVER)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def validate_mode(value: str, setting_name: str) -> str:
|
|
49
|
+
"""Return *value*, or raise if it is not an approval mode.
|
|
50
|
+
|
|
51
|
+
Called at IMPORT time by whoever owns the setting, which is D24's
|
|
52
|
+
posture applied to a value rather than a field: a typo in a security
|
|
53
|
+
setting must not be resolved by falling back to a default. The two
|
|
54
|
+
directions a typo can fail are not symmetric -- silently reading
|
|
55
|
+
`"teired"` as anything other than an error either asks about
|
|
56
|
+
everything (annoying, visible) or asks about nothing (catastrophic,
|
|
57
|
+
invisible), and there is no way to pick a default that is safe under
|
|
58
|
+
both readings. So there is no default.
|
|
59
|
+
"""
|
|
60
|
+
if value not in APPROVAL_MODES:
|
|
61
|
+
raise ValueError(
|
|
62
|
+
f"{setting_name} must be one of {', '.join(APPROVAL_MODES)}, "
|
|
63
|
+
f"got {value!r}")
|
|
64
|
+
return value
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
# ---------------------------------------------------------------------------
|
|
68
|
+
# ---- Capability profile ---------------------------------------------------
|
|
69
|
+
# ---------------------------------------------------------------------------
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass(frozen=True)
|
|
73
|
+
class CommandProfile:
|
|
74
|
+
"""What one call is able to do, as a capability SET rather than a
|
|
75
|
+
trust level (G1).
|
|
76
|
+
|
|
77
|
+
A linear tier ordering was the obvious design and it is wrong here,
|
|
78
|
+
because it orders harms that are not comparable: `rm -rf /workspace`
|
|
79
|
+
(writes, no network) and `curl https://x` (no writes, network) are
|
|
80
|
+
different harms, not more and less of one thing. Ranking them forces
|
|
81
|
+
an answer to a question nobody asked, and a new dimension later
|
|
82
|
+
renumbers every tier. A set lets policy read exactly the dimension it
|
|
83
|
+
cares about and lets a dimension arrive without touching the others.
|
|
84
|
+
|
|
85
|
+
`tier` survives as a LABEL -- it names the profile for the approval
|
|
86
|
+
prompt and the record, and nothing branches on it. If you find
|
|
87
|
+
yourself writing `if profile.tier == ...` in policy, the field you
|
|
88
|
+
actually wanted is missing.
|
|
89
|
+
|
|
90
|
+
Every field is an UPPER BOUND. `writes` means "not known to be
|
|
91
|
+
read-only", not "will write" -- knowing which would mean parsing the
|
|
92
|
+
command, and refusing to parse is the property that makes the
|
|
93
|
+
classifier sound (G2).
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
tier: str
|
|
97
|
+
# Whether the classifier could characterise this call AT ALL.
|
|
98
|
+
#
|
|
99
|
+
# A separate dimension from the capabilities, and the one the `tier`
|
|
100
|
+
# label was standing in for: "read-only, nothing leaves the workspace"
|
|
101
|
+
# and "we could not tell" are different claims, and only the first is
|
|
102
|
+
# a reason to skip a human. Without this field the containment
|
|
103
|
+
# argument silently covers the second -- an unmeasurable call inside a
|
|
104
|
+
# network-less container satisfies every capability test by returning
|
|
105
|
+
# False to all of them, which is the vacuity class this audit keeps
|
|
106
|
+
# finding: a check that passes because its input was empty.
|
|
107
|
+
#
|
|
108
|
+
# It is also what batch 9 needs. A model-based classifier's "I am not
|
|
109
|
+
# sure" has to land somewhere that cannot be argued away by
|
|
110
|
+
# containment, and this is that place.
|
|
111
|
+
measured: bool
|
|
112
|
+
# Some argument resolves outside the workspace. Only meaningful where
|
|
113
|
+
# the workspace is the boundary -- under CONTAINED the container's
|
|
114
|
+
# filesystem is not the host's, so this says nothing useful there.
|
|
115
|
+
escapes_workspace: bool
|
|
116
|
+
# Not known to be read-only.
|
|
117
|
+
writes: bool
|
|
118
|
+
# The sandbox will GRANT this call network access. One fact for both
|
|
119
|
+
# consumers, deliberately: the executor uses it to decide whether to
|
|
120
|
+
# pass `--network`, and the gate uses it to decide whether to ask.
|
|
121
|
+
# Splitting it into a permissive routing answer and a pessimistic
|
|
122
|
+
# approval answer is exactly the shape of #67/#133 -- sharing the
|
|
123
|
+
# mechanism is not sharing the policy -- inside the module written to
|
|
124
|
+
# close that.
|
|
125
|
+
network: bool
|
|
126
|
+
# Why the classifier said what it said. Shown in the approval prompt,
|
|
127
|
+
# so it is written for the person answering it, not for a log.
|
|
128
|
+
reason: str
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
# ---------------------------------------------------------------------------
|
|
132
|
+
# ---- The rule -------------------------------------------------------------
|
|
133
|
+
# ---------------------------------------------------------------------------
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def auto_approved(profile: CommandProfile, containment: str) -> bool:
|
|
137
|
+
"""Whether *profile* is covered by *containment* without asking anyone.
|
|
138
|
+
|
|
139
|
+
One branch per containment, rather than one predicate ANDed across
|
|
140
|
+
all of them, because the dimensions that matter genuinely differ:
|
|
141
|
+
|
|
142
|
+
CONTAINED the container bounds the filesystem, so
|
|
143
|
+
`escapes_workspace` says nothing -- `cat /etc/passwd`
|
|
144
|
+
in a container reads the container's. What the
|
|
145
|
+
container does NOT bound is egress, and that is the
|
|
146
|
+
half the pre-§28 gate never looked at (#157 hole 2).
|
|
147
|
+
|
|
148
|
+
UNCONTAINED nothing is bounded, so everything must be clear: no
|
|
149
|
+
argument leaving the workspace (#157 hole 1), nothing
|
|
150
|
+
that might write, no network.
|
|
151
|
+
|
|
152
|
+
UNAVAILABLE the call cannot run, so it is not covered either.
|
|
153
|
+
Note this is NOT "do not ask": False here means ASK,
|
|
154
|
+
like every other False. A caller that would rather stay
|
|
155
|
+
silent about a call which is going to fail regardless
|
|
156
|
+
has to say so itself -- shell does, and the two
|
|
157
|
+
polarities meeting is worth the one explicit branch
|
|
158
|
+
rather than a second meaning smuggled into this return.
|
|
159
|
+
|
|
160
|
+
`measured` gates all three. A call the classifier could not
|
|
161
|
+
characterise must not be auto-approved by a containment argument,
|
|
162
|
+
because every capability test passes vacuously on a profile that
|
|
163
|
+
knows nothing.
|
|
164
|
+
|
|
165
|
+
This function reads no config and knows about no tool. A caller with
|
|
166
|
+
an explicit documented override (`AUTO_APPROVE_SANDBOX_FALLBACK` is
|
|
167
|
+
the only one today) applies it before calling here, where it is
|
|
168
|
+
visible, rather than passing a flag in to be honoured out of sight.
|
|
169
|
+
"""
|
|
170
|
+
if not profile.measured:
|
|
171
|
+
return False
|
|
172
|
+
if containment == CONTAINED:
|
|
173
|
+
return not profile.network
|
|
174
|
+
if containment == UNCONTAINED:
|
|
175
|
+
return not (profile.escapes_workspace or profile.writes
|
|
176
|
+
or profile.network)
|
|
177
|
+
return False
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
"""
|
|
2
|
+
security/permissions.py
|
|
3
|
+
|
|
4
|
+
POLICY, not mechanism: "may this tool be called at all?" and "does this
|
|
5
|
+
call need a human to approve it?". tools/registry.py owns dispatch
|
|
6
|
+
mechanics and is the only caller; tool modules never import this.
|
|
7
|
+
|
|
8
|
+
ROADMAP_v2 §15 adds the "stricter wins" rule (D14). Every currently
|
|
9
|
+
active layer is consulted -- the global config dataclasses, plus an
|
|
10
|
+
optional ToolContext contributed by the active agent (§18) and the skills
|
|
11
|
+
it has activated (§19):
|
|
12
|
+
|
|
13
|
+
* allow/deny is a logical AND -- a tool is available only if global
|
|
14
|
+
policy allows it AND every layer that expresses an opinion allows it.
|
|
15
|
+
A globally-disabled tool can never be re-enabled by a context; that
|
|
16
|
+
check runs first and unconditionally.
|
|
17
|
+
* approval is a logical OR -- approval is required if the global
|
|
18
|
+
setting says so, OR the context says so, OR (in the registry) the
|
|
19
|
+
tool's own dynamic approval_check says so. A context can therefore
|
|
20
|
+
tighten a lenient default but can never loosen a strict one.
|
|
21
|
+
|
|
22
|
+
ToolContext is imported for typing only. security/ must not gain a
|
|
23
|
+
runtime dependency on tools/ -- the real direction is tools -> security,
|
|
24
|
+
and inverting it would create a cycle the moment tools/context.py grows
|
|
25
|
+
an import of its own.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from typing import TYPE_CHECKING, Iterable, Optional
|
|
29
|
+
|
|
30
|
+
import config
|
|
31
|
+
|
|
32
|
+
if TYPE_CHECKING: # pragma: no cover - typing only, never imported at runtime
|
|
33
|
+
from tools.context import ToolContext
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _default_for_unknown_tool(tool_name: str) -> bool:
|
|
37
|
+
"""Explicit, named default for tools with no declared field, rather
|
|
38
|
+
than letting getattr's fallback decide by omission.
|
|
39
|
+
|
|
40
|
+
config.ToolPermissions is a static dataclass with one field per known
|
|
41
|
+
tool. MCP tools (§17) are named at connection time
|
|
42
|
+
(`mcp__<server>__<tool>`) and can never have a pre-declared field, so
|
|
43
|
+
a bare `getattr(..., False)` would deny every one of them forever.
|
|
44
|
+
They are allowed here because their real control point is the
|
|
45
|
+
server-level trust gate in §17. Anything else unknown is denied --
|
|
46
|
+
and for statically registered tools, omission is caught outright by
|
|
47
|
+
assert_permissions_declared() at import time (D24), so this branch
|
|
48
|
+
should be unreachable for them.
|
|
49
|
+
"""
|
|
50
|
+
return tool_name.startswith("mcp__")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _default_for_unknown_approval(tool_name: str) -> bool:
|
|
54
|
+
"""Approval counterpart to _default_for_unknown_tool.
|
|
55
|
+
|
|
56
|
+
MCP tools default to REQUIRING approval (§17 decision D). They are
|
|
57
|
+
allowed by default but not trusted by default, and those are different
|
|
58
|
+
questions: an MCP server is third-party code that the model can reach
|
|
59
|
+
without the user ever naming it. The project tier is trust-gated
|
|
60
|
+
(D17), but a user-level mcp.json auto-connects, and config files grow
|
|
61
|
+
entries that installers appended.
|
|
62
|
+
|
|
63
|
+
Everything else unknown defaults to not requiring approval, matching
|
|
64
|
+
the previous getattr fallback.
|
|
65
|
+
"""
|
|
66
|
+
return tool_name.startswith("mcp__")
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
# Base approval defaults for tools that cannot have a declared field --
|
|
70
|
+
# populated at connection time from each MCP server's `autoApprove`.
|
|
71
|
+
#
|
|
72
|
+
# This exists because the per-server opt-out CANNOT be expressed as a
|
|
73
|
+
# ToolSpec.approval_check: registry.approval_needed() ORs those in, and OR
|
|
74
|
+
# can only ever tighten. Varying the BASE DEFAULT instead keeps D14's
|
|
75
|
+
# one-way ratchet exactly intact -- a context override can still force
|
|
76
|
+
# approval back on for an auto-approved server, but nothing can wave a
|
|
77
|
+
# call past a gate a stricter layer set.
|
|
78
|
+
_dynamic_approval_defaults: dict = {}
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def set_dynamic_approval_default(tool_name: str, required: bool) -> None:
|
|
82
|
+
"""Declare the base approval default for a dynamically-named tool."""
|
|
83
|
+
_dynamic_approval_defaults[tool_name] = bool(required)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def clear_dynamic_approval_defaults(*names: str) -> None:
|
|
87
|
+
"""Drop defaults for tools that no longer exist. Idempotent, because
|
|
88
|
+
disconnect handling can run more than once for the same server. With
|
|
89
|
+
no arguments, drops all of them.
|
|
90
|
+
|
|
91
|
+
Names are EXACT. This took a PREFIX until §14-§18 review finding f8,
|
|
92
|
+
which is the same over-match hazard `mcp__<server>__<tool>` has one
|
|
93
|
+
layer up and for the same reason -- neither `__` in a server name nor
|
|
94
|
+
`__` in a tool name is illegal. Clearing "mcp__fs__read" by prefix
|
|
95
|
+
also cleared "mcp__fs__read_file", silently returning a live tool to
|
|
96
|
+
the approval-required default (or, for an auto-approved server, to
|
|
97
|
+
requiring approval it was configured not to need).
|
|
98
|
+
"""
|
|
99
|
+
if not names:
|
|
100
|
+
_dynamic_approval_defaults.clear()
|
|
101
|
+
return
|
|
102
|
+
for name in names:
|
|
103
|
+
_dynamic_approval_defaults.pop(name, None)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def is_tool_allowed(
|
|
107
|
+
tool_name: str, context: Optional["ToolContext"] = None
|
|
108
|
+
) -> bool:
|
|
109
|
+
"""Should this tool be callable at all, given current policy?
|
|
110
|
+
|
|
111
|
+
Logical AND across layers. The global check is unconditional and
|
|
112
|
+
happens first: no agent or skill context can re-enable a tool that
|
|
113
|
+
config has disabled.
|
|
114
|
+
"""
|
|
115
|
+
permissions = config.ToolPermissions()
|
|
116
|
+
if not getattr(permissions, tool_name, _default_for_unknown_tool(tool_name)):
|
|
117
|
+
return False
|
|
118
|
+
if context is not None and context.allowed_tools is not None:
|
|
119
|
+
return tool_name in context.allowed_tools
|
|
120
|
+
return True
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def requires_approval(
|
|
124
|
+
tool_name: str, params: dict, context: Optional["ToolContext"] = None
|
|
125
|
+
) -> bool:
|
|
126
|
+
"""Does this specific call need a human to approve it before running?
|
|
127
|
+
|
|
128
|
+
Logical OR across layers, which is what makes approval_overrides a
|
|
129
|
+
one-way ratchet: a context entry can ADD an approval requirement, but
|
|
130
|
+
an entry of `False` is indistinguishable from the key being absent
|
|
131
|
+
and can never remove one. That asymmetry is D14's intent -- do not
|
|
132
|
+
"fix" it into a three-state override, or an agent definition (which
|
|
133
|
+
may come from a merely-trusted project directory) could wave a call
|
|
134
|
+
past a gate the global config deliberately set.
|
|
135
|
+
|
|
136
|
+
Note this function covers the global + context layers only. The
|
|
137
|
+
tool's own dynamic approval_check is OR'd in by
|
|
138
|
+
ToolRegistry.approval_needed(), which is the single source of truth
|
|
139
|
+
both dispatch() and the loop's permission bridge call.
|
|
140
|
+
"""
|
|
141
|
+
approvals = config.ToolApprovals()
|
|
142
|
+
if hasattr(approvals, tool_name):
|
|
143
|
+
tool_level = getattr(approvals, tool_name)
|
|
144
|
+
else:
|
|
145
|
+
# No declared field: a dynamically-named tool (§17). Its base
|
|
146
|
+
# default is whatever was registered for it, falling back to the
|
|
147
|
+
# named default rather than to bare False.
|
|
148
|
+
tool_level = _dynamic_approval_defaults.get(
|
|
149
|
+
tool_name, _default_for_unknown_approval(tool_name)
|
|
150
|
+
)
|
|
151
|
+
context_level = (
|
|
152
|
+
context.approval_overrides.get(tool_name, False)
|
|
153
|
+
if context is not None
|
|
154
|
+
else False
|
|
155
|
+
)
|
|
156
|
+
return tool_level or context_level
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def assert_permissions_declared(tool_names: Iterable[str]) -> None:
|
|
160
|
+
"""D24: every statically registered tool must have a field in BOTH
|
|
161
|
+
config dataclasses. Raises rather than warning, because the failure
|
|
162
|
+
this guards against is invisible at runtime.
|
|
163
|
+
|
|
164
|
+
The precedent is `fetch_url`: registered, documented as working, and
|
|
165
|
+
denied on every call for its entire life because nobody added the
|
|
166
|
+
field. Nothing logged and nothing raised -- the schema was still
|
|
167
|
+
advertised to the model, so it kept choosing the tool, and the only
|
|
168
|
+
trace was a denial string inside a tool result it then worked around.
|
|
169
|
+
Making omission MEANINGFUL for MCP tools (see
|
|
170
|
+
_default_for_unknown_tool) is exactly what makes it important that
|
|
171
|
+
omission is never accidental for built-in ones.
|
|
172
|
+
|
|
173
|
+
Dynamically-named `mcp__*` tools are exempt by design; they can never
|
|
174
|
+
have a declared field. Call this after static registration only.
|
|
175
|
+
"""
|
|
176
|
+
permissions = config.ToolPermissions()
|
|
177
|
+
approvals = config.ToolApprovals()
|
|
178
|
+
missing = [
|
|
179
|
+
name
|
|
180
|
+
for name in tool_names
|
|
181
|
+
if not name.startswith("mcp__")
|
|
182
|
+
and not (hasattr(permissions, name) and hasattr(approvals, name))
|
|
183
|
+
]
|
|
184
|
+
if missing:
|
|
185
|
+
raise RuntimeError(
|
|
186
|
+
"Tools are registered with no declared permission/approval "
|
|
187
|
+
f"field, so they would be silently denied forever: {sorted(missing)}. "
|
|
188
|
+
"Add a bool field for each to BOTH config.ToolPermissions and "
|
|
189
|
+
"config.ToolApprovals (ROADMAP_v2 §15, D24)."
|
|
190
|
+
)
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
"""
|
|
2
|
+
security/posture.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §40. The process's security posture, computed ONCE and frozen.
|
|
5
|
+
|
|
6
|
+
WHY THIS EXISTS, AND WHY IT IS NOT JUST `config`
|
|
7
|
+
------------------------------------------------
|
|
8
|
+
Every security flag in this project used to be read LIVE, at call time.
|
|
9
|
+
`tools/builtin/shell.py` said so in as many words:
|
|
10
|
+
|
|
11
|
+
Re-checked per call as well, because a test or a runtime edit can
|
|
12
|
+
change it after this line has run.
|
|
13
|
+
|
|
14
|
+
That comment describes a test seam and also describes an attack. A single
|
|
15
|
+
attribute assignment -- `config.SHELL_APPROVAL_MODE = "never"` -- turned
|
|
16
|
+
the shell gate off for the rest of the process, and anything that reaches
|
|
17
|
+
arbitrary in-process Python could make it. The module's own history has
|
|
18
|
+
the precedent: `tools/builtin/_math_common.py` exists because "an
|
|
19
|
+
expression string is code", and its docstring lists the escapes that were
|
|
20
|
+
found before the AST allowlist went in.
|
|
21
|
+
|
|
22
|
+
So the posture is bound once and frozen (UN1). The `config.py` constants
|
|
23
|
+
are still where a HUMAN writes the value; they simply stop being what is
|
|
24
|
+
read at the moment a decision is made.
|
|
25
|
+
|
|
26
|
+
WHAT THE GUARANTEE IS, AND IS NOT
|
|
27
|
+
---------------------------------
|
|
28
|
+
Stated precisely, because a half-understood control is worse than none
|
|
29
|
+
(UN4). The posture CANNOT be changed by:
|
|
30
|
+
|
|
31
|
+
* any tool call -- nothing writes `config.py` without an approval
|
|
32
|
+
prompt, since it is outside the workspace and `_file_approval_check`
|
|
33
|
+
hard-returns True there;
|
|
34
|
+
* `settings.json` at either tier -- the keys are rejected BY NAME, the
|
|
35
|
+
way G7 rejects `shell_approval_mode`, because a project's settings
|
|
36
|
+
beat the user's and arrive with a directory you cloned;
|
|
37
|
+
* an environment variable -- there is none, by design, and SECURITY.md
|
|
38
|
+
says so;
|
|
39
|
+
* model output, or a TUI slash command -- there is no posture command,
|
|
40
|
+
deliberately, because that is the one surface reachable after
|
|
41
|
+
untrusted content is already in the context window.
|
|
42
|
+
|
|
43
|
+
It CAN be changed by arbitrary in-process Python, which can also rebind
|
|
44
|
+
`current` itself. A frozen dataclass raises `FrozenInstanceError` where a
|
|
45
|
+
bare `config.X = ...` succeeded; that raises the bar without closing the
|
|
46
|
+
class, and pretending otherwise would be the "reads as safety without
|
|
47
|
+
being it" failure SECURITY.md already names for the insecure fallback.
|
|
48
|
+
|
|
49
|
+
ORDERING IS SELF-ENFORCING (UN2)
|
|
50
|
+
--------------------------------
|
|
51
|
+
`current()` marks the posture bound. `apply_cli()` raises if folding in
|
|
52
|
+
the command line would now CHANGE it. So a wrong call order in `main.py`
|
|
53
|
+
is a LOUD startup failure rather than a silently stale posture -- which
|
|
54
|
+
matters because the failure mode of getting it wrong is a run that
|
|
55
|
+
believes it is safer than it is, and that is invisible.
|
|
56
|
+
|
|
57
|
+
The predicate is "a change after a read", not "a read", and the
|
|
58
|
+
difference is not a softening. The guard exists to catch *something acted
|
|
59
|
+
on the config-only value*; if the command line produces the posture that
|
|
60
|
+
was already read, nobody anywhere saw a wrong value and there is nothing
|
|
61
|
+
to catch. Raising on the read alone was the first draft and it was wrong
|
|
62
|
+
twice: `tools/builtin/shell.py` validates the approval mode at import, so
|
|
63
|
+
every launch died in the guard, and `main()` became un-callable twice in
|
|
64
|
+
one interpreter, which the suite does constantly. A guard the tests have
|
|
65
|
+
to work around stops being read as a guard.
|
|
66
|
+
|
|
67
|
+
Never calling `apply_cli()` at all -- a library import, a bare test --
|
|
68
|
+
leaves the config-derived default, which is the safe posture.
|
|
69
|
+
|
|
70
|
+
This module imports `config` and the stdlib and nothing else, per
|
|
71
|
+
ARCHITECTURE's rule for `security/`.
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
from __future__ import annotations
|
|
75
|
+
|
|
76
|
+
import contextlib
|
|
77
|
+
import dataclasses
|
|
78
|
+
import os
|
|
79
|
+
from dataclasses import dataclass
|
|
80
|
+
from typing import Any, Iterator
|
|
81
|
+
|
|
82
|
+
import config
|
|
83
|
+
|
|
84
|
+
# ---------------------------------------------------------------------------
|
|
85
|
+
# ---- The posture ----------------------------------------------------------
|
|
86
|
+
# ---------------------------------------------------------------------------
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@dataclass(frozen=True)
|
|
90
|
+
class Posture:
|
|
91
|
+
"""What this process is allowed to do to itself and its host.
|
|
92
|
+
|
|
93
|
+
Frozen, and the frozenness is the point rather than tidiness: the
|
|
94
|
+
whole reason this type exists is that `config.<FLAG> = ...` was a
|
|
95
|
+
legal statement anywhere in the process.
|
|
96
|
+
"""
|
|
97
|
+
|
|
98
|
+
# "always" / "tiered" / "never" -- validated at bind time, so a typo
|
|
99
|
+
# is a startup failure and never a policy that quietly means
|
|
100
|
+
# something else (the argument capability.validate_mode makes).
|
|
101
|
+
shell_approval_mode: str
|
|
102
|
+
# The weak host-subprocess backend, and whether it runs unprompted.
|
|
103
|
+
# Together these two are unbounded code on the host; SECURITY.md
|
|
104
|
+
# records that it is not defended against because it cannot be.
|
|
105
|
+
allow_insecure_fallback: bool
|
|
106
|
+
auto_approve_fallback: bool
|
|
107
|
+
# Master switch for pattern-based redaction of what leaves a tool.
|
|
108
|
+
redact_tool_outputs: bool
|
|
109
|
+
# VENASTINE_REDACT_OFF, the per-run weakening of the line above.
|
|
110
|
+
#
|
|
111
|
+
# Bound here rather than left as a live `os.environ` read, and that is
|
|
112
|
+
# not tidiness: `os.environ["VENASTINE_REDACT_OFF"] = "1"` is a legal
|
|
113
|
+
# statement anywhere in the process, so the one security setting that
|
|
114
|
+
# DID have an environment input also had the mutation surface this
|
|
115
|
+
# module exists to close. Batch 37 established the asymmetry it turns
|
|
116
|
+
# on -- `config` binds at import so mutating the environment cannot
|
|
117
|
+
# move it, but anything reading `os.environ` at call time follows the
|
|
118
|
+
# mutation.
|
|
119
|
+
#
|
|
120
|
+
# Kept as its own field rather than folded into the effective answer,
|
|
121
|
+
# because `redaction_enabled()`'s "two switches, one question" is a
|
|
122
|
+
# real distinction: the constant is the permanent answer and this is
|
|
123
|
+
# one run's, and the environment may only ever turn redaction OFF.
|
|
124
|
+
redact_off_env: bool
|
|
125
|
+
|
|
126
|
+
def unsafe_reasons(self) -> list[tuple[str, str]]:
|
|
127
|
+
"""Every active posture that weakens the shipped defaults, as
|
|
128
|
+
`(label, detail)` pairs.
|
|
129
|
+
|
|
130
|
+
ONE source for the startup banner, the launch WARNING and the TUI
|
|
131
|
+
badge (UN3). Three surfaces describing the same state in three
|
|
132
|
+
slightly different ways is how a user ends up trusting the one
|
|
133
|
+
that happens to be wrong, and it is the shape §28 was written to
|
|
134
|
+
remove one level up ("one classification, two consumers").
|
|
135
|
+
|
|
136
|
+
The pair is what lets that stay true across surfaces of very
|
|
137
|
+
different widths. The sidebar is twenty columns, so it shows the
|
|
138
|
+
LABEL; stderr and app.log have a full line, so they show the
|
|
139
|
+
detail. The alternative -- a second method deriving short names --
|
|
140
|
+
would put these conditions in two places, which is the drift this
|
|
141
|
+
method exists to prevent. Labels are short enough not to wrap
|
|
142
|
+
mid-identifier at that width, which `ALLOW_INSECURE_SANDBOX_FALLBACK`
|
|
143
|
+
is not.
|
|
144
|
+
|
|
145
|
+
Empty list means the shipped posture, which is what lets every
|
|
146
|
+
caller write `if reasons:` instead of re-deriving the question.
|
|
147
|
+
"""
|
|
148
|
+
reasons: list[tuple[str, str]] = []
|
|
149
|
+
if self.shell_approval_mode == "never":
|
|
150
|
+
reasons.append((
|
|
151
|
+
"shell: never ask",
|
|
152
|
+
"SHELL_APPROVAL_MODE is 'never' -- no shell command is "
|
|
153
|
+
"ever asked about, including one that reads outside the "
|
|
154
|
+
"workspace on the host"))
|
|
155
|
+
if self.allow_insecure_fallback and self.auto_approve_fallback:
|
|
156
|
+
reasons.append((
|
|
157
|
+
"host shell, no ask",
|
|
158
|
+
"ALLOW_INSECURE_SANDBOX_FALLBACK and "
|
|
159
|
+
"AUTO_APPROVE_SANDBOX_FALLBACK are both on -- unprompted "
|
|
160
|
+
"arbitrary code on the host, with your own file access, "
|
|
161
|
+
"including writes into this harness's own source"))
|
|
162
|
+
elif self.allow_insecure_fallback:
|
|
163
|
+
reasons.append((
|
|
164
|
+
"host shell fallback",
|
|
165
|
+
"ALLOW_INSECURE_SANDBOX_FALLBACK is on -- if Docker is "
|
|
166
|
+
"down, commands run on the host with no filesystem or "
|
|
167
|
+
"network isolation"))
|
|
168
|
+
if not self.redact_tool_outputs:
|
|
169
|
+
reasons.append((
|
|
170
|
+
"no redaction",
|
|
171
|
+
"REDACT_TOOL_OUTPUTS is off -- credential-shaped strings "
|
|
172
|
+
"in tool results are passed through unredacted"))
|
|
173
|
+
elif self.redact_off_env:
|
|
174
|
+
reasons.append((
|
|
175
|
+
"no redaction (env)",
|
|
176
|
+
"VENASTINE_REDACT_OFF is set -- credential-shaped strings "
|
|
177
|
+
"in tool results are passed through unredacted for this "
|
|
178
|
+
"run"))
|
|
179
|
+
return reasons
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
def _redact_off_from_env() -> bool:
|
|
183
|
+
"""Whether VENASTINE_REDACT_OFF asks for redaction off, this run.
|
|
184
|
+
|
|
185
|
+
The truthiness rule is `redaction_enabled()`'s, moved rather than
|
|
186
|
+
rewritten: an unset, empty, "0", "false", "no" or "off" value means
|
|
187
|
+
redaction stays ON. Anything else turns it off.
|
|
188
|
+
"""
|
|
189
|
+
raw = os.environ.get("VENASTINE_REDACT_OFF", "")
|
|
190
|
+
return raw.strip().lower() not in ("", "0", "false", "no", "off")
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def _from_config() -> Posture:
|
|
194
|
+
"""Read `config` and the environment once. The only place this module
|
|
195
|
+
touches either."""
|
|
196
|
+
return Posture(
|
|
197
|
+
shell_approval_mode=config.SHELL_APPROVAL_MODE,
|
|
198
|
+
allow_insecure_fallback=bool(config.ALLOW_INSECURE_SANDBOX_FALLBACK),
|
|
199
|
+
auto_approve_fallback=bool(config.AUTO_APPROVE_SANDBOX_FALLBACK),
|
|
200
|
+
redact_tool_outputs=bool(config.REDACT_TOOL_OUTPUTS),
|
|
201
|
+
redact_off_env=_redact_off_from_env(),
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
# Bound at IMPORT from config alone, so a caller that never reaches
|
|
206
|
+
# `apply_cli` -- a library import, a bare test, `python -c` -- still gets
|
|
207
|
+
# a valid posture, and the one it gets is whatever the human wrote in
|
|
208
|
+
# config.py. There is no "unset" state to forget to handle.
|
|
209
|
+
_posture: Posture = _from_config()
|
|
210
|
+
_read = False
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
# ---------------------------------------------------------------------------
|
|
214
|
+
# ---- Accessors ------------------------------------------------------------
|
|
215
|
+
# ---------------------------------------------------------------------------
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def current() -> Posture:
|
|
219
|
+
"""The posture, marking it bound.
|
|
220
|
+
|
|
221
|
+
Reading is what closes the door. That is deliberate: it makes
|
|
222
|
+
`apply_cli` after a read an error rather than a silent no-op, and it
|
|
223
|
+
means the check costs nothing in the common path.
|
|
224
|
+
"""
|
|
225
|
+
global _read
|
|
226
|
+
_read = True
|
|
227
|
+
return _posture
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def apply_cli(**overrides: Any) -> Posture:
|
|
231
|
+
"""Fold command-line overrides in, once, before anything reads.
|
|
232
|
+
|
|
233
|
+
Raises if the posture has already been read. `main.py` calls this
|
|
234
|
+
immediately after `parse_args` and above `protected_paths.check_workspace`
|
|
235
|
+
-- whose answer now depends on it -- so the ordering is short enough to
|
|
236
|
+
verify by eye, and this makes it verifiable by the suite as well.
|
|
237
|
+
|
|
238
|
+
Keyword arguments rather than an argparse Namespace: this module must
|
|
239
|
+
not know the CLI's flag names, and a caller passing `shell_approval_mode=`
|
|
240
|
+
is stating what it means rather than what it was typed as.
|
|
241
|
+
"""
|
|
242
|
+
global _posture, _read
|
|
243
|
+
known = {f.name for f in dataclasses.fields(Posture)}
|
|
244
|
+
unknown = set(overrides) - known
|
|
245
|
+
if unknown:
|
|
246
|
+
raise TypeError(
|
|
247
|
+
f"unknown posture field(s): {sorted(unknown)}. Add the field to "
|
|
248
|
+
f"Posture, or fix the caller -- silently ignoring it would mean "
|
|
249
|
+
f"a flag that appears to work and does nothing.")
|
|
250
|
+
# None means "the flag was not passed", so an absent CLI flag never
|
|
251
|
+
# overrides config. argparse gives absent booleans None or False, and
|
|
252
|
+
# False here would mean a missing --unsafe silently turned something
|
|
253
|
+
# off that config.py had turned on.
|
|
254
|
+
supplied = {k: v for k, v in overrides.items() if v is not None}
|
|
255
|
+
candidate = dataclasses.replace(_posture, **supplied)
|
|
256
|
+
|
|
257
|
+
# The guard fires on a CHANGE after a read, not on a read. Those are
|
|
258
|
+
# different facts and only one of them is a bug: if folding in the
|
|
259
|
+
# command line produces the posture that was already read, nobody
|
|
260
|
+
# anywhere saw a wrong value and there is nothing to catch. Raising on
|
|
261
|
+
# the read alone would also make `main()` un-callable twice in one
|
|
262
|
+
# interpreter, which the suite does constantly -- and a guard that
|
|
263
|
+
# forces the tests to work around it stops being read as a guard.
|
|
264
|
+
if _read and candidate != _posture:
|
|
265
|
+
raise RuntimeError(
|
|
266
|
+
"security.posture.apply_cli() would CHANGE the posture after it "
|
|
267
|
+
"had already been read. Something consulted the posture before "
|
|
268
|
+
"the command line was folded in, so it acted on the config-only "
|
|
269
|
+
"value -- which is a run that may believe it is safer or less "
|
|
270
|
+
"safe than it is. Move the apply_cli() call above the first "
|
|
271
|
+
"reader (main.py does it directly after parse_args), and note "
|
|
272
|
+
"that no module may read the posture at IMPORT time.")
|
|
273
|
+
_posture = candidate
|
|
274
|
+
return _posture
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
@contextlib.contextmanager
|
|
278
|
+
def override_for_tests(**overrides: Any) -> Iterator[Posture]:
|
|
279
|
+
"""Set the posture for the duration of a block. TESTS ONLY.
|
|
280
|
+
|
|
281
|
+
Named at length on purpose. It is a mutation seam in a module whose
|
|
282
|
+
entire subject is not having one, and the honest defence is that an
|
|
283
|
+
attacker who can call this can also rebind `current` -- see the module
|
|
284
|
+
docstring. What it must never become is a runtime API: nothing in
|
|
285
|
+
`core/`, `tools/`, `tui/` or `main.py` may call it, and
|
|
286
|
+
`test_posture.py` asserts that.
|
|
287
|
+
|
|
288
|
+
Replaces the pre-§40 pattern `monkeypatch.setattr(config, "FLAG", ...)`,
|
|
289
|
+
which worked only because the flags were read live -- the property this
|
|
290
|
+
batch removed.
|
|
291
|
+
"""
|
|
292
|
+
global _posture, _read
|
|
293
|
+
before, before_read = _posture, _read
|
|
294
|
+
known = {f.name for f in dataclasses.fields(Posture)}
|
|
295
|
+
unknown = set(overrides) - known
|
|
296
|
+
if unknown:
|
|
297
|
+
raise TypeError(f"unknown posture field(s): {sorted(unknown)}")
|
|
298
|
+
try:
|
|
299
|
+
_posture = dataclasses.replace(_posture, **overrides)
|
|
300
|
+
yield _posture
|
|
301
|
+
finally:
|
|
302
|
+
_posture, _read = before, before_read
|