@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.
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +558 -0
- package/README.zh-CN.md +488 -0
- package/adapters/INTEGRATION.md +94 -0
- package/adapters/claude/README.md +141 -0
- package/adapters/claude/compatibility.json +17 -0
- package/adapters/claude/harness/README.md +59 -0
- package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
- package/adapters/claude/harness/run_scenario.sh +79 -0
- package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
- package/adapters/claude/hook_bridge.sh +33 -0
- package/adapters/claude/pre_tool_use.py +264 -0
- package/adapters/claude/settings.example.json +16 -0
- package/adapters/codex/harness/README.md +53 -0
- package/adapters/codex/harness/acceptance.py +226 -0
- package/adapters/dsh/README.md +62 -0
- package/adapters/dsh/cordis.patch.yml +30 -0
- package/adapters/dsh/lib/index.js +500 -0
- package/adapters/kimi-code/README.md +169 -0
- package/adapters/kimi-code/compatibility.json +17 -0
- package/adapters/kimi-code/config.example.toml +26 -0
- package/adapters/kimi-code/hook_bridge.sh +32 -0
- package/adapters/kimi-code/pre_tool_use.py +72 -0
- package/core/__init__.py +47 -0
- package/core/audit.py +86 -0
- package/core/classifier.py +1175 -0
- package/core/dialects.py +898 -0
- package/core/policy.py +817 -0
- package/core/recovery.py +700 -0
- package/core/redaction.py +1096 -0
- package/core/safe_view.py +212 -0
- package/docs/architecture.md +223 -0
- package/docs/compatibility.md +142 -0
- package/docs/development-note-unguarded-deletion.md +187 -0
- package/docs/friction.md +266 -0
- package/docs/harness-capabilities.md +72 -0
- package/docs/host-drift.md +142 -0
- package/docs/publishing-from-ephemeral-environments.md +104 -0
- package/docs/release-notes-0.2.0-rc1.md +46 -0
- package/docs/release-notes-0.2.0.md +72 -0
- package/docs/release-notes-0.2.1.md +78 -0
- package/docs/release-notes-0.2.2.md +120 -0
- package/docs/secret-guard-analysis.md +416 -0
- package/docs/secret-guard-architecture.md +93 -0
- package/docs/secret-guard-design.md +649 -0
- package/docs/test-report-claude-code-harness.md +462 -0
- package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
- package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
- package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
- package/docs/test-report-dsh-v0.1.1.md +126 -0
- package/docs/test-report-kimi-code-block.md +198 -0
- package/docs/test-report-zcode-glm-flash.md +241 -0
- package/docs/threat-model.md +44 -0
- package/doctor.py +756 -0
- package/live_sentinel.py +339 -0
- package/package.json +69 -0
- package/skills/delete-guard/SKILL.md +109 -0
- package/skills/delete-guard/agents/openai.yaml +4 -0
- package/skills/delete-guard/references/policy.md +161 -0
- package/skills/delete-guard/scripts/_bootstrap.py +8 -0
- package/skills/delete-guard/scripts/check.py +370 -0
- package/skills/delete-guard/scripts/gc.py +103 -0
- package/skills/delete-guard/scripts/restore.py +98 -0
- package/skills/delete-guard/scripts/safe_delete.py +256 -0
- package/skills/delete-guard/scripts/status.py +130 -0
- package/skills/exfil-guard/SKILL.md +143 -0
- package/skills/exfil-guard/agents/openai.yaml +4 -0
- package/skills/exfil-guard/references/channels.md +58 -0
- package/skills/exfil-guard/references/rules.md +194 -0
- package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
- package/skills/exfil-guard/scripts/check_span.py +250 -0
- package/skills/exfil-guard/scripts/sanitize.py +155 -0
- package/skills/exfil-guard/scripts/view.py +44 -0
- package/skills/recovery-audit/SKILL.md +283 -0
- package/skills/recovery-audit/agents/openai.yaml +4 -0
- 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())
|