repoward 0.1.0__py3-none-any.whl
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.
- repoward/__init__.py +1 -0
- repoward/adapters/__init__.py +1 -0
- repoward/adapters/ci.py +50 -0
- repoward/adapters/github.py +150 -0
- repoward/approvals/__init__.py +1 -0
- repoward/approvals/store.py +199 -0
- repoward/audit.py +235 -0
- repoward/canonical.py +20 -0
- repoward/catalog.py +29 -0
- repoward/cli.py +391 -0
- repoward/flow.py +239 -0
- repoward/pipeline.py +333 -0
- repoward/policy/__init__.py +1 -0
- repoward/policy/engine.py +101 -0
- repoward/policy/loader.py +245 -0
- repoward/policy/models.py +100 -0
- repoward/principal.py +15 -0
- repoward/py.typed +0 -0
- repoward/ratelimit.py +39 -0
- repoward/registry.py +68 -0
- repoward/sanitize.py +207 -0
- repoward/server.py +101 -0
- repoward/setup.py +118 -0
- repoward/storage.py +26 -0
- repoward/tools/__init__.py +1 -0
- repoward/tools/ci_read.py +121 -0
- repoward/tools/github_dangerous.py +135 -0
- repoward/tools/github_read.py +312 -0
- repoward/tools/github_write.py +239 -0
- repoward/tools/system.py +26 -0
- repoward/validation.py +63 -0
- repoward-0.1.0.dist-info/METADATA +317 -0
- repoward-0.1.0.dist-info/RECORD +36 -0
- repoward-0.1.0.dist-info/WHEEL +4 -0
- repoward-0.1.0.dist-info/entry_points.txt +2 -0
- repoward-0.1.0.dist-info/licenses/LICENSE +21 -0
repoward/pipeline.py
ADDED
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
"""The single guarded call path. Every tool attempt goes through `Pipeline.call`."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
import time
|
|
6
|
+
import uuid
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
import anyio.to_thread
|
|
10
|
+
from mcp.types import CallToolResult, TextContent
|
|
11
|
+
from pydantic import ValidationError
|
|
12
|
+
|
|
13
|
+
from repoward.approvals.store import ApprovalStore, ApprovalStoreError, TooManyPendingError
|
|
14
|
+
from repoward.audit import AuditLog, AuditWriteError
|
|
15
|
+
from repoward.canonical import canonical_json, sha256_hex
|
|
16
|
+
from repoward.catalog import RiskClass
|
|
17
|
+
from repoward.flow import FlowGuard, FlowStoreError
|
|
18
|
+
from repoward.policy.engine import Decision, Effect, decide
|
|
19
|
+
from repoward.policy.loader import CompiledPolicy
|
|
20
|
+
from repoward.principal import Principal
|
|
21
|
+
from repoward.ratelimit import RateLimiter
|
|
22
|
+
from repoward.registry import ToolError, ToolInput, ToolRegistry, ToolSpec
|
|
23
|
+
from repoward.sanitize import redact_for_audit, redact_text, render_output
|
|
24
|
+
|
|
25
|
+
MAX_OUTPUT_CHARS = 100_000
|
|
26
|
+
_MAX_VALIDATION_ERRORS = 5
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _result(text: str, *, is_error: bool = False) -> CallToolResult:
|
|
30
|
+
return CallToolResult(content=[TextContent(type="text", text=text)], is_error=is_error)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _hash_args(args: Any) -> str:
|
|
34
|
+
try:
|
|
35
|
+
return sha256_hex(canonical_json(args))
|
|
36
|
+
except (TypeError, ValueError):
|
|
37
|
+
return sha256_hex(repr(args).encode("utf-8", "replace"))
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def alert(message: str) -> None:
|
|
41
|
+
"""Report an operational problem on stderr. In stdio mode, stdout is the protocol."""
|
|
42
|
+
print(f"repoward: {message}", file=sys.stderr, flush=True)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _describe_invalid_input(exc: ValidationError) -> str:
|
|
46
|
+
"""Say what to fix without echoing the input back."""
|
|
47
|
+
details = [
|
|
48
|
+
f"{'.'.join(str(part) for part in error['loc']) or 'arguments'}: {error['msg']}"
|
|
49
|
+
for error in exc.errors(include_url=False, include_input=False, include_context=False)
|
|
50
|
+
]
|
|
51
|
+
return "Invalid arguments. " + "; ".join(details[:_MAX_VALIDATION_ERRORS])
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class Pipeline:
|
|
55
|
+
def __init__(
|
|
56
|
+
self,
|
|
57
|
+
policy: CompiledPolicy,
|
|
58
|
+
registry: ToolRegistry,
|
|
59
|
+
audit: AuditLog,
|
|
60
|
+
limiter: RateLimiter | None = None,
|
|
61
|
+
approvals: ApprovalStore | None = None,
|
|
62
|
+
flow: FlowGuard | None = None,
|
|
63
|
+
) -> None:
|
|
64
|
+
self._policy = policy
|
|
65
|
+
self._registry = registry
|
|
66
|
+
self._audit = audit
|
|
67
|
+
self._limiter = limiter or RateLimiter(policy.rate_limits)
|
|
68
|
+
self._instance_id = str(uuid.uuid4())
|
|
69
|
+
self._approvals = approvals
|
|
70
|
+
self._flow = flow
|
|
71
|
+
self._degraded = False
|
|
72
|
+
|
|
73
|
+
async def call(
|
|
74
|
+
self,
|
|
75
|
+
principal: Principal,
|
|
76
|
+
tool: str,
|
|
77
|
+
raw_args: dict[str, Any] | None,
|
|
78
|
+
session_id: str | None = None,
|
|
79
|
+
) -> CallToolResult:
|
|
80
|
+
request_id = str(uuid.uuid4())
|
|
81
|
+
args: Any = raw_args if raw_args is not None else {}
|
|
82
|
+
context: dict[str, Any] = {
|
|
83
|
+
"request_id": request_id,
|
|
84
|
+
"instance_id": self._instance_id,
|
|
85
|
+
"session_id": session_id,
|
|
86
|
+
"principal": principal.id,
|
|
87
|
+
"role": principal.role,
|
|
88
|
+
"tool": redact_for_audit(tool),
|
|
89
|
+
"policy_hash": self._policy.sha256,
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
spec = self._registry.get(tool)
|
|
93
|
+
if spec is None:
|
|
94
|
+
return await self._refuse(context, args, "tool.unknown", "Unknown tool.")
|
|
95
|
+
|
|
96
|
+
try:
|
|
97
|
+
validated = spec.input_model.model_validate(args)
|
|
98
|
+
except ValidationError as exc:
|
|
99
|
+
return await self._refuse(context, args, "input.invalid", _describe_invalid_input(exc))
|
|
100
|
+
normalized = validated.model_dump(mode="json")
|
|
101
|
+
|
|
102
|
+
decision = decide(self._policy, principal, tool, spec.risk, spec.target(validated))
|
|
103
|
+
if decision.effect is Effect.DENY:
|
|
104
|
+
return await self._refuse(context, normalized, decision.rule_id, decision.message)
|
|
105
|
+
|
|
106
|
+
mutating = spec.risk is not RiskClass.READ
|
|
107
|
+
repo = spec.target(validated).repo
|
|
108
|
+
if mutating and self._flow is not None:
|
|
109
|
+
flow_decision = await self._flow.check_write(principal.id, repo)
|
|
110
|
+
decision = self._combine(decision, flow_decision)
|
|
111
|
+
if decision.effect is Effect.DENY:
|
|
112
|
+
return await self._refuse(context, normalized, decision.rule_id, decision.message)
|
|
113
|
+
|
|
114
|
+
hit = self._limiter.check(principal.id, tool)
|
|
115
|
+
if hit is not None:
|
|
116
|
+
message = f"Rate limit reached. Try again in {hit.retry_after_seconds} seconds."
|
|
117
|
+
return await self._refuse(context, normalized, hit.rule_id, message)
|
|
118
|
+
|
|
119
|
+
if mutating and self._degraded:
|
|
120
|
+
return await self._refuse(
|
|
121
|
+
context,
|
|
122
|
+
normalized,
|
|
123
|
+
"audit.degraded",
|
|
124
|
+
"Changes are disabled because the audit log failed. An operator must restart.",
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
rule_id = decision.rule_id
|
|
128
|
+
if decision.effect is Effect.APPROVAL_REQUIRED:
|
|
129
|
+
args_hash = _hash_args(normalized)
|
|
130
|
+
try:
|
|
131
|
+
approval_id = await self._consume_approval(principal, tool, repo, args_hash)
|
|
132
|
+
except ApprovalStoreError as exc:
|
|
133
|
+
alert(str(exc))
|
|
134
|
+
return await self._refuse(
|
|
135
|
+
context,
|
|
136
|
+
normalized,
|
|
137
|
+
"approvals.unavailable",
|
|
138
|
+
"This action needs approval, but approvals are unavailable right now.",
|
|
139
|
+
)
|
|
140
|
+
if approval_id is None:
|
|
141
|
+
return await self._request_approval(
|
|
142
|
+
context, principal, spec, validated, normalized, decision.rule_id, repo
|
|
143
|
+
)
|
|
144
|
+
context = {**context, "approval_id": approval_id}
|
|
145
|
+
rule_id = "approvals.consumed"
|
|
146
|
+
|
|
147
|
+
try:
|
|
148
|
+
await self._write(self._decision_fields(context, normalized, Effect.ALLOW, rule_id))
|
|
149
|
+
except AuditWriteError as exc:
|
|
150
|
+
alert(f"audit decision record failed: {exc}")
|
|
151
|
+
if mutating:
|
|
152
|
+
return _result(
|
|
153
|
+
"The action was not performed because it could not be audited.", is_error=True
|
|
154
|
+
)
|
|
155
|
+
|
|
156
|
+
started = time.monotonic()
|
|
157
|
+
status = "ok"
|
|
158
|
+
error: str | None = None
|
|
159
|
+
try:
|
|
160
|
+
output = await spec.handler(validated)
|
|
161
|
+
if not mutating and self._flow is not None:
|
|
162
|
+
# Saved before the content is returned: unrecorded content is never handed over.
|
|
163
|
+
for kind, source in await self._flow.record_read(principal.id, repo, output.taints):
|
|
164
|
+
await self._record_label(context, kind, source)
|
|
165
|
+
result = _result(render_output(output.text, output.untrusted, MAX_OUTPUT_CHARS))
|
|
166
|
+
except FlowStoreError as exc:
|
|
167
|
+
status = "error"
|
|
168
|
+
error = type(exc).__name__
|
|
169
|
+
alert(f"flow guard could not save state: {exc}")
|
|
170
|
+
result = _result(
|
|
171
|
+
"The content was withheld because it could not be tracked.", is_error=True
|
|
172
|
+
)
|
|
173
|
+
except ToolError as exc:
|
|
174
|
+
status = "error"
|
|
175
|
+
error = redact_text(str(exc))
|
|
176
|
+
result = _result(error, is_error=True)
|
|
177
|
+
except Exception as exc:
|
|
178
|
+
status = "error"
|
|
179
|
+
error = type(exc).__name__
|
|
180
|
+
alert(f"tool {tool} failed: {error}")
|
|
181
|
+
result = _result("The tool failed unexpectedly.", is_error=True)
|
|
182
|
+
|
|
183
|
+
try:
|
|
184
|
+
await self._write(
|
|
185
|
+
{
|
|
186
|
+
"event": "tool_call_outcome",
|
|
187
|
+
"request_id": request_id,
|
|
188
|
+
"result_status": status,
|
|
189
|
+
"duration_ms": int((time.monotonic() - started) * 1000),
|
|
190
|
+
"error": error,
|
|
191
|
+
}
|
|
192
|
+
)
|
|
193
|
+
except AuditWriteError as exc:
|
|
194
|
+
alert(f"audit outcome record failed: {exc}")
|
|
195
|
+
if mutating:
|
|
196
|
+
self._degraded = True
|
|
197
|
+
alert("degraded mode: refusing further changes until restart")
|
|
198
|
+
warning = "Warning: the action ran but its outcome could not be audited."
|
|
199
|
+
result.content.append(TextContent(type="text", text=warning))
|
|
200
|
+
return result
|
|
201
|
+
|
|
202
|
+
@staticmethod
|
|
203
|
+
def _combine(decision: Decision, flow: Decision | None) -> Decision:
|
|
204
|
+
"""Apply the flow guard, which can only tighten what policy decided."""
|
|
205
|
+
if flow is None or flow.effect is Effect.ALLOW or decision.effect is Effect.DENY:
|
|
206
|
+
return decision
|
|
207
|
+
if flow.effect is Effect.APPROVAL_REQUIRED and decision.effect is Effect.APPROVAL_REQUIRED:
|
|
208
|
+
return decision
|
|
209
|
+
return flow
|
|
210
|
+
|
|
211
|
+
async def _record_label(self, context: dict[str, Any], kind: str, source: str) -> None:
|
|
212
|
+
try:
|
|
213
|
+
await self._write(
|
|
214
|
+
{
|
|
215
|
+
"event": "flow_label",
|
|
216
|
+
"request_id": context["request_id"],
|
|
217
|
+
"principal": context["principal"],
|
|
218
|
+
"kind": kind,
|
|
219
|
+
"source": source,
|
|
220
|
+
}
|
|
221
|
+
)
|
|
222
|
+
except AuditWriteError as exc:
|
|
223
|
+
alert(f"audit flow label record failed: {exc}")
|
|
224
|
+
|
|
225
|
+
async def _consume_approval(
|
|
226
|
+
self, principal: Principal, tool: str, repo: str | None, args_hash: str
|
|
227
|
+
) -> str | None:
|
|
228
|
+
if self._approvals is None:
|
|
229
|
+
raise ApprovalStoreError("no approval store is configured")
|
|
230
|
+
return await anyio.to_thread.run_sync(
|
|
231
|
+
self._approvals.consume, principal.id, tool, repo, args_hash
|
|
232
|
+
)
|
|
233
|
+
|
|
234
|
+
async def _request_approval(
|
|
235
|
+
self,
|
|
236
|
+
context: dict[str, Any],
|
|
237
|
+
principal: Principal,
|
|
238
|
+
spec: ToolSpec,
|
|
239
|
+
validated: ToolInput,
|
|
240
|
+
normalized: Any,
|
|
241
|
+
rule_id: str,
|
|
242
|
+
repo: str | None,
|
|
243
|
+
) -> CallToolResult:
|
|
244
|
+
"""Record a request for a human. The tool does not run."""
|
|
245
|
+
assert self._approvals is not None # noqa: S101
|
|
246
|
+
details = ""
|
|
247
|
+
if spec.approval_context is not None:
|
|
248
|
+
try:
|
|
249
|
+
details = await spec.approval_context(validated)
|
|
250
|
+
except Exception as exc:
|
|
251
|
+
details = "Could not fetch details from GitHub."
|
|
252
|
+
alert(f"approval context failed: {type(exc).__name__}")
|
|
253
|
+
if self._flow is not None:
|
|
254
|
+
try:
|
|
255
|
+
note = await self._flow.describe(principal.id)
|
|
256
|
+
except FlowStoreError as exc:
|
|
257
|
+
note = "Flow guard state is unavailable."
|
|
258
|
+
alert(str(exc))
|
|
259
|
+
details = "\n".join(part for part in (details, note) if part)
|
|
260
|
+
try:
|
|
261
|
+
approval = await anyio.to_thread.run_sync(
|
|
262
|
+
self._approvals.request,
|
|
263
|
+
principal.id,
|
|
264
|
+
spec.name,
|
|
265
|
+
repo,
|
|
266
|
+
_hash_args(normalized),
|
|
267
|
+
json.dumps(redact_for_audit(normalized), ensure_ascii=True, sort_keys=True),
|
|
268
|
+
redact_text(details),
|
|
269
|
+
)
|
|
270
|
+
except TooManyPendingError:
|
|
271
|
+
return await self._refuse(
|
|
272
|
+
context,
|
|
273
|
+
normalized,
|
|
274
|
+
"approvals.too_many_pending",
|
|
275
|
+
"Too many approval requests are waiting. Ask a human to review them.",
|
|
276
|
+
)
|
|
277
|
+
except ApprovalStoreError as exc:
|
|
278
|
+
alert(str(exc))
|
|
279
|
+
return await self._refuse(
|
|
280
|
+
context,
|
|
281
|
+
normalized,
|
|
282
|
+
"approvals.unavailable",
|
|
283
|
+
"This action needs approval, but approvals are unavailable right now.",
|
|
284
|
+
)
|
|
285
|
+
await self._record_refusal(
|
|
286
|
+
{**context, "approval_id": approval.id},
|
|
287
|
+
normalized,
|
|
288
|
+
Effect.APPROVAL_REQUIRED,
|
|
289
|
+
rule_id,
|
|
290
|
+
)
|
|
291
|
+
body = {
|
|
292
|
+
"status": "approval_required",
|
|
293
|
+
"approval_id": approval.id,
|
|
294
|
+
"summary": (
|
|
295
|
+
f"{spec.name} was not run. A human must approve request {approval.id}; "
|
|
296
|
+
"then call the tool again with the same arguments."
|
|
297
|
+
),
|
|
298
|
+
}
|
|
299
|
+
return CallToolResult(
|
|
300
|
+
content=[TextContent(type="text", text=json.dumps(body))],
|
|
301
|
+
structured_content=body,
|
|
302
|
+
)
|
|
303
|
+
|
|
304
|
+
@staticmethod
|
|
305
|
+
def _decision_fields(
|
|
306
|
+
context: dict[str, Any], args: Any, effect: Effect, rule_id: str
|
|
307
|
+
) -> dict[str, Any]:
|
|
308
|
+
return {
|
|
309
|
+
**context,
|
|
310
|
+
"event": "tool_call_decision",
|
|
311
|
+
"args_redacted": redact_for_audit(args, hide_content=True),
|
|
312
|
+
"args_hash": _hash_args(args),
|
|
313
|
+
"decision": effect.value,
|
|
314
|
+
"rule_id": rule_id,
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
async def _write(self, fields: dict[str, Any]) -> None:
|
|
318
|
+
await anyio.to_thread.run_sync(self._audit.append, fields)
|
|
319
|
+
|
|
320
|
+
async def _record_refusal(
|
|
321
|
+
self, context: dict[str, Any], args: Any, effect: Effect, rule_id: str
|
|
322
|
+
) -> None:
|
|
323
|
+
"""Log an attempt that will not execute. Failing to log never turns it into a yes."""
|
|
324
|
+
try:
|
|
325
|
+
await self._write(self._decision_fields(context, args, effect, rule_id))
|
|
326
|
+
except AuditWriteError as exc:
|
|
327
|
+
alert(f"audit decision record failed: {exc}")
|
|
328
|
+
|
|
329
|
+
async def _refuse(
|
|
330
|
+
self, context: dict[str, Any], args: Any, rule_id: str, message: str
|
|
331
|
+
) -> CallToolResult:
|
|
332
|
+
await self._record_refusal(context, args, Effect.DENY, rule_id)
|
|
333
|
+
return _result(message, is_error=True)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Policy models, strict loading and decisions."""
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
"""The policy decision. Pure logic with no I/O, and default-deny."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Sequence
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from enum import StrEnum
|
|
6
|
+
|
|
7
|
+
from repoward.catalog import RiskClass
|
|
8
|
+
from repoward.policy.loader import CompiledPolicy
|
|
9
|
+
from repoward.principal import Principal
|
|
10
|
+
from repoward.sanitize import contains_secret
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class Effect(StrEnum):
|
|
14
|
+
ALLOW = "allow"
|
|
15
|
+
DENY = "deny"
|
|
16
|
+
APPROVAL_REQUIRED = "approval_required"
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class Target:
|
|
21
|
+
"""What a call touches. Paths must already be normalized by the input model."""
|
|
22
|
+
|
|
23
|
+
repo: str | None = None
|
|
24
|
+
paths: Sequence[str] = ()
|
|
25
|
+
write_branches: Sequence[str] = ()
|
|
26
|
+
non_draft: bool = False
|
|
27
|
+
commit_files: int = 0
|
|
28
|
+
commit_bytes: int = 0
|
|
29
|
+
outbound: Sequence[str] = ()
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class Decision:
|
|
34
|
+
effect: Effect
|
|
35
|
+
rule_id: str
|
|
36
|
+
message: str = ""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def decide(
|
|
40
|
+
compiled: CompiledPolicy,
|
|
41
|
+
principal: Principal,
|
|
42
|
+
tool: str,
|
|
43
|
+
risk: RiskClass,
|
|
44
|
+
target: Target,
|
|
45
|
+
) -> Decision:
|
|
46
|
+
"""Decide one call. Messages reach the agent, so they reveal no policy details."""
|
|
47
|
+
role = compiled.roles.get(principal.role)
|
|
48
|
+
if role is None:
|
|
49
|
+
return Decision(Effect.DENY, "role.unknown", "Your role is not permitted to use tools.")
|
|
50
|
+
if tool not in role.tools:
|
|
51
|
+
return Decision(
|
|
52
|
+
Effect.DENY,
|
|
53
|
+
"default.deny",
|
|
54
|
+
f"Tool {tool} is not permitted for role {principal.role}; ask a maintainer.",
|
|
55
|
+
)
|
|
56
|
+
if risk is RiskClass.DANGEROUS:
|
|
57
|
+
switch = compiled.policy.dangerous_tools.get(tool)
|
|
58
|
+
if switch is None or not switch.enabled:
|
|
59
|
+
return Decision(
|
|
60
|
+
Effect.DENY,
|
|
61
|
+
f"dangerous_tools.{tool}.disabled",
|
|
62
|
+
f"Tool {tool} is disabled in this deployment.",
|
|
63
|
+
)
|
|
64
|
+
if target.repo is not None and target.repo.casefold() not in compiled.allowed_repos:
|
|
65
|
+
return Decision(Effect.DENY, "repos.allow", "This repository is not permitted.")
|
|
66
|
+
for path in target.paths:
|
|
67
|
+
if compiled.path_is_denied(path):
|
|
68
|
+
return Decision(Effect.DENY, "paths.deny", "A requested path is not permitted.")
|
|
69
|
+
prefix = compiled.policy.branches.write_prefix
|
|
70
|
+
if any(not branch.startswith(prefix) for branch in target.write_branches):
|
|
71
|
+
return Decision(
|
|
72
|
+
Effect.DENY,
|
|
73
|
+
"branches.write_prefix",
|
|
74
|
+
f"Writes are only permitted on branches starting with {prefix}",
|
|
75
|
+
)
|
|
76
|
+
if target.non_draft and not compiled.policy.pull_requests.allow_non_draft:
|
|
77
|
+
return Decision(
|
|
78
|
+
Effect.DENY,
|
|
79
|
+
"pull_requests.allow_non_draft",
|
|
80
|
+
"Only draft pull requests are permitted.",
|
|
81
|
+
)
|
|
82
|
+
limits = role.commit_limits
|
|
83
|
+
if target.commit_files > limits.max_files or target.commit_bytes > limits.max_bytes:
|
|
84
|
+
return Decision(
|
|
85
|
+
Effect.DENY,
|
|
86
|
+
"roles.commit_limits",
|
|
87
|
+
f"Commits are limited to {limits.max_files} files and {limits.max_bytes} bytes.",
|
|
88
|
+
)
|
|
89
|
+
if any(contains_secret(text) for text in target.outbound):
|
|
90
|
+
return Decision(
|
|
91
|
+
Effect.DENY,
|
|
92
|
+
"secrets.outbound",
|
|
93
|
+
"The content appears to contain a credential, so it was not sent.",
|
|
94
|
+
)
|
|
95
|
+
if tool in role.require_approval:
|
|
96
|
+
return Decision(
|
|
97
|
+
Effect.APPROVAL_REQUIRED,
|
|
98
|
+
f"roles.{principal.role}.require_approval",
|
|
99
|
+
"This action requires human approval.",
|
|
100
|
+
)
|
|
101
|
+
return Decision(Effect.ALLOW, f"roles.{principal.role}.tools")
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
"""Strict policy loading. Every problem is reported with its line number."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass, field
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
import pathspec
|
|
8
|
+
import yaml
|
|
9
|
+
from pydantic import ValidationError
|
|
10
|
+
|
|
11
|
+
from repoward.canonical import sha256_hex
|
|
12
|
+
from repoward.catalog import TOOL_CATALOG, RiskClass
|
|
13
|
+
from repoward.policy.models import CommitLimits, Policy
|
|
14
|
+
|
|
15
|
+
_MAX_POLICY_BYTES = 1_000_000
|
|
16
|
+
_Loc = tuple[str | int, ...]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class PolicyIssue:
|
|
21
|
+
message: str
|
|
22
|
+
line: int | None = None
|
|
23
|
+
column: int | None = None
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class PolicyError(Exception):
|
|
27
|
+
def __init__(self, issues: list[PolicyIssue]) -> None:
|
|
28
|
+
super().__init__("; ".join(issue.message for issue in issues))
|
|
29
|
+
self.issues = issues
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class ResolvedRole:
|
|
34
|
+
tools: frozenset[str]
|
|
35
|
+
require_approval: frozenset[str]
|
|
36
|
+
commit_limits: CommitLimits = field(default_factory=CommitLimits)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
@dataclass(frozen=True)
|
|
40
|
+
class CompiledPolicy:
|
|
41
|
+
policy: Policy
|
|
42
|
+
sha256: str
|
|
43
|
+
roles: dict[str, ResolvedRole]
|
|
44
|
+
allowed_repos: frozenset[str]
|
|
45
|
+
denied_paths: pathspec.PathSpec[Any]
|
|
46
|
+
rate_limits: dict[str, int]
|
|
47
|
+
|
|
48
|
+
def path_is_denied(self, normalized_path: str) -> bool:
|
|
49
|
+
return self.denied_paths.match_file(normalized_path.casefold())
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _issue_at(message: str, mark: yaml.Mark) -> PolicyIssue:
|
|
53
|
+
return PolicyIssue(message, mark.line + 1, mark.column + 1)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _structure_issues(text: str) -> list[PolicyIssue]:
|
|
57
|
+
"""Reject YAML features that can silently change meaning."""
|
|
58
|
+
issues: list[PolicyIssue] = []
|
|
59
|
+
for event in yaml.parse(text, Loader=yaml.SafeLoader):
|
|
60
|
+
if isinstance(event, yaml.AliasEvent) or getattr(event, "anchor", None):
|
|
61
|
+
issues.append(_issue_at("YAML anchors and aliases are not allowed", event.start_mark))
|
|
62
|
+
|
|
63
|
+
def walk(node: yaml.Node) -> None:
|
|
64
|
+
if isinstance(node, yaml.MappingNode):
|
|
65
|
+
seen: set[str] = set()
|
|
66
|
+
for key, value in node.value:
|
|
67
|
+
if key.tag == "tag:yaml.org,2002:merge":
|
|
68
|
+
issues.append(_issue_at("YAML merge keys are not allowed", key.start_mark))
|
|
69
|
+
elif isinstance(key, yaml.ScalarNode):
|
|
70
|
+
if key.value in seen:
|
|
71
|
+
issues.append(_issue_at(f"duplicate key '{key.value}'", key.start_mark))
|
|
72
|
+
seen.add(key.value)
|
|
73
|
+
walk(value)
|
|
74
|
+
elif isinstance(node, yaml.SequenceNode):
|
|
75
|
+
for item in node.value:
|
|
76
|
+
walk(item)
|
|
77
|
+
|
|
78
|
+
if not issues:
|
|
79
|
+
root = yaml.compose(text, Loader=yaml.SafeLoader)
|
|
80
|
+
if root is not None:
|
|
81
|
+
walk(root)
|
|
82
|
+
return issues
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _locate(root: yaml.Node | None, loc: _Loc) -> tuple[int | None, int | None]:
|
|
86
|
+
"""Find the deepest YAML node on a path, for error reporting."""
|
|
87
|
+
if root is None:
|
|
88
|
+
return None, None
|
|
89
|
+
node = root
|
|
90
|
+
for part in loc:
|
|
91
|
+
child: yaml.Node | None = None
|
|
92
|
+
if isinstance(node, yaml.MappingNode):
|
|
93
|
+
for key, value in node.value:
|
|
94
|
+
if isinstance(key, yaml.ScalarNode) and key.value == str(part):
|
|
95
|
+
child = value
|
|
96
|
+
break
|
|
97
|
+
elif (
|
|
98
|
+
isinstance(node, yaml.SequenceNode) and isinstance(part, int) and part < len(node.value)
|
|
99
|
+
):
|
|
100
|
+
child = node.value[part]
|
|
101
|
+
if child is None:
|
|
102
|
+
break
|
|
103
|
+
node = child
|
|
104
|
+
return node.start_mark.line + 1, node.start_mark.column + 1
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _resolve_roles(policy: Policy, problems: list[tuple[str, _Loc]]) -> dict[str, ResolvedRole]:
|
|
108
|
+
resolved: dict[str, ResolvedRole] = {}
|
|
109
|
+
reported: set[str] = set()
|
|
110
|
+
|
|
111
|
+
def fail(name: str, message: str) -> None:
|
|
112
|
+
if name not in reported:
|
|
113
|
+
reported.add(name)
|
|
114
|
+
problems.append((message, ("roles", name, "inherits")))
|
|
115
|
+
|
|
116
|
+
def resolve(name: str, chain: tuple[str, ...]) -> ResolvedRole | None:
|
|
117
|
+
if name in resolved:
|
|
118
|
+
return resolved[name]
|
|
119
|
+
role = policy.roles[name]
|
|
120
|
+
tools = set(role.tools)
|
|
121
|
+
approvals = set(role.require_approval)
|
|
122
|
+
limits = role.commit_limits
|
|
123
|
+
if role.inherits is not None:
|
|
124
|
+
if role.inherits == name or role.inherits in chain:
|
|
125
|
+
fail(name, f"role '{name}' has an inheritance cycle")
|
|
126
|
+
return None
|
|
127
|
+
if role.inherits not in policy.roles:
|
|
128
|
+
fail(name, f"role '{name}' inherits unknown role '{role.inherits}'")
|
|
129
|
+
return None
|
|
130
|
+
parent = resolve(role.inherits, (*chain, name))
|
|
131
|
+
if parent is None:
|
|
132
|
+
return None
|
|
133
|
+
tools |= parent.tools
|
|
134
|
+
approvals |= parent.require_approval
|
|
135
|
+
limits = limits or parent.commit_limits
|
|
136
|
+
result = ResolvedRole(frozenset(tools), frozenset(approvals), limits or CommitLimits())
|
|
137
|
+
resolved[name] = result
|
|
138
|
+
return result
|
|
139
|
+
|
|
140
|
+
for name in policy.roles:
|
|
141
|
+
resolve(name, ())
|
|
142
|
+
return resolved
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def _semantic_problems(policy: Policy, resolved: dict[str, ResolvedRole]) -> list[tuple[str, _Loc]]:
|
|
146
|
+
problems: list[tuple[str, _Loc]] = []
|
|
147
|
+
for name, role in policy.roles.items():
|
|
148
|
+
for section, tools in (("tools", role.tools), ("require_approval", role.require_approval)):
|
|
149
|
+
for index, tool in enumerate(tools):
|
|
150
|
+
if tool not in TOOL_CATALOG:
|
|
151
|
+
problems.append((f"unknown tool '{tool}'", ("roles", name, section, index)))
|
|
152
|
+
effective = resolved.get(name)
|
|
153
|
+
if effective is None:
|
|
154
|
+
continue
|
|
155
|
+
for tool in sorted(effective.require_approval - effective.tools):
|
|
156
|
+
problems.append(
|
|
157
|
+
(f"role '{name}' requires approval for '{tool}' but lacks it", ("roles", name))
|
|
158
|
+
)
|
|
159
|
+
for tool in sorted(effective.tools):
|
|
160
|
+
if (
|
|
161
|
+
TOOL_CATALOG.get(tool) is RiskClass.DANGEROUS
|
|
162
|
+
and tool not in effective.require_approval
|
|
163
|
+
):
|
|
164
|
+
problems.append(
|
|
165
|
+
(f"dangerous tool '{tool}' in role '{name}' needs approval", ("roles", name))
|
|
166
|
+
)
|
|
167
|
+
for tool in policy.dangerous_tools:
|
|
168
|
+
if TOOL_CATALOG.get(tool) is not RiskClass.DANGEROUS:
|
|
169
|
+
problems.append((f"'{tool}' is not a dangerous tool", ("dangerous_tools", tool)))
|
|
170
|
+
if "default" not in policy.rate_limits:
|
|
171
|
+
problems.append(("rate_limits must define 'default'", ("rate_limits",)))
|
|
172
|
+
for tool in policy.rate_limits:
|
|
173
|
+
if tool != "default" and tool not in TOOL_CATALOG:
|
|
174
|
+
problems.append((f"unknown tool '{tool}'", ("rate_limits", tool)))
|
|
175
|
+
if policy.stdio.role not in policy.roles:
|
|
176
|
+
problems.append((f"stdio role '{policy.stdio.role}' is not defined", ("stdio", "role")))
|
|
177
|
+
for index, pattern in enumerate(policy.paths.deny):
|
|
178
|
+
if not pattern.strip() or pattern.startswith("!"):
|
|
179
|
+
problems.append(
|
|
180
|
+
("path patterns must not be empty or negated", ("paths", "deny", index))
|
|
181
|
+
)
|
|
182
|
+
return problems
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def parse_policy(data: bytes) -> CompiledPolicy:
|
|
186
|
+
if len(data) > _MAX_POLICY_BYTES:
|
|
187
|
+
raise PolicyError([PolicyIssue("policy file is too large")])
|
|
188
|
+
try:
|
|
189
|
+
text = data.decode("utf-8")
|
|
190
|
+
except UnicodeDecodeError as exc:
|
|
191
|
+
raise PolicyError([PolicyIssue("policy file must be UTF-8")]) from exc
|
|
192
|
+
|
|
193
|
+
try:
|
|
194
|
+
structure = _structure_issues(text)
|
|
195
|
+
if structure:
|
|
196
|
+
raise PolicyError(structure)
|
|
197
|
+
root = yaml.compose(text, Loader=yaml.SafeLoader)
|
|
198
|
+
raw: Any = yaml.safe_load(text)
|
|
199
|
+
except yaml.MarkedYAMLError as exc:
|
|
200
|
+
mark = exc.problem_mark
|
|
201
|
+
line = mark.line + 1 if mark else None
|
|
202
|
+
column = mark.column + 1 if mark else None
|
|
203
|
+
raise PolicyError([PolicyIssue(f"invalid YAML: {exc.problem}", line, column)]) from exc
|
|
204
|
+
except yaml.YAMLError as exc:
|
|
205
|
+
raise PolicyError([PolicyIssue("invalid YAML")]) from exc
|
|
206
|
+
|
|
207
|
+
try:
|
|
208
|
+
policy = Policy.model_validate(raw)
|
|
209
|
+
except ValidationError as exc:
|
|
210
|
+
issues = []
|
|
211
|
+
for error in exc.errors(include_url=False, include_input=False):
|
|
212
|
+
loc = tuple(error["loc"])
|
|
213
|
+
line, column = _locate(root, loc)
|
|
214
|
+
where = ".".join(str(part) for part in loc)
|
|
215
|
+
issues.append(PolicyIssue(f"{where}: {error['msg']}", line, column))
|
|
216
|
+
raise PolicyError(issues) from exc
|
|
217
|
+
|
|
218
|
+
problems: list[tuple[str, _Loc]] = []
|
|
219
|
+
resolved = _resolve_roles(policy, problems)
|
|
220
|
+
problems += _semantic_problems(policy, resolved)
|
|
221
|
+
if problems:
|
|
222
|
+
issues = []
|
|
223
|
+
for message, loc in problems:
|
|
224
|
+
line, column = _locate(root, loc)
|
|
225
|
+
issues.append(PolicyIssue(message, line, column))
|
|
226
|
+
raise PolicyError(issues)
|
|
227
|
+
|
|
228
|
+
return CompiledPolicy(
|
|
229
|
+
policy=policy,
|
|
230
|
+
sha256=sha256_hex(data),
|
|
231
|
+
roles=resolved,
|
|
232
|
+
allowed_repos=frozenset(repo.casefold() for repo in policy.repos.allow),
|
|
233
|
+
denied_paths=pathspec.PathSpec.from_lines(
|
|
234
|
+
"gitignore", [pattern.casefold() for pattern in policy.paths.deny]
|
|
235
|
+
),
|
|
236
|
+
rate_limits={tool: limit.per_minute for tool, limit in policy.rate_limits.items()},
|
|
237
|
+
)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def load_policy(path: Path) -> CompiledPolicy:
|
|
241
|
+
try:
|
|
242
|
+
data = path.read_bytes()
|
|
243
|
+
except OSError as exc:
|
|
244
|
+
raise PolicyError([PolicyIssue(f"cannot read policy file: {exc.strerror}")]) from exc
|
|
245
|
+
return parse_policy(data)
|