@mokuyoaxis/agent-guard 0.2.5-rc2 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +24 -0
- package/README.md +52 -18
- package/README.zh-CN.md +46 -15
- package/SECURITY.md +18 -10
- package/adapters/dsh/README.md +39 -6
- package/adapters/dsh/harness/README.md +5 -0
- package/adapters/dsh/harness/guard_lab.py +3 -2
- package/adapters/dsh/lib/index.js +127 -33
- package/adapters/kimi-code/harness/README.md +5 -0
- package/core/lab.py +5 -2
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +29 -8
- package/docs/design/architecture.md +9 -5
- package/docs/design/compatibility.md +43 -3
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +28 -12
- package/docs/guides/harness-capabilities.md +9 -2
- package/docs/guides/recovery-feedback.md +98 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +45 -0
- package/docs/lab/examples/blue-team-calibration.py +53 -0
- package/docs/lab/guard-lab.md +12 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +82 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/docs/reports/blue-team-lab-2026-10.md +73 -0
- package/docs/research/README.md +41 -0
- package/docs/research/content-authorization.md +54 -0
- package/docs/research/dataflow-observability.md +48 -0
- package/docs/research/delegation-provenance.md +56 -0
- package/docs/research/evaluation-method.md +51 -0
- package/docs/research/lab-observations-2026-10.json +43 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +31 -14
- package/skills/delete-guard/references/policy.md +20 -6
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
- package/skills/exfil-guard/references/rules.md +2 -2
package/CONTRIBUTING.md
CHANGED
|
@@ -57,6 +57,20 @@ Review, merge, tagging, GitHub Release, and npm publication are separate
|
|
|
57
57
|
maintainer decisions. Acceptance of a contribution does not promise a specific
|
|
58
58
|
release date.
|
|
59
59
|
|
|
60
|
+
### Defensive research and reproductions
|
|
61
|
+
|
|
62
|
+
Lab develops through small, bounded experiments. Forks, PRs, method reviews
|
|
63
|
+
and independent reproductions are welcome, without a promised experiment or
|
|
64
|
+
release cadence. Public research focuses on defensive controls, provenance,
|
|
65
|
+
task utility and evidence limits. Share synthetic, sanitized observations;
|
|
66
|
+
coordinate sensitive details privately before posting executable adversarial
|
|
67
|
+
payloads or raw captures.
|
|
68
|
+
|
|
69
|
+
Include the code/host versions, declared model configuration, input/task,
|
|
70
|
+
budget, control conditions and observed channels. Report authorization,
|
|
71
|
+
task completion and evidence health separately, retaining failed and
|
|
72
|
+
inconclusive trials. See the [research index](docs/research/README.md).
|
|
73
|
+
|
|
60
74
|
## 中文
|
|
61
75
|
|
|
62
76
|
### 先发 Issue
|
|
@@ -99,3 +113,13 @@ Core/CLI、模拟宿主还是真实宿主。模拟测试通过不能写成所有
|
|
|
99
113
|
|
|
100
114
|
审阅、合并、标签、GitHub Release 与 npm 发布是维护者分别作出的决定;贡献被
|
|
101
115
|
接受不代表承诺在某个版本或日期发布。
|
|
116
|
+
|
|
117
|
+
### 防守研究与独立复现
|
|
118
|
+
|
|
119
|
+
Lab 将按小规模、明确范围逐步推进,欢迎 fork、PR、方法评审与独立复现,
|
|
120
|
+
不承诺固定实验频率或发布时间。公开研究重点是防护、来源、正常任务效用和证据边界。
|
|
121
|
+
分享合成、去敏后的观察;可执行诱导载荷、敏感复现细节与原始捕获先私下协调。
|
|
122
|
+
|
|
123
|
+
注明代码/宿主版本、客户端声明的模型配置、输入/任务、预算、对照条件和观察信道。
|
|
124
|
+
分别报告授权遵守、任务完成和证据健康,保留失败及未定试次。
|
|
125
|
+
方法与公开示例见[研究导航](docs/research/README.md)。
|
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
|
-
[](docs/releases/release-notes-0.2.5.md)
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -65,6 +65,23 @@ external transfer or model request. Existing
|
|
|
65
65
|
[DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
|
|
66
66
|
results, failures and review states.
|
|
67
67
|
|
|
68
|
+
Since RC3, the package includes [blue-team research](docs/research/README.md), a
|
|
69
|
+
[sanitized experiment report](docs/reports/blue-team-lab-2026-10.md) and a
|
|
70
|
+
[portable four-control example](docs/lab/blue-team-calibration.md).
|
|
71
|
+
The research covers provenance, disclosure permissions and task utility in
|
|
72
|
+
bounded private experiments; those methods do not extend production hook
|
|
73
|
+
coverage. Lab proceeds gradually. Forks, PRs and independent defensive
|
|
74
|
+
reproductions are welcome; preserve failed and inconclusive results.
|
|
75
|
+
|
|
76
|
+
From a checkout or package containing the example, run all four existing controls:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
blue_run="$(mktemp -d)"
|
|
80
|
+
python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
This example calls no model; its summary describes instrument calibration.
|
|
84
|
+
|
|
68
85
|
<a id="quick-start-with-your-coding-agent"></a>
|
|
69
86
|
|
|
70
87
|
## Install and choose a version
|
|
@@ -74,14 +91,19 @@ native bridges and optional capture helpers have their own requirements.
|
|
|
74
91
|
|
|
75
92
|
| Version | Status |
|
|
76
93
|
|---|---|
|
|
77
|
-
| [0.2.
|
|
78
|
-
| [0.2.
|
|
79
|
-
| [0.2.
|
|
94
|
+
| [0.2.5](docs/releases/release-notes-0.2.5.md) | Stable release line; npm `latest`; availability in the versioned receipts below |
|
|
95
|
+
| [0.2.4](docs/releases/release-notes-0.2.4.md) | Previous stable release |
|
|
96
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | Opt-in quarantine protection backport; npm `hotfix` |
|
|
97
|
+
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
|
|
98
|
+
Publication is established by the exact
|
|
99
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
100
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5).
|
|
101
|
+
A checkout or manifest alone does not establish package availability.
|
|
80
102
|
|
|
81
|
-
For the
|
|
103
|
+
For the stable release, use a chosen, stable user-owned prefix:
|
|
82
104
|
|
|
83
105
|
```sh
|
|
84
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
106
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
|
|
85
107
|
```
|
|
86
108
|
|
|
87
109
|
The package root is
|
|
@@ -93,12 +115,16 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
|
93
115
|
cd agent-guard
|
|
94
116
|
```
|
|
95
117
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
[
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
118
|
+
To select the published prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3`.
|
|
119
|
+
The [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
|
|
120
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
|
|
121
|
+
identify that package. For only the stable-line quarantine protection fix,
|
|
122
|
+
select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
|
|
123
|
+
replaces stable `latest`.
|
|
124
|
+
|
|
125
|
+
Version 0.2.5 combines RC1–RC3 with clearer startup, command and storage
|
|
126
|
+
feedback. A reviewed local checkout or supplied tarball is also usable. See
|
|
127
|
+
[release notes](docs/releases/release-notes-0.2.5.md) and
|
|
102
128
|
[setup and the agent setup prompt](docs/guides/getting-started.md).
|
|
103
129
|
|
|
104
130
|
## Recover a supported deletion
|
|
@@ -109,7 +135,7 @@ From the workspace being protected, point at your package/checkout root:
|
|
|
109
135
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
|
|
110
136
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
111
137
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
|
|
112
|
-
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
|
|
138
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
113
139
|
```
|
|
114
140
|
|
|
115
141
|
Valuable targets are relocated with exact recovery paths in a manifest.
|
|
@@ -119,6 +145,11 @@ untracked/ignored content are refused. Force restore preserves the current
|
|
|
119
145
|
occupant before replacement. Errors can leave partial work: inspect the
|
|
120
146
|
reported transaction IDs, filesystem and state before retrying.
|
|
121
147
|
|
|
148
|
+
Version 0.2.5 makes these results explicit:
|
|
149
|
+
quarantined data still occupies storage, GC is manual, and `ALLOW_NOOP`
|
|
150
|
+
does not certify unrecognized command effects. Local status does not prove
|
|
151
|
+
that a host loaded the guard. See [status and cleanup feedback](docs/guides/recovery-feedback.md).
|
|
152
|
+
|
|
122
153
|
Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
|
|
123
154
|
may write quarantine/audit metadata and a Git local exclude entry. Advisory
|
|
124
155
|
exit 0 is not permission to execute a BLOCK or ASK.
|
|
@@ -126,10 +157,11 @@ See the [policy and assessment contract](skills/delete-guard/references/policy.m
|
|
|
126
157
|
|
|
127
158
|
RC1 added quarantine control-path protection, excluded PURGED transactions
|
|
128
159
|
from active GC planning, and minimized restore/safe_delete audit fields.
|
|
129
|
-
Exact CLI/manifest recovery paths remain available.
|
|
130
|
-
|
|
160
|
+
Exact CLI/manifest recovery paths remain available. The original 0.2.4 package
|
|
161
|
+
lacks these changes; 0.2.4-hotfix.1 backports only quarantine control-path
|
|
162
|
+
protection. See the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
|
|
131
163
|
|
|
132
|
-
|
|
164
|
+
RC2 introduced shared audit metadata projection,
|
|
133
165
|
uses opaque session correlation, and limits legacy status/GC metadata.
|
|
134
166
|
See the [audit contract and remaining boundaries](docs/guides/audit-metadata.md).
|
|
135
167
|
It adds observer startup diagnostics and correct cancellation accounting;
|
|
@@ -211,13 +243,15 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
|
|
|
211
243
|
| [Architecture](docs/design/architecture.md) | Shared Core, compensation and adapter flow |
|
|
212
244
|
| [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
|
|
213
245
|
| [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
|
|
214
|
-
| [
|
|
246
|
+
| [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
|
|
247
|
+
| [0.2.5 notes](docs/releases/release-notes-0.2.5.md) | Release scope, upgrade impact and validation boundaries |
|
|
215
248
|
|
|
216
249
|
## Contributing
|
|
217
250
|
|
|
218
251
|
Bug reports, compatibility evidence, documentation fixes and focused code
|
|
219
252
|
changes are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before sharing
|
|
220
|
-
logs. Use
|
|
253
|
+
defensive research, independent reproductions or logs. Use
|
|
254
|
+
[Issues](https://github.com/mokuyoaxis/agent-guard/issues) and
|
|
221
255
|
[Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls); keep credentials,
|
|
222
256
|
private configuration and unredacted incident records out of public reports.
|
|
223
257
|
|
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
|
-
[](docs/releases/release-notes-0.2.5.md)
|
|
8
8
|
|
|
9
9
|
**让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
|
|
10
10
|
|
|
@@ -56,6 +56,21 @@ harness/版本/模型、任务、协议及非防护配置。结果只覆盖
|
|
|
56
56
|
[DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
|
|
57
57
|
失败和待审状态。
|
|
58
58
|
|
|
59
|
+
自 RC3 起,包中包含[蓝队研究](docs/research/README.md)、
|
|
60
|
+
[去敏实验报告](docs/reports/blue-team-lab-2026-10.md)和
|
|
61
|
+
[便携四控制示例](docs/lab/blue-team-calibration.md),公开来源、发送授权和正常任务效用的
|
|
62
|
+
有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进,欢迎 fork、PR
|
|
63
|
+
与独立防守复现;失败和未定结果也应保留。
|
|
64
|
+
|
|
65
|
+
在包含该示例的源码或包根目录,可一次运行现有四种控制:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
blue_run="$(mktemp -d)"
|
|
69
|
+
python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
示例不调用模型,摘要只用于仪器校准。
|
|
73
|
+
|
|
59
74
|
## 安装与版本选择
|
|
60
75
|
|
|
61
76
|
Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可选采集
|
|
@@ -63,14 +78,19 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
63
78
|
|
|
64
79
|
| 版本 | 状态 |
|
|
65
80
|
|---|---|
|
|
66
|
-
| [0.2.
|
|
67
|
-
| [0.2.
|
|
68
|
-
| [0.2.
|
|
81
|
+
| [0.2.5](docs/releases/release-notes-0.2.5.md) | 正式版;npm `latest`;实际可用性见下方版本化回执 |
|
|
82
|
+
| [0.2.4](docs/releases/release-notes-0.2.4.md) | 上一稳定版 |
|
|
83
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
|
|
84
|
+
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
|
|
85
|
+
实际发布状态以精确版本的
|
|
86
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)和
|
|
87
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)为准,
|
|
88
|
+
checkout 或 manifest 本身不代表包已可安装。
|
|
69
89
|
|
|
70
90
|
稳定包可安装到用户选定的长期目录:
|
|
71
91
|
|
|
72
92
|
```sh
|
|
73
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
93
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
|
|
74
94
|
```
|
|
75
95
|
|
|
76
96
|
包根目录是
|
|
@@ -82,11 +102,16 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
|
82
102
|
cd agent-guard
|
|
83
103
|
```
|
|
84
104
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
105
|
+
选用已发布的预发布版时,指定 `@mokuyoaxis/agent-guard@0.2.5-rc3`,对应
|
|
106
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)与
|
|
107
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)。
|
|
108
|
+
若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
|
|
109
|
+
这两个通道均不替换稳定版 `latest`。
|
|
110
|
+
|
|
111
|
+
0.2.5 汇合 RC1—RC3,并明确启动、命令与空间占用反馈,
|
|
112
|
+
也可使用已核查的 checkout 或提供的 tarball。
|
|
113
|
+
范围见[发布说明](docs/releases/release-notes-0.2.5.md),接入步骤与 Agent 提示词见
|
|
114
|
+
[入门指南](docs/guides/getting-started.md)。
|
|
90
115
|
|
|
91
116
|
## 恢复一次受支持的删除
|
|
92
117
|
|
|
@@ -96,7 +121,7 @@ RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定
|
|
|
96
121
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
|
|
97
122
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
98
123
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
|
|
99
|
-
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
|
|
124
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
100
125
|
```
|
|
101
126
|
|
|
102
127
|
有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被
|
|
@@ -105,15 +130,20 @@ hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force res
|
|
|
105
130
|
先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的
|
|
106
131
|
事务 ID、现场文件和状态,再决定后续动作。
|
|
107
132
|
|
|
133
|
+
0.2.5 明确提示:迁入回收站的数据仍占空间,
|
|
134
|
+
GC 需要显式执行,`ALLOW_NOOP` 不代表未识别命令没有破坏性。
|
|
135
|
+
本地状态查询也不能证明宿主已加载防护。见[状态与清理反馈](docs/guides/recovery-feedback.md)。
|
|
136
|
+
|
|
108
137
|
advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,但可能写入
|
|
109
138
|
隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
|
|
110
139
|
操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
|
|
111
140
|
|
|
112
141
|
RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
|
|
113
142
|
restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
|
|
114
|
-
|
|
143
|
+
原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。
|
|
144
|
+
见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
|
|
115
145
|
|
|
116
|
-
RC2
|
|
146
|
+
RC2 进一步限定通用审计字段、使用不透明 session 关联,
|
|
117
147
|
并收口旧日志 status 展示与 GC 元信息,见[审计契约及保留边界](docs/guides/audit-metadata.md)。
|
|
118
148
|
同时补充 observer 启动诊断与取消健康记账;最初偶发超时的具体原因仍未知,
|
|
119
149
|
见 [RC2 范围与证据](docs/releases/release-notes-0.2.5-rc2.md)。
|
|
@@ -184,11 +214,12 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
|
|
|
184
214
|
| [架构](docs/design/architecture.md) | 共享 Core、补偿与适配器数据流 |
|
|
185
215
|
| [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
|
|
186
216
|
| [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
|
|
187
|
-
| [
|
|
217
|
+
| [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
|
|
218
|
+
| [0.2.5 说明](docs/releases/release-notes-0.2.5.md) | 发布范围、升级影响与验证边界 |
|
|
188
219
|
|
|
189
220
|
## 参与贡献
|
|
190
221
|
|
|
191
|
-
|
|
222
|
+
欢迎 fork、PR、独立防守复现、缺陷报告、兼容性证据和文档修订。分享研究资料或日志前阅读
|
|
192
223
|
[CONTRIBUTING.md](CONTRIBUTING.md),通过
|
|
193
224
|
[Issues](https://github.com/mokuyoaxis/agent-guard/issues) 和
|
|
194
225
|
[Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls)参与;
|
package/SECURITY.md
CHANGED
|
@@ -3,13 +3,15 @@
|
|
|
3
3
|
## Reporting
|
|
4
4
|
|
|
5
5
|
Open a GitHub issue for non-sensitive issues, or contact the maintainer
|
|
6
|
-
directly for anything you believe is exploitable.
|
|
7
|
-
verdict
|
|
6
|
+
directly for anything you believe is exploitable. Include the minimal
|
|
7
|
+
sanitized verdict/audit metadata needed to explain it, using synthetic data
|
|
8
|
+
where possible. See [CONTRIBUTING.md](CONTRIBUTING.md) before sharing captures.
|
|
8
9
|
|
|
9
10
|
## What agent-guard claims to be
|
|
10
11
|
|
|
11
|
-
Reliability infrastructure: it
|
|
12
|
-
|
|
12
|
+
Reliability infrastructure: it provides recovery for supported destructive
|
|
13
|
+
actions and records evidence under the documented audit contracts. It is
|
|
14
|
+
**not a security sandbox** - an agent
|
|
13
15
|
with the same OS privileges as the guard can bypass it. See
|
|
14
16
|
[docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
|
|
15
17
|
|
|
@@ -27,10 +29,10 @@ will therefore report hits such as:
|
|
|
27
29
|
- credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
|
|
28
30
|
(a guide about *avoiding* credential leaks).
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
A historical v0.1.0 self-scan reported 61 hits (29 high / 10 medium / 22 low).
|
|
33
|
+
That count is a dated checkpoint, not a current runtime-reachability audit.
|
|
34
|
+
Review the concrete call and its context; report unexpected runtime behavior
|
|
35
|
+
with a minimal, sanitized reproduction.
|
|
34
36
|
|
|
35
37
|
## Data handling
|
|
36
38
|
|
|
@@ -47,7 +49,13 @@ the configured provider through the host and consume quota; they are separate
|
|
|
47
49
|
from local command checks and require a selected experiment scope.
|
|
48
50
|
|
|
49
51
|
Recovery manifests, CLI diagnostics and historical audit records can contain
|
|
50
|
-
exact paths or other private text.
|
|
51
|
-
|
|
52
|
+
exact paths or other private text. Writer minimization introduced in RC1 and
|
|
53
|
+
the shared projection introduced in RC2 remain in 0.2.5;
|
|
54
|
+
they do not make every
|
|
55
|
+
output or old record secret-free. The exfil text
|
|
52
56
|
CLIs return decisions/plans or sanitized stdout; they do not automatically
|
|
53
57
|
persist egress audit events. Review and redact evidence before sharing it.
|
|
58
|
+
|
|
59
|
+
The [public blue-team research](docs/research/README.md) shares sanitized
|
|
60
|
+
methods and aggregate observations. Raw sessions, private configuration and
|
|
61
|
+
reusable induction payloads are not part of those new public materials.
|
package/adapters/dsh/README.md
CHANGED
|
@@ -18,12 +18,12 @@ retains the earlier failures and correction history.
|
|
|
18
18
|
|
|
19
19
|
## Install
|
|
20
20
|
|
|
21
|
-
The [0.2.
|
|
22
|
-
|
|
23
|
-
coverage. Install the exact version:
|
|
21
|
+
The [0.2.5 release](../../docs/releases/release-notes-0.2.5.md) includes the
|
|
22
|
+
startup/status diagnostics below without broadening admitted DSH versions or
|
|
23
|
+
native-read coverage. Install the exact stable version:
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
|
-
dsh plugin --profile
|
|
26
|
+
dsh plugin --profile 'your-profile' add @mokuyoaxis/agent-guard@0.2.5
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
Use an exact package version whose host contract matches your DSH installation.
|
|
@@ -31,17 +31,50 @@ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
|
|
|
31
31
|
Git must already be available. Installation does not enable the optional
|
|
32
32
|
text-read guard.
|
|
33
33
|
|
|
34
|
+
As checked on 2026-10-19, the published opt-in versions are
|
|
35
|
+
`@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
|
|
36
|
+
`@mokuyoaxis/agent-guard@0.2.5-rc3` for the cumulative prerelease.
|
|
37
|
+
Versioned [GitHub](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
38
|
+
and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
|
|
39
|
+
receipts establish 0.2.5 availability. A reviewed checkout or tarball is also
|
|
40
|
+
usable as described in [getting started](../../docs/guides/getting-started.md).
|
|
41
|
+
|
|
34
42
|
## What gets registered
|
|
35
43
|
|
|
36
44
|
| Contribution | Mechanism | Behavior |
|
|
37
45
|
|---|---|---|
|
|
38
|
-
| Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first;
|
|
46
|
+
| Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; permitted calls proceed after any required compensation, ASK uses the host approval path or denies when unavailable, BLOCK denies with explanation and remediation |
|
|
39
47
|
| `agent_guard_safe_delete` | model tool | recoverable delete with explicit glob expansion and manifest |
|
|
40
48
|
| `agent_guard_restore` | model tool | list / non-overwriting restore of quarantine transactions; forced overwrite remains human-only CLI functionality |
|
|
41
|
-
| `agent_guard_status` | model tool | mode, usage, retention view, recent decisions |
|
|
49
|
+
| `agent_guard_status` | model tool | adapter diagnostics, mode, usage, retention view, GC commands and recent decisions; no live-host certification |
|
|
42
50
|
| Prompt section | system prompt (order 105) | deletion discipline for the model |
|
|
43
51
|
| Experimental text `read` redaction | opt-in `tools/post-execute` value replacement | shared Core scans a complete read and DSH regenerates content and presentation metadata; unsupported or unscannable results are withheld |
|
|
44
52
|
|
|
53
|
+
## Startup and status diagnostics
|
|
54
|
+
|
|
55
|
+
Version 0.2.5 runs `python3 check.py --help`
|
|
56
|
+
before contributing the Hook/tools. This tests Python and imports in the
|
|
57
|
+
plugin process, without assessing a command or writing guard metadata.
|
|
58
|
+
Missing dependencies or a failed/timed-out startup check produce an explicit
|
|
59
|
+
initialization error instead of a log-only disabled adapter. The local check
|
|
60
|
+
has a 10-second timeout; the existing command-check timeout remains unchanged.
|
|
61
|
+
|
|
62
|
+
Startup success says that the listener was registered, while live host
|
|
63
|
+
interception remains `UNVERIFIED`. `agent_guard_status.adapter` reports that
|
|
64
|
+
distinction and the most recent checker result. It does not turn a local
|
|
65
|
+
Python test into a check of every shell/sandbox environment. If the plugin
|
|
66
|
+
never loads, its tools may be absent: inspect the host's plugin activation
|
|
67
|
+
status. An initialization error does not stop the host's other tools.
|
|
68
|
+
|
|
69
|
+
Checker process errors, timeout and unusable output remain denials with
|
|
70
|
+
static diagnostics separate from policy refusals. Relocation results state
|
|
71
|
+
that data still occupies storage; status includes accurate GC commands.
|
|
72
|
+
Status-query timeout, unsuccessful exit and unusable reports return `ok: false`
|
|
73
|
+
with a `STATUS_*` diagnostic and adapter facts, without changing the last
|
|
74
|
+
command-checker result. Partial relocation failures retain their recovery IDs
|
|
75
|
+
and storage guidance when files have moved.
|
|
76
|
+
See [status and cleanup feedback](../../docs/guides/recovery-feedback.md).
|
|
77
|
+
|
|
45
78
|
## Configuration (cordis.patch.yml row)
|
|
46
79
|
|
|
47
80
|
| Key | Default | Meaning |
|
|
@@ -6,6 +6,11 @@ host completion explicitly user-declared. No production dependency is added.
|
|
|
6
6
|
The default remains guard-off; the paired workflow below supplies the local
|
|
7
7
|
Guard patch only to guard-on members.
|
|
8
8
|
|
|
9
|
+
For a zero-model starting point, use the [four-control example](../../../docs/lab/blue-team-calibration.md).
|
|
10
|
+
The [defensive research](../../../docs/research/README.md) describes separate
|
|
11
|
+
private provenance/delegation experiments; it does not expand this runner's
|
|
12
|
+
single-root native receipt contract.
|
|
13
|
+
|
|
9
14
|
## Select the runtime
|
|
10
15
|
|
|
11
16
|
Use Node.js 22.23.2 or another runtime with the required native Zstandard APIs.
|
|
@@ -221,7 +221,7 @@ def run_trial(
|
|
|
221
221
|
node_executable: str = "node",
|
|
222
222
|
guard_state: str = "off", guard_patch_file: Optional[Path] = None,
|
|
223
223
|
expected_configuration_sha256: Optional[str] = None,
|
|
224
|
-
*, guard_profile="deletion-v1", dsh_root=None,
|
|
224
|
+
*, guard_profile="deletion-v1", dsh_root=None, _prepare_run=None,
|
|
225
225
|
) -> dict:
|
|
226
226
|
if case_id not in {"clean", "injection-probe"}:
|
|
227
227
|
raise LabError("this runner supports clean and injection-probe only")
|
|
@@ -268,7 +268,8 @@ def run_trial(
|
|
|
268
268
|
"trial_group": trial_group, "task_file": task_file,
|
|
269
269
|
"non_guard_configuration_sha256": preflight["non_guard_configuration_sha256"],
|
|
270
270
|
}
|
|
271
|
-
|
|
271
|
+
# Private experiments can pass a fixture constructor without module patches.
|
|
272
|
+
prepared = (prepare_run if _prepare_run is None else _prepare_run)(
|
|
272
273
|
output / "fixture", output / "evidence", case_id,
|
|
273
274
|
model_usage="real", attack_sample=attack_sample, **metadata,
|
|
274
275
|
)
|