@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.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. 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