@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.3
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/README.md +88 -47
- package/README.zh-CN.md +71 -39
- package/adapters/dsh/README.md +15 -10
- package/adapters/dsh/harness/README.md +68 -12
- package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
- package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
- package/adapters/dsh/harness/guard_lab.py +191 -29
- package/adapters/dsh/harness/native_session.py +41 -20
- package/adapters/dsh/harness/profiles.py +74 -22
- package/adapters/kimi-code/README.md +8 -7
- package/core/lab.py +24 -1
- package/core/redaction.py +157 -55
- package/docs/development-note-unguarded-deletion.md +6 -7
- package/docs/friction.md +68 -4
- package/docs/guard-lab-read-trial-task.md +7 -0
- package/docs/guard-lab.md +7 -0
- package/docs/harness-capabilities.md +1 -1
- package/docs/release-notes-0.2.0-rc1.md +2 -2
- package/docs/release-notes-0.2.0.md +2 -2
- package/docs/release-notes-0.2.2.md +7 -8
- package/docs/release-notes-0.2.3-rc1.md +4 -2
- package/docs/release-notes-0.2.3.md +51 -12
- package/docs/secret-guard-analysis.md +13 -12
- package/docs/secret-guard-architecture.md +5 -3
- package/docs/secret-guard-design.md +7 -3
- package/docs/test-report-codex-gpt-5.6-sol.md +10 -11
- package/docs/test-report-kimi-code-block.md +19 -20
- package/docs/test-report-release-readiness-0.2.3.md +78 -0
- package/docs/test-report-workbuddy-windows-core.md +53 -0
- package/docs/test-report-zcode-glm-flash.md +9 -9
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +2 -3
- package/skills/exfil-guard/SKILL.md +37 -7
- package/skills/exfil-guard/references/rules.md +84 -16
- package/skills/exfil-guard/scripts/_payload.py +99 -0
- package/skills/exfil-guard/scripts/check_span.py +14 -81
- package/skills/exfil-guard/scripts/sanitize.py +113 -34
|
@@ -31,7 +31,6 @@ import argparse
|
|
|
31
31
|
import json
|
|
32
32
|
import os
|
|
33
33
|
import sys
|
|
34
|
-
import time
|
|
35
34
|
|
|
36
35
|
import _bootstrap # noqa: F401
|
|
37
36
|
|
|
@@ -40,65 +39,7 @@ from core.redaction import (
|
|
|
40
39
|
CHANNELS, UNREACHABLE_CHANNELS, get_channel, scan_text,
|
|
41
40
|
)
|
|
42
41
|
from core import policy
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
# A non-interactive caller that opens a pipe but never writes to it would
|
|
46
|
-
# otherwise sit in `sys.stdin.read()` until the *host's* tool timeout kills
|
|
47
|
-
# the call: the guard presents as a hang instead of a refusal, and a
|
|
48
|
-
# mistyped invocation costs the caller a whole timeout window. Wait a
|
|
49
|
-
# bounded time for the first byte - once a producer has spoken, read to EOF
|
|
50
|
-
# as usual - and refuse loudly if nothing ever arrives. Interactive use is
|
|
51
|
-
# unchanged. Override with AGENT_GUARD_STDIN_TIMEOUT (seconds).
|
|
52
|
-
DEFAULT_STDIN_TIMEOUT_SEC = 10.0
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
class StdinIdle(Exception):
|
|
56
|
-
"""No payload arrived on stdin within the caller's patience."""
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
def _stdin_timeout() -> float:
|
|
60
|
-
try:
|
|
61
|
-
value = float(os.environ.get("AGENT_GUARD_STDIN_TIMEOUT", ""))
|
|
62
|
-
except (TypeError, ValueError):
|
|
63
|
-
return DEFAULT_STDIN_TIMEOUT_SEC
|
|
64
|
-
return value if value > 0 else DEFAULT_STDIN_TIMEOUT_SEC
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
def read_payload(stream=None, timeout=None) -> str:
|
|
68
|
-
"""Read the payload from stdin without hanging a non-interactive caller.
|
|
69
|
-
|
|
70
|
-
A TTY is a human ending the stream with Ctrl-D: keep blocking. Anything
|
|
71
|
-
else is a producer that is expected to have spoken already, so the wait
|
|
72
|
-
for its first byte is bounded. A pipe that closes without data (EOF) is
|
|
73
|
-
a legitimately empty payload and returns "" for the normal scan path.
|
|
74
|
-
"""
|
|
75
|
-
stdin = stream if stream is not None else sys.stdin
|
|
76
|
-
if stdin.isatty():
|
|
77
|
-
sys.stderr.write("exfil-guard: reading payload from stdin "
|
|
78
|
-
"(Ctrl-D to finish)\n")
|
|
79
|
-
return stdin.read()
|
|
80
|
-
try:
|
|
81
|
-
import select
|
|
82
|
-
except ImportError: # pragma: no cover - non-POSIX
|
|
83
|
-
return stdin.read()
|
|
84
|
-
budget = _stdin_timeout() if timeout is None else timeout
|
|
85
|
-
deadline = time.monotonic() + budget
|
|
86
|
-
while True:
|
|
87
|
-
remaining = deadline - time.monotonic()
|
|
88
|
-
if remaining <= 0:
|
|
89
|
-
raise StdinIdle(
|
|
90
|
-
f"no payload arrived on stdin within {budget:g}s; pipe the "
|
|
91
|
-
"text in, or run it on a terminal to type it")
|
|
92
|
-
try:
|
|
93
|
-
ready, _, _ = select.select([stdin], [], [],
|
|
94
|
-
min(remaining, 0.5))
|
|
95
|
-
except (OSError, ValueError):
|
|
96
|
-
# stdin is not selectable on this platform (e.g. a Windows
|
|
97
|
-
# pipe). Fall back to the blocking read rather than refusing a
|
|
98
|
-
# caller whose payload may be perfectly good.
|
|
99
|
-
return stdin.read()
|
|
100
|
-
if ready:
|
|
101
|
-
return stdin.read()
|
|
42
|
+
from _payload import PayloadTooLarge, StdinIdle, read_payload, resolve_context
|
|
102
43
|
|
|
103
44
|
|
|
104
45
|
def build_redaction_plan(spans, decisions, channel) -> list:
|
|
@@ -129,30 +70,11 @@ def main() -> int:
|
|
|
129
70
|
"repo-local exemption file for that path")
|
|
130
71
|
args = ap.parse_args()
|
|
131
72
|
|
|
132
|
-
workspace = args.workspace
|
|
133
|
-
if workspace is None:
|
|
134
|
-
from core.classifier import discover_workspace
|
|
135
|
-
workspace = discover_workspace(os.getcwd())
|
|
136
|
-
|
|
137
|
-
mode = args.mode
|
|
138
|
-
if mode is None:
|
|
139
|
-
trash_root = os.environ.get(
|
|
140
|
-
"AGENT_GUARD_TRASH", os.path.join(workspace, ".agent-trash"))
|
|
141
|
-
try:
|
|
142
|
-
mode = policy.load_mode(trash_root)["mode"]
|
|
143
|
-
except Exception: # noqa: BLE001 - state is advisory
|
|
144
|
-
mode = policy.MODE_NORMAL
|
|
73
|
+
workspace, mode = resolve_context(args.workspace, args.mode)
|
|
145
74
|
|
|
146
75
|
channel_name = (args.channel or "").strip().lower()
|
|
147
76
|
channel = get_channel(channel_name)
|
|
148
77
|
|
|
149
|
-
try:
|
|
150
|
-
text = read_payload()
|
|
151
|
-
except StdinIdle as exc:
|
|
152
|
-
return _fail(str(exc), args.as_json)
|
|
153
|
-
except (OSError, UnicodeDecodeError) as exc:
|
|
154
|
-
return _fail(f"could not read stdin: {exc}", args.as_json)
|
|
155
|
-
|
|
156
78
|
out = {
|
|
157
79
|
"channel": channel_name,
|
|
158
80
|
"channel_known": channel is not None,
|
|
@@ -160,9 +82,20 @@ def main() -> int:
|
|
|
160
82
|
"channel_persistence": channel.persistence if channel else None,
|
|
161
83
|
"workspace": workspace,
|
|
162
84
|
"mode": mode,
|
|
163
|
-
"size_bytes": len(text.encode("utf-8", errors="replace")),
|
|
164
85
|
}
|
|
165
86
|
|
|
87
|
+
try:
|
|
88
|
+
text = read_payload(max_bytes=args.max_bytes)
|
|
89
|
+
except PayloadTooLarge:
|
|
90
|
+
out.update(scanned=False, reason="payload exceeds scan cap")
|
|
91
|
+
return _emit(out, policy.DECISION_BLOCK,
|
|
92
|
+
policy.CODE_BLOCK_OUTPUT_UNSCANNABLE, [], [], args, 2)
|
|
93
|
+
except StdinIdle as exc:
|
|
94
|
+
return _fail(str(exc), args.as_json)
|
|
95
|
+
except (OSError, UnicodeError, ValueError):
|
|
96
|
+
return _fail("could not read a bounded UTF-8 payload", args.as_json)
|
|
97
|
+
out["size_bytes"] = len(text.encode("utf-8", errors="strict"))
|
|
98
|
+
|
|
166
99
|
if channel is None:
|
|
167
100
|
# An unknown channel name is a configuration defect, and a channel
|
|
168
101
|
# the guard cannot name is one it cannot certify. Fail closed.
|
|
@@ -14,13 +14,15 @@ so a shell pipeline can use it without writing code:
|
|
|
14
14
|
Two properties are load-bearing:
|
|
15
15
|
|
|
16
16
|
* **Format preservation.** A redacted secret keeps the shape a reader needs
|
|
17
|
-
to recognise it (`sk-proj-Ab…` -> `sk
|
|
17
|
+
to recognise it (`sk-proj-Ab…` -> `sk-<REDACTED>`), never the bytes.
|
|
18
18
|
For paths the placeholder is `<PATH>`.
|
|
19
19
|
* **Leak freedom.** The plan carries offsets and placeholders only, and the
|
|
20
20
|
output is built by *replacing* the matched ranges - so no code path here
|
|
21
21
|
can echo a matched secret into stdout, the plan, or an error message.
|
|
22
22
|
|
|
23
|
-
Exit codes: 0 applied
|
|
23
|
+
Exit codes: 0 allow/applied | 2 block | 3 ask | 1 error.
|
|
24
|
+
Refusals and errors emit no payload. External plans are revalidated against
|
|
25
|
+
the current scan; they are never an authorization to bypass its verdict.
|
|
24
26
|
"""
|
|
25
27
|
from __future__ import annotations
|
|
26
28
|
|
|
@@ -34,6 +36,8 @@ import _bootstrap # noqa: F401
|
|
|
34
36
|
|
|
35
37
|
from core import policy, redaction
|
|
36
38
|
from core.redaction import get_channel, scan_text
|
|
39
|
+
from _payload import (PayloadTooLarge, StdinIdle, read_bounded_text,
|
|
40
|
+
read_payload, resolve_context)
|
|
37
41
|
|
|
38
42
|
REDACTED = "<REDACTED>"
|
|
39
43
|
PATH_PLACEHOLDER = "<PATH>"
|
|
@@ -46,12 +50,13 @@ def placeholder_for(span) -> str:
|
|
|
46
50
|
"""The replacement text for one span; derived from shape, never content."""
|
|
47
51
|
if span.family != redaction.FAMILY_SECRET:
|
|
48
52
|
return PATH_PLACEHOLDER
|
|
49
|
-
if span.rule_id
|
|
53
|
+
if span.rule_id in (redaction.RULE_PRIVATE_KEY_BLOCK,
|
|
54
|
+
redaction.RULE_CONNECTION_PASSWORD):
|
|
50
55
|
return REDACTED
|
|
51
56
|
# Keep the vendor prefix: it is public information (it says *which*
|
|
52
57
|
# credential kind leaked) and it is what makes the output reviewable.
|
|
53
58
|
match = re.match(r"^(sk-|rk_|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|"
|
|
54
|
-
r"glpat-|xox[baprs]-|AKIA|ASIA|
|
|
59
|
+
r"glpat-|xox[baprs]-|pypi-|AKIA|ASIA|"
|
|
55
60
|
r"sk_live_|rk_live_)", span.raw)
|
|
56
61
|
if match:
|
|
57
62
|
return match.group(1) + REDACTED
|
|
@@ -70,26 +75,61 @@ def plan_for_span(span, channel=None) -> dict:
|
|
|
70
75
|
}
|
|
71
76
|
|
|
72
77
|
|
|
73
|
-
def
|
|
74
|
-
"""
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
applied blindly: a wrong splice would silently corrupt the payload,
|
|
78
|
-
which is the false-SANITIZE failure mode the analysis warns about.
|
|
79
|
-
"""
|
|
78
|
+
def _plan_pieces(text, plan):
|
|
79
|
+
"""Validate every range before constructing any output."""
|
|
80
|
+
if not isinstance(plan, list):
|
|
81
|
+
raise ValueError("redaction plan must be a list")
|
|
80
82
|
pieces = []
|
|
81
|
-
for entry in
|
|
83
|
+
for entry in plan:
|
|
84
|
+
if not isinstance(entry, dict) or not {"start", "end", "placeholder"}.issubset(entry):
|
|
85
|
+
raise ValueError("invalid redaction plan entry")
|
|
82
86
|
start, end = entry["start"], entry["end"]
|
|
87
|
+
if type(start) is not int or type(end) is not int:
|
|
88
|
+
raise ValueError("redaction offsets must be integers")
|
|
83
89
|
if start < 0 or end > len(text) or start >= end:
|
|
84
90
|
raise ValueError("redaction plan has an out-of-range span")
|
|
91
|
+
if not isinstance(entry["placeholder"], str) or not entry["placeholder"]:
|
|
92
|
+
raise ValueError("invalid redaction placeholder")
|
|
85
93
|
pieces.append((start, end, entry["placeholder"]))
|
|
86
|
-
|
|
94
|
+
pieces.sort()
|
|
95
|
+
for previous, current in zip(pieces, pieces[1:]):
|
|
96
|
+
if current[0] < previous[1]:
|
|
97
|
+
raise ValueError("redaction plan has overlapping spans")
|
|
98
|
+
return pieces
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def apply_plan(text: str, plan, verify: bool = True) -> str:
|
|
102
|
+
"""Use validated original coordinates to assemble output in one pass.
|
|
103
|
+
|
|
104
|
+
`verify` is retained for callers. Structural validation is mandatory;
|
|
105
|
+
only `sanitize_text` can verify a plan against a fresh policy decision.
|
|
106
|
+
"""
|
|
107
|
+
pieces = _plan_pieces(text, plan)
|
|
108
|
+
chunks = []
|
|
109
|
+
cursor = 0
|
|
87
110
|
for start, end, placeholder in pieces:
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
111
|
+
chunks.extend((text[cursor:start], placeholder))
|
|
112
|
+
cursor = end
|
|
113
|
+
chunks.append(text[cursor:])
|
|
114
|
+
return "".join(chunks)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _checked_plan(text, plan, derived):
|
|
118
|
+
"""Only a plan equivalent to the current scanner's plan may be replayed."""
|
|
119
|
+
# Structural validation is independent of policy/metadata checks.
|
|
120
|
+
_plan_pieces(text, plan)
|
|
121
|
+
expected = sorted(derived, key=lambda entry: entry["start"])
|
|
122
|
+
supplied = sorted(plan, key=lambda entry: entry["start"])
|
|
123
|
+
if len(supplied) != len(expected):
|
|
124
|
+
raise ValueError("redaction plan does not match the current scan")
|
|
125
|
+
for entry, actual in zip(supplied, expected):
|
|
126
|
+
if set(entry) - set(actual):
|
|
127
|
+
raise ValueError("invalid redaction plan fields")
|
|
128
|
+
if any(entry.get(key) != actual[key] for key in ("start", "end", "placeholder")):
|
|
129
|
+
raise ValueError("redaction plan does not match the current scan")
|
|
130
|
+
if any(value != actual[key] for key, value in entry.items()):
|
|
131
|
+
raise ValueError("redaction plan metadata does not match the current scan")
|
|
132
|
+
return expected
|
|
93
133
|
|
|
94
134
|
|
|
95
135
|
def sanitize_text(text: str, channel_name: str, workspace=None,
|
|
@@ -97,26 +137,58 @@ def sanitize_text(text: str, channel_name: str, workspace=None,
|
|
|
97
137
|
"""Scan + decide + apply, in one call (the library form)."""
|
|
98
138
|
channel = get_channel(channel_name)
|
|
99
139
|
if channel is None:
|
|
100
|
-
raise ValueError("unknown egress channel
|
|
101
|
-
|
|
140
|
+
raise ValueError("unknown egress channel")
|
|
141
|
+
workspace, mode = resolve_context(workspace)
|
|
142
|
+
exemption = redaction.load_exemption(workspace)
|
|
143
|
+
scan = scan_text(text, channel=channel_name, workspace=workspace,
|
|
144
|
+
exemption=exemption)
|
|
102
145
|
if not scan.scanned:
|
|
103
|
-
raise RuntimeError(
|
|
146
|
+
raise RuntimeError("payload could not be scanned")
|
|
104
147
|
ctx = policy.PolicyContext(workspace=workspace or "", trash_root="",
|
|
105
148
|
base_dir=workspace or "",
|
|
106
|
-
mode=
|
|
149
|
+
mode=mode)
|
|
107
150
|
verdicts = policy.decide_spans(scan.spans, ctx=ctx, channel=channel)
|
|
151
|
+
decision = (policy.worst(verdicts).decision if verdicts else
|
|
152
|
+
policy.DECISION_ALLOW)
|
|
108
153
|
derived = [plan_for_span(span, channel)
|
|
109
154
|
for span, verdict in zip(scan.spans, verdicts)
|
|
110
155
|
if verdict.decision == policy.DECISION_SANITIZE]
|
|
111
|
-
|
|
156
|
+
if decision not in (policy.DECISION_ALLOW, policy.DECISION_SANITIZE):
|
|
157
|
+
return {"text": "", "plan": derived, "decision": decision}
|
|
158
|
+
applied = derived if plan is None else _checked_plan(text, plan, derived)
|
|
159
|
+
rewritten = apply_plan(text, applied)
|
|
160
|
+
checked = scan_text(rewritten, channel=channel_name, workspace=workspace,
|
|
161
|
+
exemption=exemption)
|
|
162
|
+
if not checked.scanned:
|
|
163
|
+
raise RuntimeError("sanitized payload could not be scanned")
|
|
164
|
+
remaining = policy.decide_spans(checked.spans, ctx=ctx, channel=channel)
|
|
165
|
+
if remaining and policy.worst(remaining).decision != policy.DECISION_ALLOW:
|
|
166
|
+
raise RuntimeError("sanitized payload did not pass verification")
|
|
112
167
|
return {
|
|
113
|
-
"text":
|
|
168
|
+
"text": rewritten,
|
|
114
169
|
"plan": applied,
|
|
115
|
-
"decision":
|
|
116
|
-
policy.DECISION_ALLOW,
|
|
170
|
+
"decision": decision,
|
|
117
171
|
}
|
|
118
172
|
|
|
119
173
|
|
|
174
|
+
def _unique_object(pairs):
|
|
175
|
+
obj = {}
|
|
176
|
+
for key, value in pairs:
|
|
177
|
+
if key in obj:
|
|
178
|
+
raise ValueError("duplicate plan field")
|
|
179
|
+
obj[key] = value
|
|
180
|
+
return obj
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _read_plan(filename):
|
|
184
|
+
with open(filename, "rb") as stream:
|
|
185
|
+
text = read_bounded_text(stream, redaction.max_scan_bytes())
|
|
186
|
+
obj = json.loads(text, object_pairs_hook=_unique_object)
|
|
187
|
+
if not isinstance(obj, dict) or not isinstance(obj.get("redaction_plan"), list):
|
|
188
|
+
raise ValueError("invalid plan document")
|
|
189
|
+
return obj["redaction_plan"]
|
|
190
|
+
|
|
191
|
+
|
|
120
192
|
def main() -> int:
|
|
121
193
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
122
194
|
ap.add_argument("--channel", default=os.environ.get(
|
|
@@ -129,17 +201,24 @@ def main() -> int:
|
|
|
129
201
|
help="print the plan, not the sanitized text")
|
|
130
202
|
args = ap.parse_args()
|
|
131
203
|
|
|
132
|
-
workspace = args.workspace or os.environ.get("AGENT_GUARD_WORKSPACE")
|
|
133
|
-
text = sys.stdin.read()
|
|
134
|
-
plan = None
|
|
135
|
-
if args.plan:
|
|
136
|
-
with open(args.plan, "r", encoding="utf-8") as fh:
|
|
137
|
-
plan = json.load(fh).get("redaction_plan", [])
|
|
138
204
|
try:
|
|
205
|
+
workspace, _ = resolve_context(args.workspace)
|
|
206
|
+
text = read_payload()
|
|
207
|
+
plan = _read_plan(args.plan) if args.plan else None
|
|
139
208
|
result = sanitize_text(text, args.channel, workspace, plan)
|
|
140
|
-
except
|
|
141
|
-
print(
|
|
209
|
+
except PayloadTooLarge:
|
|
210
|
+
print("sanitize: BLOCK [BLOCK_OUTPUT_UNSCANNABLE] input exceeds cap",
|
|
211
|
+
file=sys.stderr)
|
|
212
|
+
return 2
|
|
213
|
+
except StdinIdle:
|
|
214
|
+
print("sanitize: no payload arrived on stdin within the wait", file=sys.stderr)
|
|
215
|
+
return 1
|
|
216
|
+
except (OSError, UnicodeError, ValueError, RuntimeError):
|
|
217
|
+
print("sanitize: payload or plan validation failed", file=sys.stderr)
|
|
142
218
|
return 1
|
|
219
|
+
if result["decision"] in (policy.DECISION_BLOCK, policy.DECISION_ASK):
|
|
220
|
+
print("sanitize: " + result["decision"] + " payload withheld", file=sys.stderr)
|
|
221
|
+
return 2 if result["decision"] == policy.DECISION_BLOCK else 3
|
|
143
222
|
if args.dry_run:
|
|
144
223
|
print(json.dumps(result["plan"], ensure_ascii=False, indent=2))
|
|
145
224
|
return 0
|