@mokuyoaxis/agent-guard 0.2.2

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 (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,194 @@
1
+ # exfil-guard rules reference (V1.y / MVP)
2
+
3
+ The frozen rule table. Rule ids are **payload**, not verdict codes: adding a
4
+ pattern is a minor release and needs no new reason code (design 2.2 rule 3).
5
+ Reason codes are the contract third parties build against.
6
+
7
+ ## Decision Protocol
8
+
9
+ | Decision | Meaning | Tier | Rank |
10
+ |---|---|---|---|
11
+ | `ALLOW` | nothing matched, or the match is provably benign (placeholder, workspace-relative path, system prefix) | SAFE | 0 |
12
+ | `SANITIZE` | the guard returns a **redaction plan**; the payload owner rewrites and emits | SAFE | 1 |
13
+ | `ASK` | single-execution authorization; the channel cannot be rewritten and cannot be un-done | AMBIGUOUS | 3 |
14
+ | `BLOCK` | refuse: immutable/remote history, un-scannable payload, invalid config | FORBIDDEN | 4 |
15
+
16
+ `RELOCATE`/`SNAPSHOT` (rank 2) belong to delete-guard and never appear here:
17
+ there is no compensation for an emission.
18
+
19
+ **Why `SANITIZE` ranks *below* `ASK`.** It is automatic (SAFE tier), while ASK
20
+ forfeits automation. A payload carrying both a sanitizable secret and an
21
+ un-rewritable shape must ASK - you cannot silently proceed when part of the
22
+ emission is uninspectable.
23
+
24
+ Exit codes (`check_span.py`): `0` allow/sanitize · `2` block · `3` ask ·
25
+ `1` error.
26
+
27
+ ## Reason codes
28
+
29
+ | Code | Decision | Meaning |
30
+ |---|---|---|
31
+ | `ALLOW_SECRET_PLACEHOLDER` | ALLOW | every match is a documented placeholder or an `<REDACTED>` marker |
32
+ | `ALLOW_PATH_IN_WORKSPACE` | ALLOW | every path is workspace-relative or a system prefix |
33
+ | `SANITIZE_SECRET_REDACT` | SANITIZE | a credential would leave; a redaction plan is returned |
34
+ | `SANITIZE_PATH_REWRITE` | SANITIZE | a host-identifying path would leave; a plan is returned |
35
+ | `ASK_SECRET_EMISSION` | ASK | credential on a channel that cannot be rewritten (stdout cannot be un-printed) |
36
+ | `ASK_PATH_EMISSION` | ASK | host path on such a channel; low severity |
37
+ | `BLOCK_SECRET_EMISSION` | BLOCK | credential about to enter immutable/remote history |
38
+ | `BLOCK_PATH_EMISSION` | BLOCK | host path about to enter immutable/remote history |
39
+ | `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, non-ASCII, scanner error |
41
+
42
+ ## Rule table (first match wins)
43
+
44
+ | # | Condition | Decision | Code |
45
+ |---|---|---|---|
46
+ | 1 | payload reads a secret store (`.env`, `*.pem`, `id_rsa*`, `kubeconfig`, `printenv`, `env \| …`) | BLOCK | `BLOCK_SECRET_SOURCE_DUMP` |
47
+ | 2 | match is a placeholder / already-redacted marker | ALLOW | `ALLOW_SECRET_PLACEHOLDER` |
48
+ | 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 / non-ASCII / scanner error | BLOCK | `BLOCK_OUTPUT_UNSCANNABLE` |
50
+ | 5 | channel is immutable history (`git-commit-message`, `git-push-payload`) | BLOCK | `BLOCK_*_EMISSION` |
51
+ | 6 | channel is neither rewritable nor persistent (`shell-stdout`) | ASK | `ASK_*_EMISSION` |
52
+ | 7 | secret, `deterministic` (T1) or context gate fired | SANITIZE | `SANITIZE_SECRET_REDACT` |
53
+ | 8 | secret, `contextual` without the context gate | ASK | `ASK_SECRET_EMISSION` |
54
+ | 9 | path matches a system prefix (`/usr`, `/etc`, `C:\Windows`, `/Users/Shared`) | ALLOW | `ALLOW_PATH_IN_WORKSPACE` |
55
+ | 10 | path is deterministic (host prefix, workspace ancestor, CI root) or the workspace root | SANITIZE | `SANITIZE_PATH_REWRITE` |
56
+ | 11 | path is contextual (generic absolute path, no host correlation) | ASK (SANITIZE in RESTRICTED) | `ASK_PATH_EMISSION` |
57
+
58
+ `RESTRICTED` tightens only: it promotes rule 11 to SANITIZE and never
59
+ loosens a BLOCK.
60
+
61
+ ## Span rules (`secret/*`)
62
+
63
+ | Rule id | Shape | Anchor |
64
+ |---|---|---|
65
+ | `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+ | fixed-format prefix |
67
+ | `secret/aws-access-key-id` | `AKIA`/`ASIA`/`AGPA`/`AIDA`/`AROA`/`ANPA` + 16 upper-alnum | globally reserved prefix |
68
+ | `secret/gitlab-token` | `glpat-` + 20+ | prefix |
69
+ | `secret/slack-token` | `xox[baprs]-` | prefix |
70
+ | `secret/stripe-key` | `sk_live_`/`rk_live_` (never `sk_test_`) | prefix + live mode |
71
+ | `secret/jwt` | three base64url segments; header decodes to JSON containing `alg` | **structural**, not just `a.b.c` |
72
+ | `secret/private-key-block` | `-----BEGIN [X ]*PRIVATE KEY-----` … `-----END …` | delimiters; whole block withheld |
73
+ | `secret/source-reference` | an env-var *name* (`*KEY*`, `*TOKEN*`, …), a secret-store file name, or a whole-environment expansion | value-free (T2) |
74
+
75
+ Two design rules that keep T1 deterministic:
76
+
77
+ 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
79
+ string (`1.2.3`) or a hostname (`api.example.com`), both of which occur
80
+ constantly in this repository's own text.
81
+ 2. **No generic keyword patterns.** `password=` / `secret=` are *context*
82
+ (T3's job). In T1 they would destroy the "deterministic ⇒ auto-sanitize"
83
+ property the whole design depends on.
84
+
85
+ ## Span rules (`path/*`)
86
+
87
+ | Rule id | Shape | Default |
88
+ |---|---|---|
89
+ | `path/workspace-relative` | inside the workspace | ALLOW (the root itself: SANITIZE) |
90
+ | `path/system` | `/usr`, `/etc`, `/opt`, `/var/...`, `/dev/null`, `C:\Windows`, `/Users/Shared` | ALLOW |
91
+ | `path/host-absolute` | under a host prefix, a CI root, or a workspace ancestor | SANITIZE |
92
+ | `path/generic-absolute` | an absolute path with no host correlation | ASK |
93
+ | `path/device` | UNC (`\\host\share`), device (`\\?\`, `\\.\pipe\`) | SANITIZE |
94
+
95
+ **The workspace-relative exemption is the core rule.** A path is only a host
96
+ identifier if it is outside the workspace. The boundary is the one
97
+ delete-guard already computes (`classifier.discover_workspace`).
98
+
99
+ **Host identity is derived, never guessed.** The deny-set is built at runtime
100
+ from `HOME`/`USERPROFILE`/`TEMP`, `getpass.getuser()`, `USER`/`LOGNAME`/
101
+ `USERNAME`, workspace ancestors (which are by definition not to be echoed
102
+ raw), and `AGENT_GUARD_HOSTNAMES`/`AGENT_GUARD_HOME_MARKERS`. The
103
+ filesystem root is deliberately excluded - `/` is an ancestor of everything
104
+ and therefore identifies nothing.
105
+
106
+ **The component floor (design 3.2).** A POSIX match needs ≥ 2 components;
107
+ `/` alone and `/project` are conventions, not hosts. This is what keeps this
108
+ repository's own prose quiet.
109
+
110
+ ## Placeholder allowlist (design 5.1)
111
+
112
+ Deterministic, in-repo, no config: `YOUR_API_KEY_HERE`, `EXAMPLE_SECRET`,
113
+ `changeme`, `dummy`, `example`, `test`, `fake`, `placeholder`, `TODO`,
114
+ `<REDACTED>`, `[REDACTED]`, `<...>` markers, `${...}` interpolations,
115
+ all-same-char runs (`xxxx`, `****`), sequential runs, and vendor-prefixed
116
+ words (`sk-test`). A token whose **alphabet** is trivial is a placeholder; a
117
+ real credential can never live in that regime.
118
+
119
+ ## Configuration (environment)
120
+
121
+ | Variable | Meaning |
122
+ |---|---|
123
+ | `AGENT_GUARD_EXFIL_CHANNEL` | default egress channel for `check_span.py` |
124
+ | `AGENT_GUARD_EXFIL_MAX_BYTES` | payload size cap (default 4 MiB); over-cap is `BLOCK_OUTPUT_UNSCANNABLE` |
125
+ | `AGENT_GUARD_HOSTNAMES` / `AGENT_GUARD_HOME_MARKERS` | extra literal host names / home markers |
126
+ | `AGENT_GUARD_HOME_PREFIXES` | extra literal prefixes to treat as host-identifying |
127
+ | `AGENT_GUARD_SYSTEM_PREFIXES` | override the system-prefix allow set |
128
+ | `AGENT_GUARD_WORKSPACE` | workspace boundary (shared with delete-guard) |
129
+ | `--path` (`check_span.py`) | the path the payload will be written to; enables the repo-local exemption file for that path |
130
+
131
+ ## Repo-local exemptions (design 5.2)
132
+
133
+ `.agent-guard/exfil-allow.toml` (or `.agent-guardignore`) is read from the
134
+ **workspace root only**, so an agent cannot add one on the fly.
135
+
136
+ ```toml
137
+ [rules]
138
+ disable = [] # rule-id globs; [] means none
139
+ [values]
140
+ sha256 = # exempt a literal WITHOUT tracking it
141
+ sha256:8ab1...e7
142
+ [paths]
143
+ ignore = # path globs skipped entirely
144
+ docs/*.md
145
+ tests/fixtures/secrets/*
146
+ ```
147
+
148
+ Three properties matter:
149
+
150
+ 1. **Value exemptions are by hash.** A human who needs one specific literal
151
+ exempted provides `sha256:...`; the guard compares hashes. Writing the
152
+ value into a tracked file *is* the bug this feature exists to prevent.
153
+ 2. **Path exemptions, not rule amnesty.** Scoping an exemption to a path
154
+ keeps the rule fully active everywhere else. Disabling the rule wholesale
155
+ is what would blind the guard.
156
+ 3. **A broken allowfile fails closed.** Malformed input is ignored and the
157
+ rules stay on - never the reverse.
158
+
159
+ This repository ships such a file for its own documentation and fixtures,
160
+ exactly as `SECURITY.md` documents "Expected scanner hits on this
161
+ repository". The `[paths]` list is a *reviewed* list: it names the files
162
+ that discuss the topic, and the noise-budget test still measures the whole
163
+ corpus.
164
+
165
+ ## Audit record shape
166
+
167
+ ```json
168
+ {"event":"exfil-sanitize","rule_id":"secret/openai-key",
169
+ "confidence":"deterministic","channel":"file-write",
170
+ "family":"secret","span":[104,151],"length":47,
171
+ "exempted":false,"plan_id":"…","ts":"…","session":"…"}
172
+ ```
173
+
174
+ No `raw`, no prefix, no suffix, **no hash of the secret** (a hash of a
175
+ low-entropy secret is offline-crackable). Rule id + offsets + length is
176
+ enough to reproduce a false positive and worthless to an attacker.
177
+
178
+ ## Noise budget (design 5.6)
179
+
180
+ On this repository's own corpus (README, `docs/`, `tests/`, `skills/`) the
181
+ default rule set must produce **zero BLOCK** and only path-family matches.
182
+ Anything else is a rule bug, not a tuning problem. Verified by
183
+ `tests/test_exfil_classifier.py::RepoCorpusNoise`.
184
+
185
+ ## Known limitations (V1.y)
186
+
187
+ - T3 (generic entropy with a context gate) is **not in this release**: it is
188
+ the single largest false-positive source, and the named scenarios do not
189
+ require it (design 6.2 item 3).
190
+ - No archive/packaging enumeration (`tar`, `git bundle`, `gh release
191
+ upload`); the natural MVP-6.
192
+ - No git-history rewriting. Detection is not remediation.
193
+ - Channels with no hook remain uncovered, by construction. See
194
+ `channels.md`.
@@ -0,0 +1,8 @@
1
+ """Shared sys.path bootstrap for the delete-guard CLI scripts."""
2
+ import os
3
+ import sys
4
+
5
+ _HERE = os.path.dirname(os.path.abspath(__file__))
6
+ _REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(_HERE)))
7
+ if _REPO_ROOT not in sys.path:
8
+ sys.path.insert(0, _REPO_ROOT)
@@ -0,0 +1,250 @@
1
+ #!/usr/bin/env python3
2
+ """check_span - scan an outbound payload before it leaves the machine.
3
+
4
+ check_span.py --channel <name> [--workspace DIR] [--mode M] [--json] < text
5
+
6
+ This is deliberately a *separate* entry point from `check.py`: that one
7
+ classifies a shell command line (its `--` REMAINDER convention, its dialect
8
+ resolution, its compensation phase). A text payload has a different input, a
9
+ smaller decision set (no RELOCATE/SNAPSHOT - the guard cannot rewrite what
10
+ it did not write) and no compensation phase at all.
11
+
12
+ It is a pure function of its input: it never mutates the payload and never
13
+ writes a file, so "apply the plan" stays the caller's decision. The output
14
+ carries offsets, rule ids and placeholders - **never the matched bytes** -
15
+ which is why `--json` output is safe to paste into a CI log.
16
+
17
+ Decisions (design 1.3): ALLOW | SANITIZE | ASK | BLOCK.
18
+
19
+ Exit codes: 0 ALLOW/SANITIZE (advisory ok) | 2 BLOCK | 3 ASK | 1 ERROR.
20
+
21
+ `--json` payload:
22
+ {"decision": "SANITIZE", "code": "SANITIZE_SECRET_REDACT",
23
+ "spans": [{"start": 104, "end": 151, "rule_id": "secret/openai-key",
24
+ "confidence": "deterministic"}],
25
+ "redaction_plan": [{"start": 104, "end": 151,
26
+ "placeholder": "sk-<REDACTED>"}]}
27
+ """
28
+ from __future__ import annotations
29
+
30
+ import argparse
31
+ import json
32
+ import os
33
+ import sys
34
+ import time
35
+
36
+ import _bootstrap # noqa: F401
37
+
38
+ from core import redaction
39
+ from core.redaction import (
40
+ CHANNELS, UNREACHABLE_CHANNELS, get_channel, scan_text,
41
+ )
42
+ 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()
102
+
103
+
104
+ def build_redaction_plan(spans, decisions, channel) -> list:
105
+ """Offsets + placeholder only; the caller applies it (design 4.3)."""
106
+ from sanitize import plan_for_span # same directory
107
+ plan = []
108
+ for span, verdict in zip(spans, decisions):
109
+ if verdict.decision != policy.DECISION_SANITIZE:
110
+ continue
111
+ plan.append(plan_for_span(span, channel))
112
+ return plan
113
+
114
+
115
+ def main() -> int:
116
+ ap = argparse.ArgumentParser(description=__doc__)
117
+ ap.add_argument("--channel", default=os.environ.get(
118
+ "AGENT_GUARD_EXFIL_CHANNEL", "file-write"),
119
+ help="egress channel: " + ", ".join(sorted(CHANNELS)))
120
+ ap.add_argument("--workspace", default=None,
121
+ help="workspace root (default: AGENT_GUARD_WORKSPACE "
122
+ "or discovery from cwd)")
123
+ ap.add_argument("--mode", default=None, choices=["NORMAL", "RESTRICTED"])
124
+ ap.add_argument("--json", action="store_true", dest="as_json")
125
+ ap.add_argument("--max-bytes", type=int, default=None,
126
+ help="override the scan size cap")
127
+ ap.add_argument("--path", default=None,
128
+ help="path the payload will be written to; enables the "
129
+ "repo-local exemption file for that path")
130
+ args = ap.parse_args()
131
+
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
145
+
146
+ channel_name = (args.channel or "").strip().lower()
147
+ channel = get_channel(channel_name)
148
+
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
+ out = {
157
+ "channel": channel_name,
158
+ "channel_known": channel is not None,
159
+ "channel_rewritable": bool(channel and channel.rewritable),
160
+ "channel_persistence": channel.persistence if channel else None,
161
+ "workspace": workspace,
162
+ "mode": mode,
163
+ "size_bytes": len(text.encode("utf-8", errors="replace")),
164
+ }
165
+
166
+ if channel is None:
167
+ # An unknown channel name is a configuration defect, and a channel
168
+ # the guard cannot name is one it cannot certify. Fail closed.
169
+ if channel_name in UNREACHABLE_CHANNELS:
170
+ out["reason"] = ("channel is unreachable by design; exfil-guard "
171
+ "makes no claim to cover it")
172
+ else:
173
+ out["reason"] = ("unknown egress channel; expected one of: "
174
+ + ", ".join(sorted(CHANNELS)))
175
+ return _emit(out, policy.DECISION_BLOCK,
176
+ policy.CODE_BLOCK_OUTPUT_UNSCANNABLE, [], [], args, 2)
177
+
178
+ scan = scan_text(text, channel=channel_name, workspace=workspace,
179
+ max_bytes=args.max_bytes, path=args.path)
180
+ out["scanned"] = scan.scanned
181
+ out["exempted"] = scan.exempted
182
+ if args.path:
183
+ out["path"] = args.path
184
+ if not scan.scanned:
185
+ out["reason"] = scan.error
186
+ return _emit(out, policy.DECISION_BLOCK,
187
+ policy.CODE_BLOCK_OUTPUT_UNSCANNABLE, [], [], args, 2)
188
+
189
+ ctx = policy.PolicyContext(workspace=workspace, trash_root="",
190
+ base_dir=workspace, mode=mode)
191
+ verdicts = policy.decide_spans(scan.spans, ctx=ctx, channel=channel)
192
+
193
+ # De-duplicate the per-span narratives: one payload gets one verdict,
194
+ # and the aggregate must not depend on how many spans matched.
195
+ top = (policy.worst(verdicts) if verdicts else
196
+ policy.Verdict(policy.DECISION_ALLOW,
197
+ policy.CODE_ALLOW_NOOP,
198
+ explanation="No secret or host path matched."))
199
+
200
+ spans_out = []
201
+ for span, verdict in zip(scan.spans, verdicts):
202
+ record = span.safe()
203
+ record["decision"] = verdict.decision
204
+ record["code"] = verdict.code
205
+ spans_out.append(record)
206
+
207
+ plan = build_redaction_plan(scan.spans, verdicts, channel)
208
+ exit_code = {policy.DECISION_BLOCK: 2, policy.DECISION_ASK: 3}.get(
209
+ top.decision, 0)
210
+ return _emit(out, top.decision, top.code, spans_out, plan, args, exit_code,
211
+ top)
212
+
213
+
214
+ def _emit(out, decision, code, spans, plan, args, exit_code,
215
+ top=None) -> int:
216
+ out["decision"] = decision
217
+ out["code"] = code
218
+ out["explanation"] = (top.explanation if top is not None
219
+ else policy.EXPLANATIONS.get(code, code))
220
+ out["reasons"] = list(top.reasons) if top is not None else []
221
+ out["spans"] = spans
222
+ out["redaction_plan"] = plan
223
+ out["exit"] = exit_code
224
+ if args.as_json:
225
+ print(json.dumps(out, ensure_ascii=False, indent=2))
226
+ else:
227
+ print(f"{decision} [{code}] {len(spans)} span(s) on "
228
+ f"channel {out.get('channel')}")
229
+ if out.get("explanation"):
230
+ print(f" {out['explanation']}")
231
+ for span in spans:
232
+ print(f" - {span['rule_id']} [{span['start']},{span['end']}] "
233
+ f"{span['decision']}")
234
+ return exit_code
235
+
236
+
237
+ def _fail(message, as_json) -> int:
238
+ if as_json:
239
+ print(json.dumps({"error": message, "exit": 1}, ensure_ascii=False))
240
+ else:
241
+ print(f"exfil-guard error: {message}", file=sys.stderr)
242
+ return 1
243
+
244
+
245
+ if __name__ == "__main__":
246
+ try:
247
+ sys.exit(main())
248
+ except Exception as exc: # fail closed, never a traceback with payload
249
+ print(f"agent-guard internal error: {type(exc).__name__}", file=sys.stderr)
250
+ sys.exit(1)
@@ -0,0 +1,155 @@
1
+ #!/usr/bin/env python3
2
+ """sanitize - apply a redaction plan to a payload (design 4.3).
3
+
4
+ sanitize.py --channel <name> [--workspace DIR] [--plan FILE] < text
5
+
6
+ The guard never rewrites the payload itself: `check_span.py` returns a plan
7
+ (offsets + placeholders, no bytes) and the *payload owner* applies it. This
8
+ script is that applicator, and it exists so the discipline is testable and
9
+ so a shell pipeline can use it without writing code:
10
+
11
+ check_span.py --channel llm-request --json < prompt.json > verdict.json
12
+ sanitize.py --channel llm-request < prompt.json # sanitized text
13
+
14
+ Two properties are load-bearing:
15
+
16
+ * **Format preservation.** A redacted secret keeps the shape a reader needs
17
+ to recognise it (`sk-proj-Ab…` -> `sk-proj-<REDACTED>`), never the bytes.
18
+ For paths the placeholder is `<PATH>`.
19
+ * **Leak freedom.** The plan carries offsets and placeholders only, and the
20
+ output is built by *replacing* the matched ranges - so no code path here
21
+ can echo a matched secret into stdout, the plan, or an error message.
22
+
23
+ Exit codes: 0 applied (or nothing to do) | 1 error.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import argparse
28
+ import json
29
+ import os
30
+ import re
31
+ import sys
32
+
33
+ import _bootstrap # noqa: F401
34
+
35
+ from core import policy, redaction
36
+ from core.redaction import get_channel, scan_text
37
+
38
+ REDACTED = "<REDACTED>"
39
+ PATH_PLACEHOLDER = "<PATH>"
40
+ # Windows drive/UNC prefixes are layout, not identity, and they are what
41
+ # makes a rewritten path still readable ("C:\\Users\\..." -> "C:\\<PATH>").
42
+ _DRIVE_PREFIX_RE = re.compile(r"^[A-Za-z]:[\\/]")
43
+
44
+
45
+ def placeholder_for(span) -> str:
46
+ """The replacement text for one span; derived from shape, never content."""
47
+ if span.family != redaction.FAMILY_SECRET:
48
+ return PATH_PLACEHOLDER
49
+ if span.rule_id == redaction.RULE_PRIVATE_KEY_BLOCK:
50
+ return REDACTED
51
+ # Keep the vendor prefix: it is public information (it says *which*
52
+ # credential kind leaked) and it is what makes the output reviewable.
53
+ match = re.match(r"^(sk-|rk_|ghp_|gho_|ghu_|ghs_|ghr_|github_pat_|"
54
+ r"glpat-|xox[baprs]-|AKIA|ASIA|AGPA|AIDA|AROA|ANPA|"
55
+ r"sk_live_|rk_live_)", span.raw)
56
+ if match:
57
+ return match.group(1) + REDACTED
58
+ return REDACTED
59
+
60
+
61
+ def plan_for_span(span, channel=None) -> dict:
62
+ """One plan entry: offsets + placeholder. Never the matched bytes."""
63
+ return {
64
+ "start": span.start,
65
+ "end": span.end,
66
+ "rule_id": span.rule_id,
67
+ "family": span.family,
68
+ "confidence": span.confidence,
69
+ "placeholder": placeholder_for(span),
70
+ }
71
+
72
+
73
+ def apply_plan(text: str, plan, verify: bool = True) -> str:
74
+ """Replace every planned range, back to front so offsets stay valid.
75
+
76
+ Blocks whose span overlaps a gap (stale plan) are skipped rather than
77
+ applied blindly: a wrong splice would silently corrupt the payload,
78
+ which is the false-SANITIZE failure mode the analysis warns about.
79
+ """
80
+ pieces = []
81
+ for entry in sorted(plan, key=lambda e: e["start"], reverse=True):
82
+ start, end = entry["start"], entry["end"]
83
+ if start < 0 or end > len(text) or start >= end:
84
+ raise ValueError("redaction plan has an out-of-range span")
85
+ pieces.append((start, end, entry["placeholder"]))
86
+ result = text
87
+ for start, end, placeholder in pieces:
88
+ result = result[:start] + placeholder + result[end:]
89
+ if verify and REDACTED in result and result.count(REDACTED) > len(pieces):
90
+ # Another marker was already present: harmless, but worth knowing.
91
+ pass
92
+ return result
93
+
94
+
95
+ def sanitize_text(text: str, channel_name: str, workspace=None,
96
+ plan=None) -> dict:
97
+ """Scan + decide + apply, in one call (the library form)."""
98
+ channel = get_channel(channel_name)
99
+ if channel is None:
100
+ raise ValueError("unknown egress channel: " + str(channel_name))
101
+ scan = scan_text(text, channel=channel_name, workspace=workspace)
102
+ if not scan.scanned:
103
+ raise RuntimeError(scan.error)
104
+ ctx = policy.PolicyContext(workspace=workspace or "", trash_root="",
105
+ base_dir=workspace or "",
106
+ mode=policy.MODE_NORMAL)
107
+ verdicts = policy.decide_spans(scan.spans, ctx=ctx, channel=channel)
108
+ derived = [plan_for_span(span, channel)
109
+ for span, verdict in zip(scan.spans, verdicts)
110
+ if verdict.decision == policy.DECISION_SANITIZE]
111
+ applied = plan if plan is not None else derived
112
+ return {
113
+ "text": apply_plan(text, applied),
114
+ "plan": applied,
115
+ "decision": policy.worst(verdicts).decision if verdicts else
116
+ policy.DECISION_ALLOW,
117
+ }
118
+
119
+
120
+ def main() -> int:
121
+ ap = argparse.ArgumentParser(description=__doc__)
122
+ ap.add_argument("--channel", default=os.environ.get(
123
+ "AGENT_GUARD_EXFIL_CHANNEL", "file-write"))
124
+ ap.add_argument("--workspace", default=None)
125
+ ap.add_argument("--plan", default=None,
126
+ help="read an explicit plan (JSON) instead of deriving "
127
+ "one; useful for replaying a check_span verdict")
128
+ ap.add_argument("--dry-run", action="store_true", dest="dry_run",
129
+ help="print the plan, not the sanitized text")
130
+ args = ap.parse_args()
131
+
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
+ try:
139
+ result = sanitize_text(text, args.channel, workspace, plan)
140
+ except (ValueError, RuntimeError) as exc:
141
+ print(f"sanitize: {exc}", file=sys.stderr)
142
+ return 1
143
+ if args.dry_run:
144
+ print(json.dumps(result["plan"], ensure_ascii=False, indent=2))
145
+ return 0
146
+ sys.stdout.write(result["text"])
147
+ return 0
148
+
149
+
150
+ if __name__ == "__main__":
151
+ try:
152
+ sys.exit(main())
153
+ except Exception as exc:
154
+ print(f"agent-guard internal error: {type(exc).__name__}", file=sys.stderr)
155
+ sys.exit(1)
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env python3
2
+ """Show a value-free view of an explicitly selected JSON or dotenv config."""
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import json
7
+ import os
8
+ import sys
9
+
10
+ import _bootstrap # noqa: F401
11
+
12
+ from core import classifier, safe_view
13
+
14
+
15
+ class SafeArgumentParser(argparse.ArgumentParser):
16
+ def error(self, _message):
17
+ raise safe_view.SafeViewError("INVALID_ARGUMENT", "invalid arguments")
18
+
19
+
20
+ def main() -> int:
21
+ parser = SafeArgumentParser(description=__doc__)
22
+ parser.add_argument("path", help="workspace-relative config path")
23
+ parser.add_argument("--workspace", default=None,
24
+ help="workspace root (default: discovered from cwd)")
25
+ parser.add_argument("--format", dest="format_name", default="auto",
26
+ choices=("auto", "json", "dotenv"))
27
+ try:
28
+ args = parser.parse_args()
29
+ workspace = args.workspace or classifier.discover_workspace(os.getcwd())
30
+ result = safe_view.read_view(workspace, args.path, args.format_name)
31
+ except safe_view.SafeViewError as exc:
32
+ print(json.dumps({"status": "error", "code": exc.code,
33
+ "message": exc.message}), file=sys.stderr)
34
+ return 2
35
+ except Exception:
36
+ print(json.dumps({"status": "error", "code": "INTERNAL_ERROR",
37
+ "message": "safe view failed"}), file=sys.stderr)
38
+ return 1
39
+ print(json.dumps(result, ensure_ascii=False))
40
+ return 0
41
+
42
+
43
+ if __name__ == "__main__":
44
+ sys.exit(main())