@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4

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 (81) hide show
  1. package/README.md +127 -83
  2. package/README.zh-CN.md +106 -74
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +24 -15
  8. package/adapters/dsh/harness/README.md +75 -19
  9. package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
  10. package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
  11. package/adapters/dsh/harness/guard_lab.py +194 -32
  12. package/adapters/dsh/harness/native_session.py +41 -20
  13. package/adapters/dsh/harness/profiles.py +74 -22
  14. package/adapters/dsh/lib/index.js +1 -1
  15. package/adapters/kimi-code/README.md +15 -14
  16. package/adapters/kimi-code/harness/README.md +3 -3
  17. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  18. package/core/__init__.py +1 -1
  19. package/core/classifier.py +41 -16
  20. package/core/lab.py +24 -1
  21. package/core/policy.py +11 -4
  22. package/core/recovery.py +256 -23
  23. package/core/redaction.py +157 -55
  24. package/core/trash_index.py +193 -0
  25. package/docs/README.md +104 -0
  26. package/docs/{architecture.md → design/architecture.md} +31 -6
  27. package/docs/{compatibility.md → design/compatibility.md} +54 -4
  28. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  29. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  30. package/docs/guides/trash-index.md +106 -0
  31. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +8 -9
  32. package/docs/{friction.md → history/friction.md} +107 -4
  33. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +23 -22
  34. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +6 -4
  35. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +19 -15
  36. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  37. package/docs/{guard-lab.md → lab/guard-lab.md} +18 -11
  38. package/docs/lab/tasks/guard-lab-read-trial-task.md +7 -0
  39. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +5 -5
  40. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +7 -7
  41. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  42. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +9 -10
  43. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +4 -2
  44. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  45. package/docs/releases/release-notes-0.2.3.md +84 -0
  46. package/docs/releases/release-notes-0.2.4.md +89 -0
  47. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  48. package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
  49. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  50. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  51. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  52. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  53. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  54. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  55. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  56. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
  57. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  58. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
  59. package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
  60. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
  61. package/package.json +1 -1
  62. package/skills/delete-guard/SKILL.md +40 -3
  63. package/skills/delete-guard/references/policy.md +18 -5
  64. package/skills/delete-guard/scripts/check.py +19 -0
  65. package/skills/delete-guard/scripts/restore.py +18 -6
  66. package/skills/delete-guard/scripts/status.py +52 -0
  67. package/skills/exfil-guard/SKILL.md +37 -7
  68. package/skills/exfil-guard/references/channels.md +1 -1
  69. package/skills/exfil-guard/references/rules.md +84 -16
  70. package/skills/exfil-guard/scripts/_payload.py +99 -0
  71. package/skills/exfil-guard/scripts/check_span.py +14 -81
  72. package/skills/exfil-guard/scripts/sanitize.py +113 -34
  73. package/docs/release-notes-0.2.3.md +0 -45
  74. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  75. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  76. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  77. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  78. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  79. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  80. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  81. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -51,7 +51,7 @@ 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; `reset --hard`/force-push exempt (position-independent) |
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
  | 3 | any target inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | direct delete permitted (housekeeping) |
57
57
  | 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
@@ -64,7 +64,9 @@ 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`, `git restore <path>`, `git checkout -- <path>` | `SNAPSHOT_GIT_STASH` | `git stash create`+`store` first; any create/store failure blocks |
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 |
@@ -154,8 +156,19 @@ model tool.
154
156
 
155
157
  - Command-level interception covers the recognized vocabulary; arbitrary
156
158
  scripts that delete internally are invisible to `check.py` (see
157
- `docs/threat-model.md`).
158
- - `git stash create` captures tracked modifications; untracked files are not
159
- affected by `reset --hard`, so they need no snapshot.
159
+ `docs/design/threat-model.md`).
160
+ - `git stash create` captures tracked modifications only. `reset --hard`
161
+ can delete untracked and ignored content that obstructs its target tree.
162
+ `check.py` checks file/directory/ancestor collisions and refuses them;
163
+ this version does not automatically archive those paths. It also refuses
164
+ target-tree writes into quarantine. Ordinary unrelated untracked files
165
+ remain allowed. Only `--hard`, optional `-q`/`--quiet`, and at most one
166
+ commit are supported; submodules and stash-relative targets are refused.
167
+ - Hard reset must be standalone without shell wrappers: other segments can
168
+ change its revision or create a collision after preflight; wrappers can
169
+ change its Git environment. The preflight and host execution are separate;
170
+ concurrent changes are not atomically excluded.
171
+ Direct callers of `snapshot_git` receive a tracked-only snapshot and must
172
+ run the hard-reset preflight themselves before authorizing that operation.
160
173
  - Windows cmd/PowerShell, databases, cloud resources: future skills
161
174
  (`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 is an explicit human decision.
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
- audit.append({"event": "restore", "txid": args.txid, "force": args.force,
73
- "ok": report.get("ok"), "restored": report.get("restored"),
74
- "conflicts": report.get("conflicts"),
75
- "errors": report.get("errors")},
76
- os.path.join(engine.trash_root, AUDIT_NAME))
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, non-ASCII, unknown channel, scanner error) | an unscanned egress is not a clean egress. Do not route around it |
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-proj-<REDACTED>`
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** (`*KEY*`, `*TOKEN*`, `*SECRET*`,
99
- `*PASSWORD*`, `*CRED*`, `*AUTH*`) and a secret-store **file name**
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 ASKs. That is intentional. The cost of a false ASK is one
106
- keystroke; the cost of a false ALLOW is permanent. Do not attempt to
107
- "resolve" the variable to reduce prompts.
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, non-ASCII, scanner error |
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 / non-ASCII / scanner error | BLOCK | `BLOCK_OUTPUT_UNSCANNABLE` |
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+ | fixed-format prefix |
67
- | `secret/aws-access-key-id` | `AKIA`/`ASIA`/`AGPA`/`AIDA`/`AROA`/`ANPA` + 16 upper-alnum | globally reserved prefix |
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/jwt` | three base64url segments; header decodes to JSON containing `alg` | **structural**, not just `a.b.c` |
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/source-reference` | an env-var *name* (`*KEY*`, `*TOKEN*`, …), a secret-store file name, or a whole-environment expansion | value-free (T2) |
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: `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.
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 `check_span.py` |
124
- | `AGENT_GUARD_EXFIL_MAX_BYTES` | payload size cap (default 4 MiB); over-cap is `BLOCK_OUTPUT_UNSCANNABLE` |
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