@mokuyoaxis/agent-guard 0.2.2 → 0.2.3-rc1
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 +14 -6
- package/README.zh-CN.md +14 -6
- package/adapters/claude/README.md +5 -5
- package/core/classifier.py +90 -23
- package/core/dialects.py +6 -5
- package/docs/architecture.md +27 -12
- package/docs/compatibility.md +10 -5
- package/docs/friction.md +23 -0
- package/docs/release-notes-0.2.3-rc1.md +92 -0
- package/docs/test-report-zcode-glm-flash.md +8 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](https://github.com/mokuyoaxis/agent-guard/releases)
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -58,6 +58,10 @@ Pinned npm installation into a stable, user-owned prefix:
|
|
|
58
58
|
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
+
`0.2.2` remains the stable recommendation. After the candidate is published,
|
|
62
|
+
explicit testers may select `@mokuyoaxis/agent-guard@0.2.3-rc1` or the npm
|
|
63
|
+
`@rc` channel; prereleases do not replace npm `latest`.
|
|
64
|
+
|
|
61
65
|
The package root is then
|
|
62
66
|
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
63
67
|
Alternatively, clone the source (skip this if you already have a checkout):
|
|
@@ -482,6 +486,7 @@ compensation engine without restructuring.
|
|
|
482
486
|
| [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
|
|
483
487
|
| [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
|
|
484
488
|
| [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
|
|
489
|
+
| [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed candidate and prerelease channel |
|
|
485
490
|
| [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 host drift, live sentinel and DSH package acceptance |
|
|
486
491
|
| [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
|
|
487
492
|
| [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
|
|
@@ -499,13 +504,15 @@ compensation engine without restructuring.
|
|
|
499
504
|
|
|
500
505
|
## Status & roadmap
|
|
501
506
|
|
|
502
|
-
The source version is **v0.2.
|
|
507
|
+
The source version is **v0.2.3-rc1**; the latest stable release remains
|
|
508
|
+
**v0.2.2**. The published `v0.2.0` baseline includes
|
|
503
509
|
recoverable destructive actions, cmd/PowerShell dialect parsing, the
|
|
504
510
|
`exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
|
|
505
511
|
Later source releases add Claude/Kimi POSIX hook bridges, bounded host
|
|
506
512
|
evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
|
|
507
513
|
current DSH package acceptance. See the
|
|
508
|
-
[0.2.
|
|
514
|
+
[0.2.3-rc1 notes](docs/release-notes-0.2.3-rc1.md) for the candidate scope,
|
|
515
|
+
[0.2.2 notes](docs/release-notes-0.2.2.md) for the stable scope, and
|
|
509
516
|
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
|
|
510
517
|
publication status; a source version is not itself a published Release.
|
|
511
518
|
|
|
@@ -518,13 +525,14 @@ actions are protected. A tested direct-Python hook startup failure was
|
|
|
518
525
|
fail-open. The optional shell bridge blocked a sampled Python startup failure
|
|
519
526
|
in a real Kimi host session, but only when the bridge itself ran; config
|
|
520
527
|
validation alone cannot prove that the hook is live.
|
|
521
|
-
|
|
522
|
-
|
|
528
|
+
The candidate adds a focused real-Windows Core gate for Issue #7, but native
|
|
529
|
+
cmd/PowerShell execution through every harness and general concurrent-subagent
|
|
530
|
+
safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
|
|
523
531
|
`cloud-guard`) reuse the same protocol and compensation engine.
|
|
524
532
|
|
|
525
533
|
## 0.2.x preview: guard-lab
|
|
526
534
|
|
|
527
|
-
Planned, **not included in 0.2.
|
|
535
|
+
Planned, **not included in 0.2.3-rc1**: an opt-in, offline honeytoken lab
|
|
528
536
|
using disposable projects and synthetic, non-secret markers. It will compare
|
|
529
537
|
normal tasks with prompt-injection attempts, and separately observe whether a
|
|
530
538
|
harness indexes or exports files without an agent-requested read. Positive and
|
package/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](https://github.com/mokuyoaxis/agent-guard/releases)
|
|
8
8
|
|
|
9
9
|
**让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
|
|
10
10
|
|
|
@@ -48,6 +48,10 @@ checkout。不要误装无作用域的同名 `agent-guard` 包。
|
|
|
48
48
|
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
+
`0.2.2` 仍是稳定版推荐。候选版发布后,测试者可显式选择
|
|
52
|
+
`@mokuyoaxis/agent-guard@0.2.3-rc1` 或 npm 的 `@rc` 通道;预发布不会替换
|
|
53
|
+
npm `latest`。
|
|
54
|
+
|
|
51
55
|
安装后的包根目录是
|
|
52
56
|
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
|
|
53
57
|
也可以克隆源码;如果已有 checkout,跳过克隆:
|
|
@@ -425,6 +429,7 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
425
429
|
| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
|
|
426
430
|
| [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
|
|
427
431
|
| [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
|
|
432
|
+
| [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
|
|
428
433
|
| [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
|
|
429
434
|
| [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
|
|
430
435
|
| [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
|
|
@@ -442,11 +447,13 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
442
447
|
|
|
443
448
|
## 状态与路线图
|
|
444
449
|
|
|
445
|
-
当前源码版本为 **v0.2.
|
|
450
|
+
当前源码版本为 **v0.2.3-rc1**,最新稳定版仍为 **v0.2.2**。已发布的
|
|
451
|
+
`v0.2.0` 基线包含可恢复的破坏性
|
|
446
452
|
操作、cmd/PowerShell 方言解析、`exfil-guard` 文本 CLI、只读配置安全视图
|
|
447
453
|
和 `recovery-audit`。后续源码版新增 Claude/Kimi POSIX hook 桥、有界宿主
|
|
448
454
|
证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH 打包验收。准确范围见
|
|
449
|
-
[0.2.
|
|
455
|
+
[0.2.3-rc1 说明](docs/release-notes-0.2.3-rc1.md)记录候选范围,
|
|
456
|
+
[0.2.2 说明](docs/release-notes-0.2.2.md)记录稳定版范围;是否已正式发布以
|
|
450
457
|
[GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) 为准,
|
|
451
458
|
源码版本号本身不代表已有 Release。
|
|
452
459
|
|
|
@@ -455,13 +462,14 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
|
|
|
455
462
|
Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
|
|
456
463
|
所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
|
|
457
464
|
启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
|
|
458
|
-
但前提是桥自身成功运行;单凭配置校验无法证明 hook
|
|
459
|
-
|
|
465
|
+
但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。候选版为 Issue #7
|
|
466
|
+
新增了聚焦的真实 Windows Core 门,但各 harness 下的原生 cmd/PowerShell
|
|
467
|
+
执行与一般并发子代理安全仍是明确缺口。
|
|
460
468
|
后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
|
|
461
469
|
|
|
462
470
|
## 0.2.x 预告:guard-lab 合成蜜罐
|
|
463
471
|
|
|
464
|
-
这是规划中的可选实验,**不属于 0.2.
|
|
472
|
+
这是规划中的可选实验,**不属于 0.2.3-rc1**。它会在离线、一次性的测试项目
|
|
465
473
|
里放入无认证能力的合成标记,对照正常任务与提示词注入诱导;另设试次观察
|
|
466
474
|
harness 是否在 Agent 未请求读取时自行索引或外发文件。正负对照、独立观察器
|
|
467
475
|
和证据分级将区分“提出读取”“本地接触”与“证实越过外部边界”。不使用真实
|
|
@@ -115,11 +115,11 @@ lines are lexed with the right rules. Precedence:
|
|
|
115
115
|
| environment | `AGENT_GUARD_DIALECT=powershell` |
|
|
116
116
|
| default | `posix` |
|
|
117
117
|
|
|
118
|
-
The prefilter
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
118
|
+
The prefilter screens both POSIX and Windows destructive vocabularies. The
|
|
119
|
+
dialect chooses the lexer, not whether a suspicious command reaches Core;
|
|
120
|
+
this lets Core turn a known vocabulary mismatch into a fail-closed verdict.
|
|
121
|
+
An unrecognised dialect selector is **not** swapped for POSIX - `check.py`
|
|
122
|
+
returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
|
|
123
123
|
|
|
124
124
|
## Live-tested
|
|
125
125
|
|
package/core/classifier.py
CHANGED
|
@@ -14,9 +14,9 @@ Design rules:
|
|
|
14
14
|
push) covers the overwhelming majority of real agent accidents on
|
|
15
15
|
Linux/macOS. Native Windows shells express the same effects with other
|
|
16
16
|
programs and other lexical rules; those live in `dialects.py` and are
|
|
17
|
-
dispatched by `classify_command(dialect=...)`. The default
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
dispatched by `classify_command(dialect=...)`. The default lexer is POSIX;
|
|
18
|
+
a separate vocabulary-mismatch floor prevents known destructive commands
|
|
19
|
+
from disappearing merely because a host selected the wrong lexer.
|
|
20
20
|
* Fail closed. Unbalanced quotes, shell variables, command substitution,
|
|
21
21
|
unknown flags, stdin-fed target lists, indirect shells (bash -c) - all
|
|
22
22
|
become `undeterminable` facts. The policy layer restricts those.
|
|
@@ -693,13 +693,11 @@ def _normalize_windows_separators(cmd: str) -> str:
|
|
|
693
693
|
r"""Turn a backslash into a slash so `del build\o.js` survives POSIX.
|
|
694
694
|
|
|
695
695
|
`shlex.split(..., posix=True)` treats `\` as an escape and silently
|
|
696
|
-
yields `buildo.js` - one wrong filename instead of a path.
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
696
|
+
yields `buildo.js` - one wrong filename instead of a path. The caller
|
|
697
|
+
invokes this only for a standalone Windows delete verb, so normal POSIX
|
|
698
|
+
escapes are untouched. Lexical facts must not depend on the OS running
|
|
699
|
+
the classifier: Windows accepts `/` as a path separator too.
|
|
700
700
|
"""
|
|
701
|
-
if os.name == "nt":
|
|
702
|
-
return cmd
|
|
703
701
|
return cmd.replace("\\", "/")
|
|
704
702
|
|
|
705
703
|
|
|
@@ -992,6 +990,73 @@ def _parse_error_spec(exc: str,
|
|
|
992
990
|
return spec
|
|
993
991
|
|
|
994
992
|
|
|
993
|
+
_KNOWN_DELETE_HEADS = frozenset(
|
|
994
|
+
FS_DELETE_CMDS | WINDOWS_DELETE_CMDS | {"remove-item"})
|
|
995
|
+
|
|
996
|
+
|
|
997
|
+
def _portable_command_name(token: str, casefold: bool = True) -> str:
|
|
998
|
+
"""Command basename for safety probes, independent of the host OS."""
|
|
999
|
+
cleaned = token.strip().strip("&").strip("'\"")
|
|
1000
|
+
base = os.path.basename(cleaned.replace("\\", "/"))
|
|
1001
|
+
if casefold:
|
|
1002
|
+
base = base.lower()
|
|
1003
|
+
return base[:-4] if casefold and base.endswith(".exe") else base
|
|
1004
|
+
|
|
1005
|
+
|
|
1006
|
+
def _known_destructive_segment(segment: List[str], dialect: str) -> bool:
|
|
1007
|
+
"""Whether one selected-dialect command segment has a known hazard.
|
|
1008
|
+
|
|
1009
|
+
This deliberately examines the command head/shape produced by the
|
|
1010
|
+
*selected* tokenizer. Re-parsing the raw line as another shell would
|
|
1011
|
+
manufacture semantics (for example cmd treats ``$(rm ...)`` as text).
|
|
1012
|
+
The result is only a mismatch signal; callers must not derive targets or
|
|
1013
|
+
a compensation plan from it.
|
|
1014
|
+
"""
|
|
1015
|
+
if not segment:
|
|
1016
|
+
return False
|
|
1017
|
+
windows_syntax = dialect != dialects.DIALECT_POSIX
|
|
1018
|
+
head = _portable_command_name(segment[0], casefold=windows_syntax)
|
|
1019
|
+
if head in _KNOWN_DELETE_HEADS:
|
|
1020
|
+
return True
|
|
1021
|
+
if not windows_syntax and head.lower() in (
|
|
1022
|
+
WINDOWS_DELETE_CMDS | {"remove-item"}):
|
|
1023
|
+
# A foreign Windows verb may arrive in any case even though the
|
|
1024
|
+
# selected POSIX shell is case-sensitive. Do not case-fold POSIX's
|
|
1025
|
+
# own command vocabulary (`RM` may be an unrelated executable).
|
|
1026
|
+
return True
|
|
1027
|
+
if head == "find":
|
|
1028
|
+
probe = _parse_find(["find", *segment[1:]])
|
|
1029
|
+
return probe.kind != KIND_OTHER
|
|
1030
|
+
if head == "git":
|
|
1031
|
+
probe = _parse_git(["git", *segment[1:]])
|
|
1032
|
+
return probe.kind != KIND_OTHER
|
|
1033
|
+
return False
|
|
1034
|
+
|
|
1035
|
+
|
|
1036
|
+
def _append_dialect_mismatches(specs: List[OpSpec],
|
|
1037
|
+
segments: List[List[str]],
|
|
1038
|
+
dialect: str) -> None:
|
|
1039
|
+
"""Fail closed when known destructive vocabulary vanished in parsing.
|
|
1040
|
+
|
|
1041
|
+
One operation in an earlier segment must not mask a missed later one.
|
|
1042
|
+
``segment_index`` is therefore the coverage key. The appended UNKNOWN
|
|
1043
|
+
fact carries no raw command or target bytes and can only BLOCK; it can
|
|
1044
|
+
never authorize compensation under a grammar the caller did not select.
|
|
1045
|
+
"""
|
|
1046
|
+
covered = {spec.segment_index for spec in specs}
|
|
1047
|
+
for index, segment in enumerate(segments):
|
|
1048
|
+
if index in covered or not _known_destructive_segment(
|
|
1049
|
+
segment, dialect):
|
|
1050
|
+
continue
|
|
1051
|
+
spec = _unknown_op(
|
|
1052
|
+
"known destructive vocabulary is incompatible with the "
|
|
1053
|
+
"selected dialect")
|
|
1054
|
+
spec.segment_index = index
|
|
1055
|
+
spec.dialect = dialect
|
|
1056
|
+
specs.append(spec)
|
|
1057
|
+
specs.sort(key=lambda spec: spec.segment_index)
|
|
1058
|
+
|
|
1059
|
+
|
|
995
1060
|
_WINDOWS_PREFIX_RE = "|".join(sorted(SHELL_PREFIXES - {"xargs"}))
|
|
996
1061
|
_WINDOWS_COMMAND_RE = re.compile(
|
|
997
1062
|
r"(^|[;&|\n])\s*(?:(?:" + _WINDOWS_PREFIX_RE + r")\s+)*"
|
|
@@ -1050,7 +1115,9 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
|
|
|
1050
1115
|
spec.segment_index = index
|
|
1051
1116
|
specs.append(spec)
|
|
1052
1117
|
|
|
1053
|
-
|
|
1118
|
+
raw_segments = _split_segments(tokens)
|
|
1119
|
+
command_segments: List[List[str]] = [[] for _ in raw_segments]
|
|
1120
|
+
for index, segment in enumerate(raw_segments):
|
|
1054
1121
|
seg, from_xargs, prefix_uncertain = _unwrap_shell_prefixes(segment)
|
|
1055
1122
|
if prefix_uncertain:
|
|
1056
1123
|
opaque = " ".join(segment)
|
|
@@ -1061,6 +1128,7 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
|
|
|
1061
1128
|
continue
|
|
1062
1129
|
if not seg:
|
|
1063
1130
|
continue
|
|
1131
|
+
command_segments[index] = seg
|
|
1064
1132
|
head = _basename(seg[0])
|
|
1065
1133
|
|
|
1066
1134
|
if head == "cd":
|
|
@@ -1089,6 +1157,8 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
|
|
|
1089
1157
|
|
|
1090
1158
|
for spec in specs:
|
|
1091
1159
|
spec.dialect = dialects.DIALECT_POSIX
|
|
1160
|
+
_append_dialect_mismatches(
|
|
1161
|
+
specs, command_segments, dialects.DIALECT_POSIX)
|
|
1092
1162
|
_apply_shape_rules(specs, cd_positions, creation_positions)
|
|
1093
1163
|
return [s for s in specs if s.kind != KIND_OTHER], None
|
|
1094
1164
|
|
|
@@ -1114,12 +1184,10 @@ def _classify_windows_dialect(cmd: str, dialect: str
|
|
|
1114
1184
|
) -> Tuple[List[OpSpec], Optional[str]]:
|
|
1115
1185
|
"""Native Windows dialects: lex, map effects, then shared annotations.
|
|
1116
1186
|
|
|
1117
|
-
Rewriting
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
commands keep their separators - the running host already resolves
|
|
1122
|
-
them.
|
|
1187
|
+
Rewriting target separators after tokenization gives the shared
|
|
1188
|
+
boundary/glob machinery one host-independent representation. Windows
|
|
1189
|
+
accepts `/`, while leaving `\\` in the fact makes Linux and Windows CI
|
|
1190
|
+
disagree about the same command.
|
|
1123
1191
|
|
|
1124
1192
|
Shape rules (docs/friction.md F1/F2) apply to Windows lines too: `cd`
|
|
1125
1193
|
and the interpreter prefix set are shared shell concepts, so F1 means
|
|
@@ -1142,12 +1210,9 @@ def _classify_windows_dialect(cmd: str, dialect: str
|
|
|
1142
1210
|
creation_positions.append(index)
|
|
1143
1211
|
for spec in specs:
|
|
1144
1212
|
spec.dialect = dialect
|
|
1145
|
-
|
|
1146
|
-
# Path separation is a host concern, not a dialect concern:
|
|
1147
|
-
# only rewrite on a non-Windows host, where `\` is an ordinary
|
|
1148
|
-
# filename character and would defeat boundary analysis.
|
|
1149
|
-
spec.targets = [t.replace("\\", "/") for t in spec.targets]
|
|
1213
|
+
spec.targets = [t.replace("\\", "/") for t in spec.targets]
|
|
1150
1214
|
_attribute_targets(spec)
|
|
1215
|
+
_append_dialect_mismatches(specs, stream.segments, dialect)
|
|
1151
1216
|
_apply_shape_rules(specs, cd_positions, creation_positions)
|
|
1152
1217
|
return [s for s in specs if s.kind != KIND_OTHER], None
|
|
1153
1218
|
|
|
@@ -1156,8 +1221,10 @@ def classify_command(cmd: str, dialect: str = dialects.DEFAULT_DIALECT
|
|
|
1156
1221
|
) -> Tuple[List[OpSpec], Optional[str]]:
|
|
1157
1222
|
"""Parse one shell command line into destructive OpSpecs.
|
|
1158
1223
|
|
|
1159
|
-
`dialect` selects the lexical front end: `posix` (default,
|
|
1160
|
-
|
|
1224
|
+
`dialect` selects the lexical front end: `posix` (default), `cmd`, or
|
|
1225
|
+
`powershell`. Native POSIX command semantics remain stable, while the
|
|
1226
|
+
shared vocabulary floor may newly refuse a known destructive command
|
|
1227
|
+
that the selected grammar could not classify. Unknown dialect names
|
|
1161
1228
|
raise ValueError rather than silently falling back to POSIX - parsing a
|
|
1162
1229
|
Windows command line with the POSIX lexer is the exact failure the
|
|
1163
1230
|
dialect layer exists to prevent.
|
package/core/dialects.py
CHANGED
|
@@ -31,11 +31,12 @@ Design rules (mirroring the core's):
|
|
|
31
31
|
another process, a wildcard handed to a tool that expands it itself -
|
|
32
32
|
becomes an `undeterminable` fact. The policy layer turns those into
|
|
33
33
|
BLOCK. We never guess what a target set will be.
|
|
34
|
-
* **
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
34
|
+
* **Selected lexer, shared safety floor.** POSIX remains the default lexical
|
|
35
|
+
grammar, while cmd and PowerShell keep their own quoting and separators.
|
|
36
|
+
After structural classification, Core may add a target-free UNKNOWN when
|
|
37
|
+
the selected tokenizer exposed known destructive vocabulary that its
|
|
38
|
+
classifier could not safely interpret. That is an intentional fail-closed
|
|
39
|
+
change, never a guessed cross-shell compensation.
|
|
39
40
|
* **Facts, not decisions.** Like the rest of the classifier, a dialect
|
|
40
41
|
returns OpSpecs only; it never decides ALLOW/BLOCK.
|
|
41
42
|
|
package/docs/architecture.md
CHANGED
|
@@ -92,7 +92,7 @@ neither do the lexical rules. `core/dialects.py` isolates both concerns:
|
|
|
92
92
|
|
|
93
93
|
```
|
|
94
94
|
classify_command(cmd, dialect="posix")
|
|
95
|
-
posix -> shlex + heredoc stripping (default
|
|
95
|
+
posix -> shlex + heredoc stripping (default lexer)
|
|
96
96
|
cmd -> caret escapes, & separators, no
|
|
97
97
|
backslash escapes in quotes, del/erase/rd/rmdir, /s /q
|
|
98
98
|
powershell -> '' literal quoting, ` escapes, $() kept verbatim,
|
|
@@ -110,15 +110,16 @@ The dialect is selected by, in precedence order:
|
|
|
110
110
|
|
|
111
111
|
Both adapters forward the *requested* selector verbatim rather than a
|
|
112
112
|
resolved value, so `check.py` owns the single verdict for an unusable
|
|
113
|
-
selector.
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
the default path keeps its exact behaviour and cost.
|
|
113
|
+
selector. Their cheap prefilter screens both POSIX and Windows vocabularies:
|
|
114
|
+
the selector chooses the lexer, not whether a destructive-looking command
|
|
115
|
+
reaches Core at all.
|
|
117
116
|
|
|
118
117
|
Four rules keep the layer honest:
|
|
119
118
|
|
|
120
|
-
* **The default
|
|
121
|
-
|
|
119
|
+
* **The default lexer is POSIX.** Existing POSIX syntax keeps POSIX quoting
|
|
120
|
+
and separator rules. The cross-vocabulary safety floor is deliberately
|
|
121
|
+
additive: a known destructive command that previously vanished on a
|
|
122
|
+
mismatch now blocks instead of becoming `ALLOW_NOOP`.
|
|
122
123
|
* **An unknown dialect name is never a silent POSIX fallback.** The
|
|
123
124
|
library raises/returns unusable; the CLI and adapters turn that into
|
|
124
125
|
`BLOCK_DIALECT_UNKNOWN` (name not recognised) or
|
|
@@ -131,6 +132,12 @@ Four rules keep the layer honest:
|
|
|
131
132
|
(`powershell -Command "..."`) all become undeterminable facts -> BLOCK.
|
|
132
133
|
`-WhatIf:$true` is a dry run (ALLOW); `-WhatIf:$false` is a real delete;
|
|
133
134
|
a *variable* switch value blocks.
|
|
135
|
+
* **Known destructive vocabulary cannot disappear on a dialect mismatch.**
|
|
136
|
+
The selected tokenizer defines command boundaries. If one of those
|
|
137
|
+
segments contains a supported destructive command shape but its dialect
|
|
138
|
+
classifier produced no operation, Core emits a target-free `UNKNOWN` fact
|
|
139
|
+
and blocks. It never reuses targets or flags guessed under another shell
|
|
140
|
+
grammar, and it does not scan ordinary argument text for dangerous words.
|
|
134
141
|
* **Abbreviations expand only when unambiguous.** PowerShell resolves
|
|
135
142
|
`-r`/`-rec` to `-Recurse` and `-fo` to `-Force`, and the guard follows so
|
|
136
143
|
a recursive forced delete is not read as a mild one. A prefix matching
|
|
@@ -205,16 +212,24 @@ order of value:
|
|
|
205
212
|
alias subset, `-WhatIf`/`-Recurse`/`-Force`/`-Confirm` semantics, and
|
|
206
213
|
fail-closed handling of variables, subexpressions, piped target sets
|
|
207
214
|
and nested hosts. Unit-tested on Linux CI; POSIX stays the default
|
|
208
|
-
|
|
215
|
+
lexical grammar. Since `0.2.3-rc1`, the shared safety floor can turn a
|
|
216
|
+
previously invisible cross-vocabulary mismatch into a target-free
|
|
217
|
+
refusal without guessing another shell's targets.
|
|
209
218
|
- **Phase 2 (done at the pure-logic/adapter-test level).** Differential
|
|
210
219
|
and regression suites (`tests/test_dialects.py`,
|
|
211
220
|
`tests/test_dialect_phase2.py`) cover further cmd/PowerShell spellings,
|
|
212
221
|
option aliases and fail-closed edge cases. Hook payload dialect forwarding
|
|
213
222
|
has adapter tests; this is not a Windows host execution claim.
|
|
214
|
-
- **Phase
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
223
|
+
- **Phase 3a (`0.2.3-rc1` candidate).** A blocking `windows-latest` Core
|
|
224
|
+
job covers the Issue #7 dialect-mismatch and separator regressions,
|
|
225
|
+
deterministic cmd/PowerShell facts, and recovery inside disposable
|
|
226
|
+
fixtures. The job uses Python argv/bytes so a surrounding shell cannot
|
|
227
|
+
rewrite the evidence.
|
|
228
|
+
- **Phase 3 remains incomplete.** Real cmd/PowerShell execution through
|
|
229
|
+
each harness, host-selected dialect wiring, privileged symlink cases,
|
|
230
|
+
broader UNC/device paths and full-suite portability still require
|
|
231
|
+
separate evidence. A focused Core runner is not a universal Windows E2E
|
|
232
|
+
claim.
|
|
218
233
|
- V2: `git-guard` skill (remote ref protection with lease semantics);
|
|
219
234
|
adapter hardening (host-side mode storage, tamper-evident audit).
|
|
220
235
|
- V3+: `database-guard` (compensations = transaction / backup /
|
package/docs/compatibility.md
CHANGED
|
@@ -37,11 +37,11 @@ While the major version is `0`:
|
|
|
37
37
|
|
|
38
38
|
| Surface | Class | Notes |
|
|
39
39
|
|---|---|---|
|
|
40
|
-
| Command dialects (`cmd`, `powershell`) | minor | `classify_command(cmd, dialect=...)`; the default stays `posix
|
|
40
|
+
| Command dialects (`cmd`, `powershell`) | minor | `classify_command(cmd, dialect=...)`; the default lexical grammar stays `posix` |
|
|
41
41
|
| `core/dialects.py` module + `TokenStream` | minor | Internal-but-documented; used by the dialect unit tests |
|
|
42
42
|
| `OpSpec.dialect` field | minor | New field; unknown fields stay opaque to consumers |
|
|
43
43
|
| `Ask` on PowerShell `-WhatIf` | minor | A dry run is an `ALLOW_NOOP`; a real delete keeps existing rules |
|
|
44
|
-
| `check.py --dialect` flag | minor | Defaults to
|
|
44
|
+
| `check.py --dialect` flag | minor | Defaults to the POSIX lexical grammar; later safety releases may newly block a previously invisible known destructive vocabulary mismatch |
|
|
45
45
|
| `AGENT_GUARD_DIALECT` env var | minor | Read by `check.py` and the native shell adapters; unset means `posix` |
|
|
46
46
|
| `BLOCK_DIALECT_UNKNOWN` / `BLOCK_DIALECT_INVALID` | minor | New reason codes (additive) |
|
|
47
47
|
| `BLOCK_PROTECTED_ANCESTOR` | minor | New reason code (additive). Filesystem roots (`/`, `/home`, `/usr`, `$HOME`, ...) are refused by identity rather than by falling outside the workspace |
|
|
@@ -54,6 +54,7 @@ While the major version is `0`:
|
|
|
54
54
|
| `.agent-guard/exfil-allow.toml` exemption file | minor | Read from the workspace root only; values exempted by `sha256:...`, never by value |
|
|
55
55
|
| `doctor.py --check-drift` report and adapter `compatibility.json` profiles | minor | Additive local preflight. Without drift flags the doctor keeps its previous process-execution and exit behavior; `CURRENT` never promotes live interception above `UNVERIFIED` |
|
|
56
56
|
| `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
|
|
57
|
+
| Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
|
|
57
58
|
|
|
58
59
|
### 0.2.0 check output minimization
|
|
59
60
|
|
|
@@ -84,9 +85,13 @@ unknown selector must produce a Decision Protocol verdict with a reason
|
|
|
84
85
|
code; a usage error carries none, and a harness could read "no decision" as
|
|
85
86
|
"nothing to worry about".
|
|
86
87
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
88
|
+
`0.2.3-rc1` adds a focused real-Windows Core gate for dialect mismatch,
|
|
89
|
+
separator normalization, disposable-fixture recovery and exact-byte path
|
|
90
|
+
redaction. It also makes known destructive vocabulary fail closed when it
|
|
91
|
+
does not match the configured dialect. This is only Phase 3a: native
|
|
92
|
+
cmd/PowerShell execution through each harness, hook-selected dialect wiring,
|
|
93
|
+
broader UNC/device paths, module auto-loading and full-suite Windows
|
|
94
|
+
portability remain unverified.
|
|
90
95
|
|
|
91
96
|
### PowerShell parameter prefixes
|
|
92
97
|
|
package/docs/friction.md
CHANGED
|
@@ -264,3 +264,26 @@ without data is still a legitimately empty payload (ALLOW, since nothing
|
|
|
264
264
|
can leak); and on platforms where stdin is not selectable the code falls
|
|
265
265
|
back to the blocking read rather than refusing a caller whose payload may
|
|
266
266
|
be perfectly good.
|
|
267
|
+
|
|
268
|
+
## F16 · A selected shell dialect could erase a known hazard
|
|
269
|
+
|
|
270
|
+
The dialect selector chose both a tokenizer and its recognized command
|
|
271
|
+
vocabulary. That made a configuration mismatch asymmetric: `rm -rf .`
|
|
272
|
+
was a protected-root refusal under POSIX, but the cmd classifier returned no
|
|
273
|
+
operation and policy reported `ALLOW_NOOP`. A mixed line was worse: one
|
|
274
|
+
recognized Windows delete could make the result look guarded while a later
|
|
275
|
+
POSIX delete segment remained invisible. Separately, Windows-native targets
|
|
276
|
+
kept backslashes only when Core itself ran on Windows, so identical command
|
|
277
|
+
text produced host-dependent path facts.
|
|
278
|
+
|
|
279
|
+
**Fixed in `0.2.3-rc1`:** the selected tokenizer still owns command
|
|
280
|
+
boundaries and quoting semantics, but every resulting segment also passes a
|
|
281
|
+
small, shared destructive-vocabulary floor. A known delete, destructive Git
|
|
282
|
+
shape, or `find -delete` shape that its selected classifier did not resolve
|
|
283
|
+
becomes target-free `UNKNOWN` and therefore
|
|
284
|
+
`BLOCK_UNDETERMINABLE_EFFECT`. Core never re-parses the segment under a
|
|
285
|
+
different grammar and never invents a compensation target. Recognized
|
|
286
|
+
Windows delete targets are normalized after their own tokenizer on every
|
|
287
|
+
host, removing the OS-dependent fact split. Negative tests pin quoted output
|
|
288
|
+
and shell-specific literal syntax so the safety floor does not become a
|
|
289
|
+
substring blacklist.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Agent Guard 0.2.3-rc1 — Windows Core fail-closed candidate
|
|
2
|
+
|
|
3
|
+
These notes describe the `0.2.3-rc1` source candidate. A version in the
|
|
4
|
+
repository is not proof that its tag, GitHub prerelease, or npm package has
|
|
5
|
+
been published. The latest stable npm installation remains `0.2.2` unless the
|
|
6
|
+
registry says otherwise.
|
|
7
|
+
|
|
8
|
+
## Issue #7: two confirmed Core fixes
|
|
9
|
+
|
|
10
|
+
[Issue #7](https://github.com/mokuyoaxis/agent-guard/issues/7) reported two
|
|
11
|
+
fail-open paths from a Windows 11 CLI run. The runner was WorkBuddy, but every
|
|
12
|
+
reproduction called Core directly; these were not adapter findings.
|
|
13
|
+
|
|
14
|
+
1. A known destructive command could disappear when its vocabulary did not
|
|
15
|
+
match the configured dialect. In particular, `rm -rf .` changed from
|
|
16
|
+
`BLOCK_PROTECTED_PATH` under POSIX to `ALLOW_NOOP` under `cmd`.
|
|
17
|
+
2. Windows-native delete targets kept or lost backslashes according to the OS
|
|
18
|
+
running the classifier. On Windows, `del build\o.js` could become either
|
|
19
|
+
`buildo.js` or a host-specific target fact and fall through as a no-op.
|
|
20
|
+
|
|
21
|
+
The classifier now treats the selected dialect's command segmentation as the
|
|
22
|
+
authoritative boundary, then checks every segment for known destructive
|
|
23
|
+
vocabulary that produced no operation. A mismatch becomes a target-free,
|
|
24
|
+
non-compensable `UNKNOWN` fact and therefore
|
|
25
|
+
`BLOCK_UNDETERMINABLE_EFFECT`. It does not borrow targets or flags from a
|
|
26
|
+
different shell grammar. Mixed lines are checked segment by segment, so an
|
|
27
|
+
earlier recognized delete cannot hide a later mismatch.
|
|
28
|
+
|
|
29
|
+
This safety floor covers the existing filesystem-delete vocabulary and the
|
|
30
|
+
already supported destructive Git/`find -delete` shapes. It does not block
|
|
31
|
+
all unknown commands. Negative regressions keep ordinary `echo`,
|
|
32
|
+
`Write-Host`, `git status`, quoted command text and cmd-literal `$()` forms
|
|
33
|
+
quiet.
|
|
34
|
+
|
|
35
|
+
Windows-native delete targets are now normalized to `/` after their own
|
|
36
|
+
tokenizer has identified them, on every host OS. The default POSIX bridge
|
|
37
|
+
performs the same rewrite only for its existing standalone Windows-verb
|
|
38
|
+
compatibility path. Normal POSIX escape semantics such as `rm a\ b` are not
|
|
39
|
+
globally rewritten.
|
|
40
|
+
|
|
41
|
+
## Withdrawn exfil report
|
|
42
|
+
|
|
43
|
+
The issue's third finding was withdrawn by its reporter after an exact-byte
|
|
44
|
+
rerun. Git Bash `printf` had changed the backslashes and newline before the
|
|
45
|
+
payload reached `check_span.py`. Python `subprocess` input confirmed that
|
|
46
|
+
native, forward-slash, mixed-separator and UNC Windows absolute paths were
|
|
47
|
+
already classified and sanitized correctly.
|
|
48
|
+
|
|
49
|
+
This candidate does not change `core/redaction.py` or expand exfil policy. It
|
|
50
|
+
adds a regression that constructs the native Windows path in Python, supplies
|
|
51
|
+
matching `USERPROFILE`/`USERNAME` markers, and requires
|
|
52
|
+
`SANITIZE_PATH_REWRITE` without reproducing the matched bytes in output.
|
|
53
|
+
|
|
54
|
+
## Focused Windows CI
|
|
55
|
+
|
|
56
|
+
CI now includes a blocking `windows-latest` / Python 3.13 Core job. It runs
|
|
57
|
+
the cmd/PowerShell dialect suite, the two Issue #7 CLI regressions, a safe
|
|
58
|
+
temporary-directory relocate/restore round trip, and the exact-byte exfil
|
|
59
|
+
regression. Test inputs are passed by Python rather than shell `printf` or
|
|
60
|
+
`echo`, so Git Bash cannot silently rewrite them. The existing Linux/macOS
|
|
61
|
+
matrix continues to run the full suite.
|
|
62
|
+
|
|
63
|
+
A passing run is bounded real-Windows evidence for the listed Core paths,
|
|
64
|
+
not completion of the entire Windows roadmap. It does not prove native
|
|
65
|
+
cmd/PowerShell execution by every harness, hook-selected dialect wiring,
|
|
66
|
+
privileged symlink behavior, all UNC/device paths, or full-suite portability.
|
|
67
|
+
|
|
68
|
+
## Prerelease publishing
|
|
69
|
+
|
|
70
|
+
The release workflow now accepts the project's exact `X.Y.Z-rcN` tag shape in
|
|
71
|
+
addition to stable `X.Y.Z` tags. A tested channel classifier routes RCs to a
|
|
72
|
+
GitHub prerelease and npm's `rc` dist-tag; stable versions use `latest`. The
|
|
73
|
+
tag and `package.json` version must still match exactly, and GitHub Release
|
|
74
|
+
plus npm still receive the same packed tarball with provenance.
|
|
75
|
+
|
|
76
|
+
If published, install this candidate explicitly as
|
|
77
|
+
`@mokuyoaxis/agent-guard@0.2.3-rc1` or through
|
|
78
|
+
`@mokuyoaxis/agent-guard@rc`. An RC publication must not move npm `latest`
|
|
79
|
+
away from `0.2.2`.
|
|
80
|
+
|
|
81
|
+
## Verification and limits
|
|
82
|
+
|
|
83
|
+
The local candidate gate passes 450 Python tests plus the DSH adapter smoke
|
|
84
|
+
test. [GitHub Actions run 36366616252](https://github.com/mokuyoaxis/agent-guard/actions/runs/36366616252)
|
|
85
|
+
passed all 12 jobs for implementation commit `7b83649`, including the focused
|
|
86
|
+
Windows Core gate on `windows-latest` / Python 3.13. This is the bounded
|
|
87
|
+
evidence described above, not a universal Windows-harness claim. No tag,
|
|
88
|
+
GitHub prerelease, npm publication, or Issue closure is implied by these
|
|
89
|
+
notes.
|
|
90
|
+
|
|
91
|
+
`guard-lab` is not included in `0.2.3-rc1`. It remains planned for the next
|
|
92
|
+
available 0.2.3 candidate after the Windows fix is stable.
|
|
@@ -104,7 +104,7 @@ relocations and restores succeed end-to-end.
|
|
|
104
104
|
fixture now spells the path with forward slashes, matching what the shell
|
|
105
105
|
would actually see on this platform.
|
|
106
106
|
|
|
107
|
-
### Verified non-issue
|
|
107
|
+
### Verified non-issue within the tested Git Bash `rm` path
|
|
108
108
|
|
|
109
109
|
`rm -rf C:\...\build` (unquoted, unquoted-backslash) classifies as
|
|
110
110
|
`ALLOW_NOOP` because `shlex` posix-tokenization strips the backslashes — the
|
|
@@ -114,6 +114,13 @@ and shell therefore agree on the effective target, and no fail-open gap exists
|
|
|
114
114
|
on this harness. Quoted and forward-slash spellings — the forms that do delete
|
|
115
115
|
— classify correctly (`RELOCATE_TREE`).
|
|
116
116
|
|
|
117
|
+
This conclusion is deliberately limited to POSIX `rm` under the tested Git
|
|
118
|
+
Bash execution path. It does not cover Windows-native `del`/`rd`/
|
|
119
|
+
`Remove-Item`, where a backslash is a separator rather than an escape.
|
|
120
|
+
Issue #7 later demonstrated that those target facts varied by host OS;
|
|
121
|
+
`0.2.3-rc1` normalizes recognized Windows-native targets independently of the
|
|
122
|
+
machine running Core and pins them in a focused Windows CI job.
|
|
123
|
+
|
|
117
124
|
### ZCode integration properties (harness, not agent-guard)
|
|
118
125
|
|
|
119
126
|
- **Project hooks load at session start and require workspace trust.** The
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3-rc1",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: reversible destructive actions, pre-emission redaction, recovery evidence, and a shared Decision Protocol with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./adapters/dsh/lib/index.js",
|