@mokuyoaxis/agent-guard 0.2.3 → 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 +70 -63
- package/README.zh-CN.md +61 -59
- 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 +10 -6
- package/adapters/dsh/harness/README.md +8 -8
- package/adapters/dsh/harness/guard_lab.py +3 -3
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +7 -7
- 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/policy.py +28 -13
- package/core/recovery.py +256 -23
- 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} +2 -2
- package/docs/{friction.md → history/friction.md} +61 -0
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
- 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} +2 -2
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
- 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/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} +3 -3
- 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} +1 -1
- package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +38 -0
- 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/references/channels.md +1 -1
- /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-read-trial-task.md → lab/tasks/guard-lab-read-trial-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-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.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
|
@@ -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))
|
|
@@ -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
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
/package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md}
RENAMED
|
File without changes
|