@mokuyoaxis/agent-guard 0.2.3-rc1 → 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 +124 -52
- package/README.zh-CN.md +102 -41
- package/adapters/dsh/README.md +92 -10
- package/adapters/dsh/harness/README.md +384 -0
- package/adapters/dsh/harness/baseline.patch.yml +8 -0
- 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 +771 -0
- package/adapters/dsh/harness/native_session.py +503 -0
- package/adapters/dsh/harness/profiles.py +212 -0
- package/adapters/dsh/harness/read_fixture.py +60 -0
- package/adapters/dsh/harness/retry_stream.py +171 -0
- package/adapters/dsh/harness/session_decode.mjs +117 -0
- package/adapters/dsh/lib/index.js +46 -5
- package/adapters/dsh/lib/read_result_guard.js +207 -0
- package/adapters/dsh/lib/read_result_guard.py +139 -0
- package/adapters/harness_support.py +109 -0
- package/adapters/kimi-code/README.md +15 -7
- package/adapters/kimi-code/harness/README.md +126 -0
- package/adapters/kimi-code/harness/guard_lab.py +430 -0
- package/core/lab.py +2396 -0
- package/core/redaction.py +157 -55
- package/docs/architecture.md +75 -0
- package/docs/development-note-unguarded-deletion.md +6 -7
- package/docs/friction.md +140 -4
- package/docs/guard-lab-clean-task.md +4 -0
- package/docs/guard-lab-read-trial-task.md +7 -0
- package/docs/guard-lab-trial-task.md +5 -0
- package/docs/guard-lab.md +398 -0
- package/docs/harness-capabilities.md +8 -5
- 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-rc2.md +189 -0
- package/docs/release-notes-0.2.3.md +84 -0
- 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-dsh-0.2-upgrade.md +142 -0
- package/docs/test-report-dsh-guard-lab.md +154 -0
- package/docs/test-report-dsh-native-session.md +118 -0
- package/docs/test-report-dsh-paired-lab.md +183 -0
- package/docs/test-report-dsh-read-redaction.md +114 -0
- package/docs/test-report-dsh-real-followup.md +170 -0
- package/docs/test-report-dsh-retry-evidence.md +134 -0
- package/docs/test-report-kimi-code-block.md +19 -20
- package/docs/test-report-kimi-guard-lab.md +117 -0
- package/docs/test-report-release-readiness-0.2.3.md +239 -0
- package/docs/test-report-workbuddy-windows-core.md +53 -0
- package/docs/test-report-zcode-glm-flash.md +9 -9
- package/docs/threat-model.md +42 -0
- package/guard_lab.py +14 -0
- package/package.json +8 -5
- 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
|
@@ -21,9 +21,19 @@ forfeits automation. A payload carrying both a sanitizable secret and an
|
|
|
21
21
|
un-rewritable shape must ASK - you cannot silently proceed when part of the
|
|
22
22
|
emission is uninspectable.
|
|
23
23
|
|
|
24
|
-
Exit codes (`check_span.py`): `0` allow/sanitize · `2` block · `3` ask ·
|
|
24
|
+
Exit codes (`check_span.py` and `sanitize.py`): `0` allow/sanitize · `2` block · `3` ask ·
|
|
25
25
|
`1` error.
|
|
26
26
|
|
|
27
|
+
The checker returns a proposal. The sanitizer outputs a payload only after
|
|
28
|
+
ALLOW or a verified SANITIZE; ASK/BLOCK/errors produce no payload on stdout.
|
|
29
|
+
External plans must match the freshly derived offsets and placeholders, with
|
|
30
|
+
any supplied metadata agreeing too. Missing, extra, overlapping or stale ranges
|
|
31
|
+
and arbitrary replacements are refused. Revalidation binds the plan to current
|
|
32
|
+
scan facts, not to a byte-identical input fingerprint. The library returns empty
|
|
33
|
+
`text` for ASK/BLOCK. Both CLIs share default workspace/mode resolution; the
|
|
34
|
+
checker retains its explicit mode/path overrides, which are not authorization
|
|
35
|
+
for the sanitizer. Input and plan files are bounded UTF-8 text.
|
|
36
|
+
|
|
27
37
|
## Reason codes
|
|
28
38
|
|
|
29
39
|
| Code | Decision | Meaning |
|
|
@@ -37,7 +47,7 @@ Exit codes (`check_span.py`): `0` allow/sanitize · `2` block · `3` ask ·
|
|
|
37
47
|
| `BLOCK_SECRET_EMISSION` | BLOCK | credential about to enter immutable/remote history |
|
|
38
48
|
| `BLOCK_PATH_EMISSION` | BLOCK | host path about to enter immutable/remote history |
|
|
39
49
|
| `BLOCK_SECRET_SOURCE_DUMP` | BLOCK | the payload reads a secret store the guard cannot see into |
|
|
40
|
-
| `BLOCK_OUTPUT_UNSCANNABLE` | BLOCK | never scanned: unknown channel, over cap,
|
|
50
|
+
| `BLOCK_OUTPUT_UNSCANNABLE` | BLOCK | never scanned: unknown channel, over cap, scanner error |
|
|
41
51
|
|
|
42
52
|
## Rule table (first match wins)
|
|
43
53
|
|
|
@@ -46,7 +56,7 @@ Exit codes (`check_span.py`): `0` allow/sanitize · `2` block · `3` ask ·
|
|
|
46
56
|
| 1 | payload reads a secret store (`.env`, `*.pem`, `id_rsa*`, `kubeconfig`, `printenv`, `env \| …`) | BLOCK | `BLOCK_SECRET_SOURCE_DUMP` |
|
|
47
57
|
| 2 | match is a placeholder / already-redacted marker | ALLOW | `ALLOW_SECRET_PLACEHOLDER` |
|
|
48
58
|
| 3 | path is workspace-relative (and not the root itself) | ALLOW | `ALLOW_PATH_IN_WORKSPACE` |
|
|
49
|
-
| 4 | channel unknown or payload over the scan cap /
|
|
59
|
+
| 4 | channel unknown or payload over the scan cap / scanner error | BLOCK | `BLOCK_OUTPUT_UNSCANNABLE` |
|
|
50
60
|
| 5 | channel is immutable history (`git-commit-message`, `git-push-payload`) | BLOCK | `BLOCK_*_EMISSION` |
|
|
51
61
|
| 6 | channel is neither rewritable nor persistent (`shell-stdout`) | ASK | `ASK_*_EMISSION` |
|
|
52
62
|
| 7 | secret, `deterministic` (T1) or context gate fired | SANITIZE | `SANITIZE_SECRET_REDACT` |
|
|
@@ -63,19 +73,72 @@ loosens a BLOCK.
|
|
|
63
73
|
| Rule id | Shape | Anchor |
|
|
64
74
|
|---|---|---|
|
|
65
75
|
| `secret/openai-key` | `sk-` + 20+ url-safe chars, incl. `sk-proj-`/`sk-ant-`/`sk-live-` | prefix + length + charset |
|
|
66
|
-
| `secret/github-token` | `ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_` + 36; `github_pat_` + 22
|
|
67
|
-
| `secret/aws-access-key-id` | `AKIA`/`ASIA
|
|
76
|
+
| `secret/github-token` | classic `ghp_`/`gho_`/`ghu_`/`ghs_`/`ghr_` + 36; `github_pat_` + 22–255; `ghs_APPID_JWT` installation wrapper | vendor prefix; new wrapper has a structural JWT header |
|
|
77
|
+
| `secret/aws-access-key-id` | `AKIA`/`ASIA` + 16 upper-alnum | access-key identifier prefixes |
|
|
68
78
|
| `secret/gitlab-token` | `glpat-` + 20+ | prefix |
|
|
69
79
|
| `secret/slack-token` | `xox[baprs]-` | prefix |
|
|
70
80
|
| `secret/stripe-key` | `sk_live_`/`rk_live_` (never `sk_test_`) | prefix + live mode |
|
|
71
|
-
| `secret/
|
|
81
|
+
| `secret/pypi-token` | `pypi-` + 85+ base64url body characters, without a fixed maximum | documented vendor scanner shape |
|
|
82
|
+
| `secret/jwt` | three base64url segments; header decodes to JSON with a nonempty ASCII string `alg` | **structural**, not just `a.b.c` |
|
|
72
83
|
| `secret/private-key-block` | `-----BEGIN [X ]*PRIVATE KEY-----` … `-----END …` | delimiters; whole block withheld |
|
|
73
|
-
| `secret/
|
|
84
|
+
| `secret/connection-password` | nonempty password between the first userinfo colon and final `@` in a `scheme://` authority | URI credential context; only password withheld |
|
|
85
|
+
| `secret/source-reference` | an env-var *name* with a complete credential component, a secret-store file name, or a whole-environment expansion | value-free (T2) |
|
|
86
|
+
|
|
87
|
+
Vendor/JWT boundaries use ASCII identifier characters so credentials adjacent
|
|
88
|
+
to CJK prose are detected while English identifier substrings stay quiet.
|
|
89
|
+
The new GitHub installation rule retains the complete `ghs_APPID_JWT` wrapper,
|
|
90
|
+
including long signatures, under the normal payload cap. App ID is opaque;
|
|
91
|
+
the JWT header must decode to JSON with a nonempty ASCII string `alg`. Generic
|
|
92
|
+
JWT detection requires that same declared header type. No business claims,
|
|
93
|
+
issuer, expiry or signature are authenticated, and algorithms are not limited
|
|
94
|
+
to a hardcoded enum. Format references: [GitHub's format notice](https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/)
|
|
95
|
+
and [updated format guidance](https://github.blog/changelog/2026-05-15-github-app-installation-tokens-per-request-override-header/).
|
|
96
|
+
|
|
97
|
+
AWS group/user/role/policy IDs (`AGPA`/`AIDA`/`AROA`/`ANPA`) are resource
|
|
98
|
+
identifiers and are excluded from the access-key rule, following the
|
|
99
|
+
[AWS prefix table](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids).
|
|
100
|
+
Their appearance inside a URI password or another credential context does not
|
|
101
|
+
exempt that enclosing credential. The JWT header type follows
|
|
102
|
+
[RFC 7515 §4.1.1](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.1).
|
|
103
|
+
|
|
104
|
+
PyPI detection follows its [official scanner format](https://docs.pypi.org/api/secrets/#detecting-the-pypi-secret-format).
|
|
105
|
+
The entire body is captured under the normal payload cap, including longer
|
|
106
|
+
Macaroon caveats. `pypi-client-library`, short examples and whole placeholders
|
|
107
|
+
remain quiet. This is shape detection, without deserializing the Macaroon,
|
|
108
|
+
verifying authorization or reporting/revoking tokens through PyPI's API.
|
|
109
|
+
The legacy broad `sk-` shape remains protected pending a complete format
|
|
110
|
+
review; ordinary long component names with that shape can still match.
|
|
111
|
+
|
|
112
|
+
Variable references support `$NAME`, `${NAME}`, `$env:NAME` and `%NAME%`.
|
|
113
|
+
Underscores and camelCase/acronym boundaries separate complete components:
|
|
114
|
+
`TOKEN`, `PASSWORD`, `API_KEY` and `accessToken` are credential names;
|
|
115
|
+
`MONKEY` and `API_KEYBOARD` are not. A terminal `COUNT`, `LENGTH` or `ENABLED`
|
|
116
|
+
component denotes metadata (`TOKEN_COUNT`, `KEY_ENABLED`). Arbitrarily glued
|
|
117
|
+
lowercase/all-capital names are not split by substring guessing. Public-key
|
|
118
|
+
names retain the existing conservative behavior; there is no `PUBLIC*`
|
|
119
|
+
exemption. A benign first reference cannot hide a later credential reference.
|
|
120
|
+
Names are classified without resolving or reading their values.
|
|
121
|
+
Bare lower/title-case `key` (`$key`, `${key}`) is ambiguous with an ordinary
|
|
122
|
+
dictionary/schema key and is not classified by name alone. Uppercase `KEY`,
|
|
123
|
+
qualified names such as `apiKey`, and explicit `$env:key`/`%key%` references
|
|
124
|
+
remain protected. This narrow name boundary does not exempt source files or
|
|
125
|
+
template expressions as a whole; stronger names still cause refusal.
|
|
126
|
+
|
|
127
|
+
The URI rule uses original text coordinates. It supports percent encoding,
|
|
128
|
+
JSON-escaped scheme slashes, empty usernames (e.g. Redis), and literal `@`
|
|
129
|
+
inside a password by selecting the final authority separator. Complete
|
|
130
|
+
template expressions (`<PASSWORD>`, `${VAR}`, `%VAR%`) and redaction markers are
|
|
131
|
+
exempt; plain short/weak passwords are not. Variable-reference facts still
|
|
132
|
+
apply independently and cannot be swallowed by an overlapping URI span.
|
|
133
|
+
Raw `/`, `?`, `#`, whitespace and quote delimiters end the authority: encode
|
|
134
|
+
them inside a password. This rule does not cover non-URI DSNs, fully encoded
|
|
135
|
+
URLs or arbitrary nested serialization. Accounts and hosts remain visible.
|
|
136
|
+
Syntax reference: [RFC 3986 §3.2.1](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.2.1).
|
|
74
137
|
|
|
75
138
|
Two design rules that keep T1 deterministic:
|
|
76
139
|
|
|
77
140
|
1. **Structural validation** where the format allows it. A JWT is only a JWT
|
|
78
|
-
if segment 1 base64-decodes to JSON with `alg`; otherwise it is a version
|
|
141
|
+
if segment 1 base64-decodes to JSON with the declared ASCII string `alg`; otherwise it is a version
|
|
79
142
|
string (`1.2.3`) or a hostname (`api.example.com`), both of which occur
|
|
80
143
|
constantly in this repository's own text.
|
|
81
144
|
2. **No generic keyword patterns.** `password=` / `secret=` are *context*
|
|
@@ -109,19 +172,24 @@ repository's own prose quiet.
|
|
|
109
172
|
|
|
110
173
|
## Placeholder allowlist (design 5.1)
|
|
111
174
|
|
|
112
|
-
Deterministic, in-repo, no config:
|
|
113
|
-
`
|
|
114
|
-
`<REDACTED
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
175
|
+
Deterministic, in-repo, no config: exact static words such as
|
|
176
|
+
`YOUR_API_KEY_HERE`, `EXAMPLE_SECRET`, `dummy-value`, `changeme`, `test`,
|
|
177
|
+
`fake`, `placeholder` and `TODO`; whole `<REDACTED>`/`[REDACTED]` markers,
|
|
178
|
+
identifier templates (`<TOKEN>`, `${NAME}`), and whole trivial-alphabet bodies.
|
|
179
|
+
Known public vendor prefixes can be removed before checking the entire body,
|
|
180
|
+
so explicit vendor examples (`sk-test`, a vendor prefix followed only by `x`)
|
|
181
|
+
remain quiet. The two fixed AWS documentation example IDs are exact entries.
|
|
182
|
+
An arbitrary random credential containing `xxx`, `dummy` or `redact`, or
|
|
183
|
+
ending in `none`/`example`, is not a placeholder. A marker word inside a
|
|
184
|
+
private-key block cannot exempt the entire block. Independent secret-source
|
|
185
|
+
facts still apply to variable templates.
|
|
118
186
|
|
|
119
187
|
## Configuration (environment)
|
|
120
188
|
|
|
121
189
|
| Variable | Meaning |
|
|
122
190
|
|---|---|
|
|
123
|
-
| `AGENT_GUARD_EXFIL_CHANNEL` | default egress channel for
|
|
124
|
-
| `AGENT_GUARD_EXFIL_MAX_BYTES` |
|
|
191
|
+
| `AGENT_GUARD_EXFIL_CHANNEL` | default egress channel for both text CLIs |
|
|
192
|
+
| `AGENT_GUARD_EXFIL_MAX_BYTES` | input/scan cap (default 4 MiB); over-cap input is `BLOCK_OUTPUT_UNSCANNABLE`; sanitizer plan files use the same bound |
|
|
125
193
|
| `AGENT_GUARD_HOSTNAMES` / `AGENT_GUARD_HOME_MARKERS` | extra literal host names / home markers |
|
|
126
194
|
| `AGENT_GUARD_HOME_PREFIXES` | extra literal prefixes to treat as host-identifying |
|
|
127
195
|
| `AGENT_GUARD_SYSTEM_PREFIXES` | override the system-prefix allow set |
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
"""Shared, bounded CLI input and host-side context resolution."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import os
|
|
5
|
+
import sys
|
|
6
|
+
import time
|
|
7
|
+
|
|
8
|
+
from core import policy, redaction
|
|
9
|
+
from core.classifier import discover_workspace
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
DEFAULT_STDIN_TIMEOUT_SEC = 10.0
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class StdinIdle(Exception):
|
|
16
|
+
"""No first byte arrived within the configured wait."""
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class PayloadTooLarge(Exception):
|
|
20
|
+
"""Fixed, value-free diagnostic for an input budget refusal."""
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _stdin_timeout():
|
|
24
|
+
try:
|
|
25
|
+
value = float(os.environ.get("AGENT_GUARD_STDIN_TIMEOUT", ""))
|
|
26
|
+
except (TypeError, ValueError):
|
|
27
|
+
return DEFAULT_STDIN_TIMEOUT_SEC
|
|
28
|
+
return value if 0 < value < float("inf") else DEFAULT_STDIN_TIMEOUT_SEC
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def read_bounded_text(stream, max_bytes):
|
|
32
|
+
"""Read at most the cap plus one byte, then strictly decode UTF-8.
|
|
33
|
+
|
|
34
|
+
Text-only streams (e.g. StringIO) are bounded in characters first and
|
|
35
|
+
checked in bytes next. They retain at most four times the byte cap.
|
|
36
|
+
No partial input is ever returned as a successful payload.
|
|
37
|
+
"""
|
|
38
|
+
if type(max_bytes) is not int or max_bytes < 0:
|
|
39
|
+
raise ValueError("invalid payload size limit")
|
|
40
|
+
source = getattr(stream, "buffer", stream)
|
|
41
|
+
chunks = []
|
|
42
|
+
total = 0
|
|
43
|
+
kind = None
|
|
44
|
+
while True:
|
|
45
|
+
data = source.read(min(65536, max_bytes + 1 - total))
|
|
46
|
+
if not isinstance(data, (str, bytes)) or (kind is not None and type(data) is not kind):
|
|
47
|
+
raise ValueError("invalid input stream")
|
|
48
|
+
kind = type(data)
|
|
49
|
+
if not data:
|
|
50
|
+
break
|
|
51
|
+
total += len(data.encode("utf-8", errors="strict")) if isinstance(data, str) else len(data)
|
|
52
|
+
if total > max_bytes:
|
|
53
|
+
raise PayloadTooLarge("payload exceeds scan cap")
|
|
54
|
+
chunks.append(data)
|
|
55
|
+
if kind is str:
|
|
56
|
+
return "".join(chunks)
|
|
57
|
+
return b"".join(chunks).decode("utf-8", errors="strict")
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def read_payload(stream=None, timeout=None, max_bytes=None):
|
|
61
|
+
"""Bound payload memory; retain the existing first-byte timeout.
|
|
62
|
+
|
|
63
|
+
This is not an end-to-end transport deadline: once a producer has
|
|
64
|
+
spoken, reading still waits for EOF or the size refusal boundary.
|
|
65
|
+
"""
|
|
66
|
+
stdin = stream if stream is not None else sys.stdin
|
|
67
|
+
limit = redaction.max_scan_bytes() if max_bytes is None else max_bytes
|
|
68
|
+
if stdin.isatty():
|
|
69
|
+
sys.stderr.write("exfil-guard: reading payload from stdin "
|
|
70
|
+
"(Ctrl-D to finish)\n")
|
|
71
|
+
return read_bounded_text(stdin, limit)
|
|
72
|
+
try:
|
|
73
|
+
import select
|
|
74
|
+
except ImportError: # pragma: no cover - non-POSIX
|
|
75
|
+
return read_bounded_text(stdin, limit)
|
|
76
|
+
budget = _stdin_timeout() if timeout is None else timeout
|
|
77
|
+
deadline = time.monotonic() + budget
|
|
78
|
+
while True:
|
|
79
|
+
remaining = deadline - time.monotonic()
|
|
80
|
+
if remaining <= 0:
|
|
81
|
+
raise StdinIdle("no payload arrived on stdin within the wait; "
|
|
82
|
+
"pipe the text in or use a terminal")
|
|
83
|
+
try:
|
|
84
|
+
ready, _, _ = select.select([stdin], [], [], min(remaining, 0.5))
|
|
85
|
+
except (OSError, ValueError):
|
|
86
|
+
return read_bounded_text(stdin, limit)
|
|
87
|
+
if ready:
|
|
88
|
+
return read_bounded_text(stdin, limit)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def resolve_context(workspace=None, mode=None):
|
|
92
|
+
"""Read the same workspace and host-side mode for both text CLIs."""
|
|
93
|
+
if workspace is None:
|
|
94
|
+
workspace = discover_workspace(os.getcwd())
|
|
95
|
+
if mode is None:
|
|
96
|
+
trash_root = os.environ.get(
|
|
97
|
+
"AGENT_GUARD_TRASH", os.path.join(workspace, ".agent-trash"))
|
|
98
|
+
mode = policy.load_mode(trash_root)["mode"]
|
|
99
|
+
return workspace, mode
|
|
@@ -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
|