@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4-hotfix.1
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 +132 -84
- package/README.zh-CN.md +109 -75
- package/adapters/INTEGRATION.md +4 -4
- package/adapters/claude/README.md +3 -3
- package/adapters/claude/harness/README.md +1 -1
- package/adapters/codex/harness/README.md +2 -2
- package/adapters/dsh/README.md +24 -15
- package/adapters/dsh/harness/README.md +75 -19
- 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 +194 -32
- package/adapters/dsh/harness/native_session.py +41 -20
- package/adapters/dsh/harness/profiles.py +74 -22
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +15 -14
- package/adapters/kimi-code/harness/README.md +3 -3
- package/adapters/kimi-code/harness/guard_lab.py +1 -1
- package/core/__init__.py +1 -1
- package/core/classifier.py +66 -17
- package/core/lab.py +24 -1
- package/core/policy.py +28 -13
- package/core/recovery.py +256 -23
- package/core/redaction.py +157 -55
- package/core/trash_index.py +193 -0
- package/docs/README.md +104 -0
- package/docs/{architecture.md → design/architecture.md} +31 -6
- package/docs/{compatibility.md → design/compatibility.md} +80 -4
- package/docs/{threat-model.md → design/threat-model.md} +4 -4
- package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
- package/docs/guides/trash-index.md +106 -0
- package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +8 -9
- package/docs/{friction.md → history/friction.md} +129 -4
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +23 -22
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +6 -4
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +19 -15
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +18 -11
- package/docs/lab/tasks/guard-lab-read-trial-task.md +7 -0
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +5 -5
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +7 -7
- package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
- package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +9 -10
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +4 -2
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/releases/release-notes-0.2.3.md +84 -0
- package/docs/releases/release-notes-0.2.4-hotfix.1.md +75 -0
- package/docs/releases/release-notes-0.2.4.md +89 -0
- package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
- package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
- package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
- package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
- package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
- package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
- package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
- package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
- package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
- package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
- package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
- package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
- package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +40 -3
- package/skills/delete-guard/references/policy.md +29 -9
- package/skills/delete-guard/scripts/check.py +19 -0
- package/skills/delete-guard/scripts/restore.py +18 -6
- package/skills/delete-guard/scripts/status.py +52 -0
- package/skills/exfil-guard/SKILL.md +37 -7
- package/skills/exfil-guard/references/channels.md +1 -1
- 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
- package/docs/release-notes-0.2.3.md +0 -45
- /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
- /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
- /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
- /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
- /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
- /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
- /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
- /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
|
@@ -25,8 +25,7 @@ enforces and how to work with it productively. The four pillars:
|
|
|
25
25
|
|
|
26
26
|
## The one rule
|
|
27
27
|
|
|
28
|
-
**Prefer `safe_delete` over `rm
|
|
29
|
-
supported path.**
|
|
28
|
+
**Prefer `safe_delete` over `rm`.** It applies the guard's recovery policy.
|
|
30
29
|
|
|
31
30
|
```bash
|
|
32
31
|
# delete files/dirs/globs - they are quarantined, not destroyed:
|
|
@@ -68,6 +67,14 @@ A block is not an error to route around. Retrying the same operation in a
|
|
|
68
67
|
disguised form (`/bin/rm`, `python -c`, a script) is a violation of the
|
|
69
68
|
authorization pillar and is recorded in the audit log.
|
|
70
69
|
|
|
70
|
+
`git reset --hard [commit]` first checks whether its target tree would
|
|
71
|
+
overwrite untracked or ignored content. A tracked-only stash cannot recover
|
|
72
|
+
those paths, so a collision returns `BLOCK_GIT_RESET_COLLISION` without
|
|
73
|
+
moving them or creating a snapshot. Preserve the conflicting content
|
|
74
|
+
separately before retrying. Use a standalone reset without shell wrappers;
|
|
75
|
+
compound commands, submodule effects, unknown options, and stash-relative
|
|
76
|
+
targets are refused as undeterminable. Unrelated untracked files are allowed.
|
|
77
|
+
|
|
71
78
|
## Compensation preflight and verification
|
|
72
79
|
|
|
73
80
|
Before sandboxed use, ensure `.agent-trash/` is already ignored by a tracked
|
|
@@ -82,12 +89,32 @@ stop immediately. Inspect both the origin and `.agent-trash/`; never infer
|
|
|
82
89
|
that an error means no filesystem change occurred. A durable
|
|
83
90
|
`relocate-intent` can keep an interrupted relocation discoverable.
|
|
84
91
|
|
|
92
|
+
## Quarantine location queries
|
|
93
|
+
|
|
94
|
+
When the user asks where quarantines are or how many exist, use the shared
|
|
95
|
+
read-only query with a current-directory or user-selected scope:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --json
|
|
99
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --root <projects> --max-depth 3 --json
|
|
100
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --trash <custom-store> --json
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Report the scope, candidate count, metadata-identified count and read/budget
|
|
104
|
+
errors. Do not claim that unconfirmed/unreadable locations are absent or that
|
|
105
|
+
the result covers the whole host. Explain that these are bucket locations,
|
|
106
|
+
not file/transaction totals. If you supplement the result yourself, identify
|
|
107
|
+
that source separately. Existing native status tools may show the current
|
|
108
|
+
project only; use the CLI for this indexed query. Location metadata and cached
|
|
109
|
+
JSON are not authorization to purge, and recovery file contents must not be
|
|
110
|
+
read just to answer a location/count question.
|
|
111
|
+
|
|
85
112
|
## RESTRICTED mode
|
|
86
113
|
|
|
87
114
|
After a human veto, the session runs with narrowed powers: explicit
|
|
88
115
|
single-file deletes inside the workspace still work (quarantined as usual);
|
|
89
116
|
recursive deletes, globs, and destructive git operations are refused. Only a
|
|
90
|
-
human can restore NORMAL. If a task
|
|
117
|
+
human can restore NORMAL. If a task requires more, say so plainly
|
|
91
118
|
and ask.
|
|
92
119
|
|
|
93
120
|
## Regenerable artifacts
|
|
@@ -105,5 +132,15 @@ overwrite anything that now exists at the origin unless a human passes
|
|
|
105
132
|
`--force`. Git snapshots are stored as stashes named `agent-guard:<txid>`;
|
|
106
133
|
restore applies them and never drops them.
|
|
107
134
|
|
|
135
|
+
With human `--force`, an existing occupant is first preserved by the normal
|
|
136
|
+
relocation journal in a separate transaction. The result's optional
|
|
137
|
+
`backup_txids` lists preservation attempts; an ID alone does not prove the
|
|
138
|
+
copy completed. Inspect those IDs with `restore.py list --json` and the
|
|
139
|
+
filesystem after any error. A failed old-version move must not be followed
|
|
140
|
+
by deleting the preserved occupant. Restoring a completed backup transaction
|
|
141
|
+
uses the same `restore.py <txid>` command; if the origin is occupied, the
|
|
142
|
+
usual conflict/force rules apply again. Preserved versions consume quarantine
|
|
143
|
+
space and remain subject to its existing explicit GC policy.
|
|
144
|
+
|
|
108
145
|
See `references/policy.md` for the complete rule table, verdict codes, and
|
|
109
146
|
manifest format.
|
|
@@ -51,11 +51,11 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
51
51
|
| 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
|
|
52
52
|
| 2 | unresolvable targets: shell vars, command substitution, unbalanced quotes, `bash -c` with destructive smell, `find -delete`, `find -exec rm`, stdin-fed (`xargs`) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse - allowing it would forfeit the core guarantee |
|
|
53
53
|
| 2a | SHAPE F1: destructive op preceded by `cd` in the same command line, target in-workspace and resolvable | `ASK` (`COMPOUND_CWD_DELETE`) | single-execution authorization; splitting the command avoids the prompt. A shape rule describes *compensation* difficulty, never effect scope: if the target set also trips rule 2, 4, 5 or 6, that BLOCK wins (`tests/test_incident_regression.py`) |
|
|
54
|
-
| 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization;
|
|
54
|
+
| 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; force-push is refused separately. Hard reset in a compound line is effect-uncertain and BLOCKED before shape rules |
|
|
55
55
|
| 2c | target *is* a filesystem root (`/`, `/home`, `/usr`, `/etc`, `/var`, `/tmp`, `/opt`, `/boot`, `$HOME`, ...) | `BLOCK_PROTECTED_ANCESTOR` | refuse. Matched exactly, so paths *under* these roots keep the ordinary codes; enforced by identity rather than workspace geometry, so it holds even when the workspace is `/` |
|
|
56
|
-
|
|
|
56
|
+
| 5 | workspace root, `.git` metadata, quarantine root/control paths, or an in-workspace parent containing configured storage | `BLOCK_PROTECTED_PATH` | refuse before the housekeeping exemption; root manifest/audit/state, state temp and sessions are control paths |
|
|
57
|
+
| 3 | explicit ordinary unprotected payload inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | opaque globs are refused; safe_delete may enumerate first, and transaction purges use gc.py --execute with an explicit selection |
|
|
57
58
|
| 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
|
|
58
|
-
| 5 | target is workspace root or `.git` (any depth) | `BLOCK_PROTECTED_PATH` | refuse |
|
|
59
59
|
| 6 | any glob target | `BLOCK_WILDCARD` | refuse; use safe_delete which enumerates |
|
|
60
60
|
| 7 | RESTRICTED mode, git/remote destructive op | `BLOCK_RESTRICTED_MODE` | refuse |
|
|
61
61
|
| 8 | RESTRICTED mode, fs delete | narrow files only -> `RELOCATE_NARROW`, else `BLOCK_RESTRICTED_MODE` | refuse or quarantine |
|
|
@@ -64,13 +64,22 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
64
64
|
| 11 | supported `git clean -f...` | `RELOCATE_VIA_CLEAN_ENUMERATE` | enumerate via `clean -n`, decode every Git-quoted path, relocate every match, proceed only on full coverage |
|
|
65
65
|
| 11a | `git clean -ff`, interactive `-i`, or exclude `-e` | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; nested-repository and interactive/exclusion semantics are not safely mirrored |
|
|
66
66
|
| 11b | supported `git clean -f...` whose target set cannot be enumerated (not a repository, `git` cannot run) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; the targets exist but their set is unknowable, so nothing was attempted and nothing may be reported as a failed compensation |
|
|
67
|
-
| 12 | `git reset --hard
|
|
67
|
+
| 12 | supported `git reset --hard [commit]` without untracked/ignored collisions, `git restore <path>`, `git checkout -- <path>` | `SNAPSHOT_GIT_STASH` | hard reset first checks its target tree; `git stash create`+`store` then protects tracked modifications; any create/store failure blocks |
|
|
68
|
+
| 12a | hard reset target overlaps untracked/ignored content or quarantine storage | `BLOCK_GIT_RESET_COLLISION` | refuse before compensation; preserve conflicting paths separately before retrying |
|
|
69
|
+
| 12b | hard reset target cannot be resolved/enumerated, has unsupported options or submodule effects, is stash-relative, or uses shell wrappers/compound commands | `BLOCK_UNDETERMINABLE_EFFECT` | refuse before compensation; use a standalone reset with an explicit stable commit |
|
|
68
70
|
| 13 | all targets git-ignored AND match artifact patterns | `ALLOW_REGENERABLE` | direct delete |
|
|
69
71
|
| 14 | rooted recursive delete | `RELOCATE_TREE` | quarantine whole tree, proceed |
|
|
70
72
|
| 15 | named files/dirs | `RELOCATE_PATHS` | quarantine, proceed |
|
|
71
73
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
+
Filesystem-root and workspace/Git/quarantine protection win before ordinary
|
|
75
|
+
housekeeping. Targets outside the workspace retain their boundary refusal,
|
|
76
|
+
except ordinary unprotected payload inside the explicitly configured quarantine.
|
|
77
|
+
RESTRICTED narrows before NORMAL relaxes.
|
|
78
|
+
|
|
79
|
+
The 0.2.4-hotfix.1 maintenance hotfix backports the RC control-path repair onto 0.2.4.
|
|
80
|
+
The original 0.2.4 artifact does not include this protection. This hotfix uses
|
|
81
|
+
an explicit version or npm hotfix selection.
|
|
82
|
+
The existing 0.2.5 RC line retains its accumulated changes.
|
|
74
83
|
|
|
75
84
|
## Verdict actions
|
|
76
85
|
|
|
@@ -154,8 +163,19 @@ model tool.
|
|
|
154
163
|
|
|
155
164
|
- Command-level interception covers the recognized vocabulary; arbitrary
|
|
156
165
|
scripts that delete internally are invisible to `check.py` (see
|
|
157
|
-
`docs/threat-model.md`).
|
|
158
|
-
- `git stash create` captures tracked modifications
|
|
159
|
-
|
|
166
|
+
`docs/design/threat-model.md`).
|
|
167
|
+
- `git stash create` captures tracked modifications only. `reset --hard`
|
|
168
|
+
can delete untracked and ignored content that obstructs its target tree.
|
|
169
|
+
`check.py` checks file/directory/ancestor collisions and refuses them;
|
|
170
|
+
this version does not automatically archive those paths. It also refuses
|
|
171
|
+
target-tree writes into quarantine. Ordinary unrelated untracked files
|
|
172
|
+
remain allowed. Only `--hard`, optional `-q`/`--quiet`, and at most one
|
|
173
|
+
commit are supported; submodules and stash-relative targets are refused.
|
|
174
|
+
- Hard reset must be standalone without shell wrappers: other segments can
|
|
175
|
+
change its revision or create a collision after preflight; wrappers can
|
|
176
|
+
change its Git environment. The preflight and host execution are separate;
|
|
177
|
+
concurrent changes are not atomically excluded.
|
|
178
|
+
Direct callers of `snapshot_git` receive a tracked-only snapshot and must
|
|
179
|
+
run the hard-reset preflight themselves before authorizing that operation.
|
|
160
180
|
- Windows cmd/PowerShell, databases, cloud resources: future skills
|
|
161
181
|
(`git-guard`, `database-guard`, `cloud-guard`) on the same core.
|
|
@@ -105,6 +105,25 @@ def main() -> int:
|
|
|
105
105
|
specs, parse_error = [], None
|
|
106
106
|
verdicts = [policy.decide_dialect_failure(resolution)]
|
|
107
107
|
|
|
108
|
+
# Preflight every reset before ANY compensation in the line. Advisory
|
|
109
|
+
# and enforced checks agree, and a later unsafe reset cannot leave an
|
|
110
|
+
# earlier filesystem relocation half-applied. Stash create only saves
|
|
111
|
+
# tracked modifications, so it cannot authorize an untracked collision.
|
|
112
|
+
if not policy.worst(verdicts).blocked:
|
|
113
|
+
for index, (spec, verdict) in enumerate(zip(specs, verdicts)):
|
|
114
|
+
if spec.kind != classifier.KIND_GIT_RESET_HARD or \
|
|
115
|
+
verdict.decision != policy.DECISION_SNAPSHOT:
|
|
116
|
+
continue
|
|
117
|
+
collisions, error = engine.preflight_git_reset_hard(
|
|
118
|
+
cwd=base, target=spec.targets[0] if spec.targets else "HEAD")
|
|
119
|
+
if error or collisions:
|
|
120
|
+
verdicts[index] = policy.Verdict(
|
|
121
|
+
policy.DECISION_BLOCK,
|
|
122
|
+
policy.CODE_BLOCK_UNDETERMINABLE_EFFECT if error else
|
|
123
|
+
policy.CODE_BLOCK_GIT_RESET_COLLISION,
|
|
124
|
+
[error or "untracked/ignored or quarantine collision"],
|
|
125
|
+
)
|
|
126
|
+
|
|
108
127
|
top = policy.worst(verdicts)
|
|
109
128
|
latency_ms = round((time.monotonic() - started) * 1000, 1)
|
|
110
129
|
check_id = audit.new_txid()
|
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
restore.py TXID [--force] [--json]
|
|
6
6
|
|
|
7
7
|
Restore is non-destructive by default: it refuses to overwrite anything now
|
|
8
|
-
occupying an origin path. --force
|
|
8
|
+
occupying an origin path. --force preserves that occupant in a separate
|
|
9
|
+
transaction before restoring. Inspect backup_txids after success or failure.
|
|
9
10
|
"""
|
|
10
11
|
from __future__ import annotations
|
|
11
12
|
|
|
@@ -69,20 +70,31 @@ def main() -> int:
|
|
|
69
70
|
|
|
70
71
|
report = engine.restore(args.txid, force=args.force)
|
|
71
72
|
workspace = engine.workspace
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
73
|
+
event = {"event": "restore", "txid": args.txid, "force": args.force,
|
|
74
|
+
"ok": report.get("ok"), "restored": report.get("restored"),
|
|
75
|
+
"conflicts": report.get("conflicts"),
|
|
76
|
+
"errors": report.get("errors")}
|
|
77
|
+
if report.get("backup_txids"):
|
|
78
|
+
event["backup_txids"] = report["backup_txids"]
|
|
79
|
+
try:
|
|
80
|
+
audit.append(event, os.path.join(engine.trash_root, AUDIT_NAME))
|
|
81
|
+
except OSError:
|
|
82
|
+
report["ok"] = False
|
|
83
|
+
report.setdefault("errors", []).append(
|
|
84
|
+
"restore audit could not be stored; inspect filesystem state")
|
|
77
85
|
if args.as_json:
|
|
78
86
|
print(json.dumps(report, ensure_ascii=False, indent=2))
|
|
79
87
|
else:
|
|
88
|
+
for txid in report.get("backup_txids", []):
|
|
89
|
+
print(f"current-version preservation transaction: {txid} (inspect state)")
|
|
80
90
|
for path in report.get("restored", []):
|
|
81
91
|
print(f"restored: {path}")
|
|
82
92
|
for path in report.get("conflicts", []):
|
|
83
93
|
print(f"conflict (exists; use --force): {path}")
|
|
84
94
|
for err in report.get("errors", []):
|
|
85
95
|
print(f"error: {err}", file=sys.stderr)
|
|
96
|
+
if report.get("error"):
|
|
97
|
+
print(f"error: {report['error']}", file=sys.stderr)
|
|
86
98
|
if report.get("errors"):
|
|
87
99
|
return 1
|
|
88
100
|
if report.get("conflicts"):
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
"""status - inspect guard state, quarantine usage, recent decisions.
|
|
3
3
|
|
|
4
4
|
status.py [--json] [--tail N]
|
|
5
|
+
status.py --trash-index [--root PATH ...] [--trash PATH ...] [--json]
|
|
5
6
|
"""
|
|
6
7
|
from __future__ import annotations
|
|
7
8
|
|
|
@@ -21,9 +22,60 @@ def main() -> int:
|
|
|
21
22
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
22
23
|
ap.add_argument("--json", action="store_true", dest="as_json")
|
|
23
24
|
ap.add_argument("--tail", type=int, default=10)
|
|
25
|
+
ap.add_argument("--trash-index", action="store_true",
|
|
26
|
+
help="read-only quarantine locations for agents and future UI")
|
|
27
|
+
ap.add_argument("--root", action="append", default=[],
|
|
28
|
+
help="search root for --trash-index (repeatable)")
|
|
29
|
+
ap.add_argument("--trash", action="append", default=[],
|
|
30
|
+
help="declared external/custom quarantine path (repeatable)")
|
|
31
|
+
ap.add_argument("--max-depth", type=int, default=None,
|
|
32
|
+
help="directory depth below each search root (default 3)")
|
|
33
|
+
ap.add_argument("--max-entries", type=int, default=None,
|
|
34
|
+
help="index directory-entry budget (default 10000)")
|
|
24
35
|
args = ap.parse_args()
|
|
25
36
|
|
|
26
37
|
base = os.getcwd()
|
|
38
|
+
if args.trash_index:
|
|
39
|
+
from core.trash_index import (
|
|
40
|
+
DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENTRIES, list_trash_locations)
|
|
41
|
+
roots, paths = list(args.root), list(args.trash)
|
|
42
|
+
if not roots and not paths:
|
|
43
|
+
roots = [base]
|
|
44
|
+
configured = os.environ.get("AGENT_GUARD_TRASH")
|
|
45
|
+
if configured:
|
|
46
|
+
paths.append(configured)
|
|
47
|
+
try:
|
|
48
|
+
result = list_trash_locations(
|
|
49
|
+
roots, trash_paths=paths,
|
|
50
|
+
max_depth=(DEFAULT_MAX_DEPTH if args.max_depth is None
|
|
51
|
+
else args.max_depth),
|
|
52
|
+
max_entries=(DEFAULT_MAX_ENTRIES if args.max_entries is None
|
|
53
|
+
else args.max_entries))
|
|
54
|
+
except ValueError as exc:
|
|
55
|
+
ap.error(str(exc))
|
|
56
|
+
if args.as_json:
|
|
57
|
+
# ASCII escapes preserve unusual POSIX names in valid UTF-8 JSON.
|
|
58
|
+
print(json.dumps(result, ensure_ascii=True, indent=2))
|
|
59
|
+
else:
|
|
60
|
+
print(f"quarantine locations: {result['count']} candidates, "
|
|
61
|
+
f"{result['identified_count']} with metadata")
|
|
62
|
+
print(f"scope: depth={result['max_depth']} budget={result['max_entries']}")
|
|
63
|
+
for path in result["roots"]:
|
|
64
|
+
print(f" root: {json.dumps(path)}")
|
|
65
|
+
for path in result["trash_paths"]:
|
|
66
|
+
print(f" declared: {json.dumps(path)}")
|
|
67
|
+
for row in result["entries"]:
|
|
68
|
+
print(f" [{row['status']}] {json.dumps(row['trash_root'])}")
|
|
69
|
+
if row["trash_root"] != row["resolved_trash_root"]:
|
|
70
|
+
print(f" resolved: {json.dumps(row['resolved_trash_root'])}")
|
|
71
|
+
for error in result["errors"]:
|
|
72
|
+
print(f" {error['code']}: {json.dumps(error['path'])}")
|
|
73
|
+
if not result["complete"]:
|
|
74
|
+
print("partial index: inspect scope and errors")
|
|
75
|
+
return 0 if result["complete"] else 1
|
|
76
|
+
if (args.root or args.trash or args.max_depth is not None or
|
|
77
|
+
args.max_entries is not None):
|
|
78
|
+
ap.error("index options require --trash-index")
|
|
27
79
|
workspace = classifier.discover_workspace(base)
|
|
28
80
|
trash_root = os.environ.get(
|
|
29
81
|
"AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
|
|
@@ -44,6 +44,11 @@ python3 <repo>/skills/exfil-guard/scripts/sanitize.py --channel file-write < dra
|
|
|
44
44
|
never writes, never rewrites, and never prints the match. Exit codes are the
|
|
45
45
|
contract: `0` allow/sanitize, `2` block, `3` ask, `1` error.
|
|
46
46
|
|
|
47
|
+
`sanitize.py` uses the same exit codes and emits no payload on ASK/BLOCK or
|
|
48
|
+
error. Both CLIs bound stdin while reading (4 MiB by default), support UTF-8,
|
|
49
|
+
and resolve the same default workspace/host-side mode. The first-byte wait is
|
|
50
|
+
bounded; it is not a deadline for a producer that has already started writing.
|
|
51
|
+
|
|
47
52
|
## Safe config view
|
|
48
53
|
|
|
49
54
|
When you need to learn a JSON or dotenv config's shape, use the explicit
|
|
@@ -74,7 +79,7 @@ intercept a harness's ordinary file-read tool.
|
|
|
74
79
|
| `ASK` (`ASK_SECRET_EMISSION` / `ASK_PATH_EMISSION`) | the channel cannot be rewritten and cannot be taken back (a terminal transcript cannot be un-printed) | stop and ask a human; do not silently proceed |
|
|
75
80
|
| `BLOCK` (`BLOCK_SECRET_EMISSION` / `BLOCK_PATH_EMISSION`) | the channel is immutable or remote history (commit message, push payload) | **do not retry.** Remove the value and redo the message/commit |
|
|
76
81
|
| `BLOCK_SECRET_SOURCE_DUMP` | the payload reads a whole secret store (`cat .env`, `printenv`) whose content the guard never saw | stop; emit an explicit, reviewed value instead |
|
|
77
|
-
| `BLOCK_OUTPUT_UNSCANNABLE` | the payload was never scanned (too large,
|
|
82
|
+
| `BLOCK_OUTPUT_UNSCANNABLE` | the payload was never scanned (too large, unknown channel, scanner error) | an unscanned egress is not a clean egress. Do not route around it |
|
|
78
83
|
|
|
79
84
|
A `BLOCK` is not an obstacle to work around. Re-encoding a payload, splitting
|
|
80
85
|
a secret across lines, or piping through a tool the guard does not scan is a
|
|
@@ -84,10 +89,17 @@ violation of the authorization pillar and is recorded in the audit log.
|
|
|
84
89
|
|
|
85
90
|
The guard deliberately does not rewrite your payload - you hold it. Apply
|
|
86
91
|
the plan back to front so offsets stay valid, or let `sanitize.py` do it.
|
|
87
|
-
Redaction **preserves format**: `sk-proj-Ab…` becomes `sk
|
|
92
|
+
Redaction **preserves format**: `sk-proj-Ab…` becomes `sk-<REDACTED>`
|
|
88
93
|
(so a reviewer can still see *which kind* of credential leaked), and a host
|
|
89
94
|
path becomes `<PATH>`.
|
|
90
95
|
|
|
96
|
+
An external `--plan` is checked against a fresh scan, including offsets,
|
|
97
|
+
placeholders and any supplied rule metadata. A partial, stale or arbitrary plan
|
|
98
|
+
is refused; the rewritten payload must pass another scan. A plan made with
|
|
99
|
+
checker-specific mode/path overrides still has to satisfy current sanitizer
|
|
100
|
+
policy. URI passwords use `<REDACTED>` while retaining scheme/account/host;
|
|
101
|
+
this is credential redaction, not network-topology hiding or an editable URI.
|
|
102
|
+
|
|
91
103
|
If you decline to apply a plan on a rewritable channel, the API contract is
|
|
92
104
|
"you were told": the audit records `sanitize-declined`. That is a choice
|
|
93
105
|
with a record, not a default.
|
|
@@ -95,16 +107,34 @@ with a record, not a default.
|
|
|
95
107
|
## Value-free detection (why `echo "$TOKEN"` is caught)
|
|
96
108
|
|
|
97
109
|
The guard detects a secret *reference* without ever reading the secret. It
|
|
98
|
-
classifies a variable's **name** (
|
|
99
|
-
|
|
110
|
+
classifies a variable's **name** by complete credential components (`KEY`,
|
|
111
|
+
`TOKEN`, `SECRET`, `PASSWORD`, `CRED`, `AUTH`, including underscores and
|
|
112
|
+
camelCase), and a secret-store **file name**
|
|
100
113
|
(`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, …), never a value.
|
|
101
114
|
This keeps this scanner from creating a second value copy; it does not
|
|
102
115
|
certify unrelated CLI output or existing audit records as secret-free.
|
|
103
116
|
|
|
104
117
|
Consequence you will notice: if `$OPENAI_API_KEY` actually holds `"test"`,
|
|
105
|
-
the guard still
|
|
106
|
-
|
|
107
|
-
|
|
118
|
+
the guard still BLOCKs its uninspectable source reference. Do not attempt to
|
|
119
|
+
resolve the variable to soften that decision. `MONKEY`/`API_KEYBOARD` are
|
|
120
|
+
ordinary names, and terminal `COUNT`/`LENGTH`/`ENABLED` denotes metadata.
|
|
121
|
+
Public-key names retain conservative handling pending separate review.
|
|
122
|
+
Bare lower/title-case `key` is too ambiguous to classify without an explicit
|
|
123
|
+
environment reference; uppercase `KEY` and qualified `apiKey` remain protected.
|
|
124
|
+
|
|
125
|
+
Placeholder exemptions require a whole documented shape or an exact static
|
|
126
|
+
example; incidental words inside random credentials do not exempt them.
|
|
127
|
+
Vendor credentials adjacent to CJK prose are scanned with original offsets.
|
|
128
|
+
GitHub installation credentials support both classic and `ghs_APPID_JWT`
|
|
129
|
+
shapes, with complete redaction of long tokens. These are shape facts, not
|
|
130
|
+
authentication or token-validity checks. See [rules.md](references/rules.md).
|
|
131
|
+
|
|
132
|
+
PyPI token bodies follow the documented `pypi-` scanner shape and are redacted
|
|
133
|
+
in full, including long bodies. AWS access-key IDs use AKIA/ASIA; IAM resource
|
|
134
|
+
IDs have separate types and do not match that credential rule. Generic JWT
|
|
135
|
+
headers require a nonempty ASCII string `alg`. Public-key variable names and
|
|
136
|
+
the broad legacy `sk-` shape retain conservative handling where their purpose
|
|
137
|
+
or complete format has not been established.
|
|
108
138
|
|
|
109
139
|
## Path rules
|
|
110
140
|
|
|
@@ -39,7 +39,7 @@ Rules the table encodes:
|
|
|
39
39
|
them here is the opposite of a claim: it is the coverage gap, stated so no
|
|
40
40
|
reader infers coverage the guard does not have.
|
|
41
41
|
|
|
42
|
-
Per `docs/threat-model.md`, the guard "may not claim" prevention of
|
|
42
|
+
Per `docs/design/threat-model.md`, the guard "may not claim" prevention of
|
|
43
43
|
adversarial exfiltration, and per design 4.4 an unreachable channel gets
|
|
44
44
|
**no verdict at all**.
|
|
45
45
|
|
|
@@ -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
|