@leeruu/agentguard 0.0.0-stage → 0.1.0
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/LICENSE +202 -0
- package/README.md +297 -2
- package/dist/audit/query.js +151 -0
- package/dist/audit/writer.js +174 -0
- package/dist/cli.js +624 -0
- package/dist/demo.js +246 -0
- package/dist/errors.js +28 -0
- package/dist/format.js +29 -0
- package/dist/limits.js +42 -0
- package/dist/logger.js +46 -0
- package/dist/main.js +239 -0
- package/dist/packs.js +51 -0
- package/dist/policy/bootstrap.js +127 -0
- package/dist/policy/decide.js +41 -0
- package/dist/policy/glob.js +80 -0
- package/dist/policy/load.js +203 -0
- package/dist/policy/match.js +431 -0
- package/dist/policy/types.js +15 -0
- package/dist/proxy.js +440 -0
- package/package.json +59 -4
- package/packs/core.yaml +104 -0
- package/packs/git.yaml +43 -0
- package/packs/net.yaml +48 -0
- package/packs/secrets.yaml +120 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,298 @@
|
|
|
1
|
-
#
|
|
1
|
+
# agentguard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**MCP 工具调用的本地防火墙:一份 YAML 决定 agent 哪些事不许做。**
|
|
4
|
+
|
|
5
|
+
夹在 agent 与真实 MCP server 之间的 stdio 代理。改 MCP 配置里的一行就生效,对 agent 完全透明。
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx -y @leeruu/agentguard@beta demo # 不接任何 agent,直接看拦截效果(内置假 server 跑一遍)
|
|
9
|
+
npx -y @leeruu/agentguard@beta init # 生成 ~/.agentguard/policy.yaml(选策略包)
|
|
10
|
+
npx -y @leeruu/agentguard@beta check # 看它会拦住什么,再决定接不接
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
> 当前是 beta:命令里的 `@beta` 别去掉。正式版转正后这些命令会去掉 `@beta`。
|
|
14
|
+
> `demo` 不需要任何 AI 客户端、不需要配置、不写审计——先看效果再决定装不装。
|
|
15
|
+
|
|
16
|
+
真实文件系统 server 过代理后,agent 侧看到的是:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
读 app.ts → "export const ok = true;\n"
|
|
20
|
+
读 .env → -32001 Blocked by policy secrets-read-env: 敏感凭据文件(.env)
|
|
21
|
+
写 /etc/hosts → -32001 Blocked by policy core-write-system-path: 写入系统目录或凭据目录
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`agentguard audit stats` 按规则聚合每一次判定:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
总计 3 条
|
|
28
|
+
判定 deny 2 / allow 1
|
|
29
|
+
|
|
30
|
+
按规则
|
|
31
|
+
core-write-system-path 1
|
|
32
|
+
secrets-read-env 1
|
|
33
|
+
base-allow-read 1
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## 拦什么
|
|
37
|
+
|
|
38
|
+
四套策略包(27 条规则),`init` 默认装 `core` + `secrets`:
|
|
39
|
+
|
|
40
|
+
| 包 | 覆盖 |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `core` | `rm -rf /`(含 `-r -f` 拆写)、系统目录、强制推送、`DROP TABLE`、`curl … \| sh`、写 `/etc` `~/.ssh`、`mkfs` / `dd of=/dev/` |
|
|
43
|
+
| `secrets` | 读 `.env` 家族(放行 `.env.example`)/ 私钥 / 云凭据、云元数据端点 `169.254.169.254`、把密钥发到 issue / PR / HTTP body |
|
|
44
|
+
| `git` | `reset --hard`、`clean -fdx`、删除远端分支、丢弃工作区改动 |
|
|
45
|
+
| `net` | 内网地址、支付类接口、单窗口调用上限 |
|
|
46
|
+
|
|
47
|
+
18 条攻击用例全部拦截,20 条日常开发操作零误伤(有测试守着,见文末)。
|
|
48
|
+
|
|
49
|
+
## 不做什么
|
|
50
|
+
|
|
51
|
+
| 不做 | 原因 |
|
|
52
|
+
|---|---|
|
|
53
|
+
| 不做 LLM API 网关 / 计费 / 厂商路由 | 我们不看模型流量,只看工具调用 |
|
|
54
|
+
| 不做沙箱 / 容器隔离 | 沙箱要换环境;我们要的是在原环境里加一层规则 |
|
|
55
|
+
| 不检查工具返回值 | 代理只看请求方向。返回值里的密钥泄漏拦不住——这是明确缺口,不假装支持 |
|
|
56
|
+
| 不上云、不注册、不联网 | 策略和审计都在本地磁盘,`grep` 就能查 |
|
|
57
|
+
| 不自动改写客户端配置 | `init` 只生成文件 + 打印片段。改坏 `~/.claude.json` 会连带影响你所有 server |
|
|
58
|
+
|
|
59
|
+
`init` 生成的 JSON 片段自己粘,三家的位置在下面的「客户端配置」里。
|
|
60
|
+
|
|
61
|
+
> 为什么做成这样、它拦不住什么:见仓库里的 `docs/launch-article.md`。
|
|
62
|
+
> (等仓库地址确定、`package.json` 补上 `repository` 之后,这里会换成可点击的链接)
|
|
63
|
+
|
|
64
|
+
> 状态:**W10 完成**(代码、策略包、审计、打包边界、本地 git 基线)。以 `@leeruu/agentguard@beta` 发布中。
|
|
65
|
+
> 源码 2,477 行(14 个文件)+ 319 行策略包 YAML;运行时依赖 1 个(`yaml`);Node ≥ 20。
|
|
66
|
+
|
|
67
|
+
## 现状
|
|
68
|
+
|
|
69
|
+
**W1 · 代理**
|
|
70
|
+
|
|
71
|
+
- stdin/stdout 原样双向转发,四个消息方向全部透传(含 server → client 的 `sampling/createMessage`)
|
|
72
|
+
- 不解析 → 不重新序列化:转发走原始 Buffer,逐字节保真
|
|
73
|
+
- 无行长度上限(2 MiB 单行实测通过)
|
|
74
|
+
- Windows 下 `.cmd` / `.bat` 垫片(`npx`、`pnpm` 等)可按 PATH + PATHEXT 解析启动
|
|
75
|
+
- stdout 只走协议流,诊断全部进 stderr
|
|
76
|
+
|
|
77
|
+
**W2 · 策略引擎**
|
|
78
|
+
|
|
79
|
+
- YAML → strict schema 校验 → 编译,任何一条写错 = 加载失败(不静默忽略)
|
|
80
|
+
- 五种操作符:`glob` / `regex` / `equals` / `in` / `prefix`
|
|
81
|
+
- 判定优先级 `deny > ask > allow`,同档取声明在前的第一条
|
|
82
|
+
- 未命中走 `defaults.on_no_match`,默认 `deny`(fail-closed)
|
|
83
|
+
- `dry_run` 只记录不拦截,审计里仍保留原始判定
|
|
84
|
+
- 多策略文件按顺序合并,规则 id 全局唯一
|
|
85
|
+
- 判定耗时 P99 **0.02ms**(4 条规则)/ **0.9ms**(1000 条规则未命中)
|
|
86
|
+
|
|
87
|
+
**W3 · 拦截路径**
|
|
88
|
+
|
|
89
|
+
- `tools/call` 先判定再转发;`deny` 时用**原 id** 回 `-32001`,upstream 根本收不到这条消息
|
|
90
|
+
- 快速路径:不含 `"tools/call"` 的行完全不解析
|
|
91
|
+
- `ask` 无审批通道时明确拒绝(不静默放行、不阻塞)
|
|
92
|
+
- 上游崩溃:未完成的调用回 `-32603`,client 不会一直等
|
|
93
|
+
- 策略加载失败 → 退出码 2 且上游不会被启动;无策略文件 → deny-all + stderr 告警
|
|
94
|
+
|
|
95
|
+
**W4 · 审计与观察模式**
|
|
96
|
+
|
|
97
|
+
- 每次 `tools/call` 判定落一行 JSONL:`ts / reqId / tool / args / decision / ruleId / reason / ms / session / agent`
|
|
98
|
+
- 按天切分 `~/.agentguard/audit/YYYY-MM-DD.jsonl`,保留 30 天(启动时按文件名清理)
|
|
99
|
+
- 参数深度截断(默认 200 字符),大文件内容不会把日志撑爆
|
|
100
|
+
- `agent` 取自 `initialize` 的 `clientInfo.name`;`session` 每进程 4 位十六进制
|
|
101
|
+
- `dry_run` 与 `ask` 保留 `raw` 字段 —— 观察模式下能看到「本会拦下什么」
|
|
102
|
+
- `limits` 真正执行:超限回 `-32004` 并落审计
|
|
103
|
+
- 写入 0.007ms/条(异步入队),退出前 flush;目录不可写时告警但不阻断转发
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
agentguard audit list --limit 20 --decision deny
|
|
107
|
+
agentguard audit stats --since 7d
|
|
108
|
+
agentguard audit export --format csv
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
环境变量:`AGENTGUARD_AUDIT_DIR`(审计目录)、`AGENTGUARD_AUDIT=off`(关闭)、`AGENTGUARD_AUDIT_KEEP_DAYS`(保留天数)、`AGENTGUARD_LOG=debug|info|warn|error`
|
|
112
|
+
|
|
113
|
+
**W5 · 策略包与 init / check**
|
|
114
|
+
|
|
115
|
+
四套策略包(`packs/`):
|
|
116
|
+
|
|
117
|
+
| 包 | 覆盖 | 默认 |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `core` | rm -rf 根目录/系统目录(含 `-r -f` 拆写)、强制推送、破坏性 SQL、下载即执行、写系统目录、磁盘级破坏 | ✅ |
|
|
120
|
+
| `secrets` | 读 .env 家族(排除 `.example`)/私钥/云凭据、云元数据端点、密钥外发 | ✅ |
|
|
121
|
+
| `git` | reset --hard、clean -fdx、删除远端分支、丢弃工作区改动 | — |
|
|
122
|
+
| `net` | 内网地址、支付接口、单窗口调用上限 | — |
|
|
123
|
+
|
|
124
|
+
- `init` 生成 `~/.agentguard/policy.yaml` + `packs/` 副本,**写盘前会用加载器自校验**生成的文本
|
|
125
|
+
- dev profile 附带基线放行(常见读写/命令工具),否则 fail-closed 会让 agent 一接入就瘫痪;`--profile strict` 关闭基线
|
|
126
|
+
- `--observe` 生成观察模式;`--packs` 选包;`--force` 才覆盖已有策略
|
|
127
|
+
- `check` 打印规则表 + 13 条样例调用的预演结果,让人一眼看懂"它会拦什么"
|
|
128
|
+
|
|
129
|
+
**W7–8 · 测试与加固**
|
|
130
|
+
|
|
131
|
+
- 方案第 9 章的 18 条攻击用例统一出口(`npm run check:attacks`),全部跑在 `init` 生成的真实产物上
|
|
132
|
+
- 压力:8 MiB 单行、1000 次连续调用(往返 p99 1.19ms)、33 条规则判定 p99 0.07ms
|
|
133
|
+
- 编码:CRLF 行尾、行首 UTF-8 BOM、策略文件 BOM+CRLF 全部兼容
|
|
134
|
+
- 正则回溯:加载期体检,识别 `(a+)+` 类嵌套量词并在 stderr 告警;四套策略包零告警(有单测守着)
|
|
135
|
+
- 冷启动计时:init 193ms + check 161ms + 真实 server 首次成功调用 2.9s,合计 3.3s
|
|
136
|
+
|
|
137
|
+
## 用法
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
agentguard [--policy <file>]... -- <真实 mcp server 命令> [参数...]
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
策略来源(优先级从高到低):
|
|
144
|
+
|
|
145
|
+
1. `--policy` 指定的文件(可重复,按顺序合并)
|
|
146
|
+
2. `~/.agentguard/policy.yaml`
|
|
147
|
+
3. 都没有 → 内置 deny-all + stderr 告警(**不会因为没配置就放行**)
|
|
148
|
+
|
|
149
|
+
退出码:`0` 正常 / `1` upstream 启动失败 / `2` 用法或策略配置错误。
|
|
150
|
+
|
|
151
|
+
示例:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npx -y @leeruu/agentguard@beta --policy ~/.agentguard/policy.yaml \
|
|
155
|
+
-- npx -y @modelcontextprotocol/server-filesystem /projects
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**不绑定任何一家 agent。** 只要客户端能用 `command` + `args` 以 stdio 方式启动 MCP server,就能用 agentguard。
|
|
159
|
+
|
|
160
|
+
| 客户端 | 配置位置 |
|
|
161
|
+
|---|---|
|
|
162
|
+
| **Cline**(VS Code,免费,可接 DeepSeek / 通义 / Kimi 等任意模型) | 设置页 → `MCP Servers` → `Edit Config` |
|
|
163
|
+
| **Roo Code**(VS Code) | 同上 |
|
|
164
|
+
| **Cursor** | `~/.cursor/mcp.json` |
|
|
165
|
+
| **Claude Code** | 项目根 `.mcp.json`,或用户级 `~/.claude.json` |
|
|
166
|
+
| 其它(Cherry Studio / Trae / Qoder 等) | 找到 MCP 配置项,结构一样 |
|
|
167
|
+
|
|
168
|
+
**配置结构完全一致**,都是下面这一段:
|
|
169
|
+
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"mcpServers": {
|
|
173
|
+
"filesystem": {
|
|
174
|
+
"command": "npx",
|
|
175
|
+
"args": [
|
|
176
|
+
"-y", "@leeruu/agentguard@beta",
|
|
177
|
+
"--policy", "C:/Users/me/.agentguard/policy.yaml",
|
|
178
|
+
"--",
|
|
179
|
+
"npx", "-y", "@modelcontextprotocol/server-filesystem", "/projects"
|
|
180
|
+
]
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
三个要点:
|
|
187
|
+
|
|
188
|
+
1. `--` 之前是 agentguard 的选项,之后是**原来那行 server 命令**,原样搬过来即可。
|
|
189
|
+
2. `--policy` 用**绝对路径**。Windows 上 JSON 里写正斜杠(`C:/Users/...`)最省事,写反斜杠要双写。
|
|
190
|
+
3. 想给多个 server 都套上,就把每个 server 的 `command`/`args` 各包一层——它们互不影响。
|
|
191
|
+
|
|
192
|
+
被拦时 agent 侧看到的是明确错误,不是卡住:
|
|
193
|
+
|
|
194
|
+
```
|
|
195
|
+
{"jsonrpc":"2.0","id":7,"error":{"code":-32001,
|
|
196
|
+
"message":"Blocked by policy secrets-read-env: 敏感凭据文件(.env)",
|
|
197
|
+
"data":{"ruleId":"secrets-read-env","reason":"敏感凭据文件(.env)","decision":"deny","dryRun":false}}}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## 接入排障
|
|
201
|
+
|
|
202
|
+
| 现象 | 先查什么 |
|
|
203
|
+
|---|---|
|
|
204
|
+
| 所有工具调用都被拒 | 没加载到策略,或规则没覆盖这个工具。跑 `agentguard check --policy <你的文件>` 看预演;确认 `--policy` 路径是绝对路径且存在 |
|
|
205
|
+
| 客户端显示 server 连不上 | 看客户端日志里 agentguard 的 stderr。策略语法错误会让它 exit 2 并且**不会启动上游** |
|
|
206
|
+
| 某个工具莫名被拦 | 它的工具名不在基线放行列表里(`base-allow-*`),或命中了某条 deny。`agentguard audit list --decision deny` 直接看是哪条规则 |
|
|
207
|
+
| 想先观察不拦截 | `agentguard init --observe --force`,或把策略里 `dry_run` 改成 `true` |
|
|
208
|
+
| Windows 下提示找不到命令 | agentguard 已处理 `.cmd` 垫片;如果仍失败,把上游命令换成显式路径(如 `node C:/path/to/server.js`) |
|
|
209
|
+
|
|
210
|
+
## 策略 DSL
|
|
211
|
+
|
|
212
|
+
```yaml
|
|
213
|
+
version: 1
|
|
214
|
+
|
|
215
|
+
defaults:
|
|
216
|
+
on_no_match: deny # deny | allow | ask(默认 deny)
|
|
217
|
+
dry_run: false # true = 只记录不拦截
|
|
218
|
+
|
|
219
|
+
rules:
|
|
220
|
+
- id: block-rm-rf-root # 全局唯一,会进审计日志
|
|
221
|
+
match:
|
|
222
|
+
tool: bash # 裸值 = equals;数组 = in
|
|
223
|
+
args.command: # args 字段必须写成操作符对象
|
|
224
|
+
regex: 'rm\s+(-[a-zA-Z]+\s+)*-(rf|fr)\s+/'
|
|
225
|
+
decision: deny # allow | deny | ask
|
|
226
|
+
reason: 递归删除根目录
|
|
227
|
+
|
|
228
|
+
limits: # W2 解析并校验,W4 才执行
|
|
229
|
+
- tool: bash
|
|
230
|
+
max_calls: 200
|
|
231
|
+
window: 1h
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
匹配语义:
|
|
235
|
+
|
|
236
|
+
| 要素 | 规则 |
|
|
237
|
+
|---|---|
|
|
238
|
+
| 字段路径 | `tool` 或 `args.<点号路径>`,支持数组下标 `args.files.0.path` |
|
|
239
|
+
| 操作符 | `glob` / `regex` / `equals` / `in` / `prefix` |
|
|
240
|
+
| 多值 | 同一操作符的多个取值是 OR |
|
|
241
|
+
| 多字段 | 同一规则的多字段是 AND |
|
|
242
|
+
| 实参数组 | 逐个元素判定,任一命中即命中 |
|
|
243
|
+
| 优先级 | `deny > ask > allow`;同档取声明在前的第一条 |
|
|
244
|
+
| 大小写 | `glob` / `regex` 不敏感(安全优先),其余精确匹配 |
|
|
245
|
+
|
|
246
|
+
## 开发
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
npm install # 运行时依赖只有 yaml;devDeps 是 typescript / @types/node
|
|
250
|
+
npm run build # tsc -> dist/
|
|
251
|
+
|
|
252
|
+
npm run check:w1 # W1 验收:差分比对 + 6 类边界
|
|
253
|
+
npm run check:w2 # W2 验收:判定语义 + 20 种非法策略 + 性能
|
|
254
|
+
npm run check:w3 # W3 验收:拦截路径 / ask / dry_run / 上游崩溃 / 无策略文件
|
|
255
|
+
npm run check:w4 # W4 验收:审计字段 / 截断 / 限流 / 查询导出 / 保留期
|
|
256
|
+
npm run check:w5 # W5 验收:四套包 / 误伤检查 / init 产物 / check 预演
|
|
257
|
+
npm run check:attacks # 18 条攻击用例(方案第 9 章)
|
|
258
|
+
npm run check:stress # 8 MiB / 1000 次调用 / CRLF / BOM / 判定延迟
|
|
259
|
+
npm run check:lint # 正则回溯风险
|
|
260
|
+
npm run check:coldstart # 全新 HOME 的 3 分钟冷启动计时
|
|
261
|
+
npm run check:real # 真实 filesystem server:透传比对 + 拦 .env 放行普通文件
|
|
262
|
+
npm run check:pkg # 安装包边界:pack → 干净目录安装 → 实跑
|
|
263
|
+
npm run check:all # 以上全部
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## 发布
|
|
267
|
+
|
|
268
|
+
`prepublishOnly` 会先 `npm run build`,所以 dist 一定是当前源码编译出来的。
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
npm run check:all # 11 个 suite / 290 条断言必须全绿
|
|
272
|
+
npm publish # 需要先 npm login
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
包内只含 `dist/` + `packs/` + README + LICENSE(20 个文件,约 40 KB),不含源码、测试与 source map。
|
|
276
|
+
|
|
277
|
+
## 设计取舍(与方案一致)
|
|
278
|
+
|
|
279
|
+
| 决策 | 原因 |
|
|
280
|
+
|---|---|
|
|
281
|
+
| 转发原始字节,不 JSON 往返 | 浮点精度、字段顺序、转义都会变,client 可能比对失败 |
|
|
282
|
+
| 自建行分割器,不用 readline | 大 JSON 会被行缓冲截断 |
|
|
283
|
+
| 三路 stdio 全部 pipe | 继承 fd 等于把代理短路 |
|
|
284
|
+
| Windows 自己拼 cmd 行 | Node 的 `shell: true` 只做空格拼接,带空格的参数会被劈开 |
|
|
285
|
+
| 日志只写 stderr | stdout 是协议流,写一个字就污染 |
|
|
286
|
+
| `args.*` 必须显式写操作符 | 裸值只能当 equals,用户写 `'**/.env*'` 时想表达的几乎一定是 glob |
|
|
287
|
+
| regex / glob 加载期预编译 | 写错的规则必须启动就报,不能等第一次调用 |
|
|
288
|
+
|
|
289
|
+
## 已知边界(不藏着)
|
|
290
|
+
|
|
291
|
+
| 边界 | 影响 | 状态 |
|
|
292
|
+
|---|---|---|
|
|
293
|
+
| **只看请求,不看响应** | 工具返回值里泄漏密钥拦不住(方案第 5 章「内容含 sk- 的输出」需要响应侧规则引擎) | 未做,后续版本 |
|
|
294
|
+
| **正则无执行超时** | 用户写 `(a+)+$` 这类模式,恶意输入能把网关卡住(实测 26 字符 → 2.6s)。已做加载期告警,但**不会硬拦** | 告警已上;worker + 超时待做 |
|
|
295
|
+
| **ask 没有审批通道** | `ask` 一律按拒绝处理,不会弹交互确认 | 设计如此(代理 stdin 就是协议流,读 y/n 会吃掉 MCP 消息) |
|
|
296
|
+
| **没有域名 allowlist** | 「生产域名白名单外」这类规则表达不了,只能逐条 deny | DSL 限制 |
|
|
297
|
+
| **审计写失败不阻断转发** | 目录只读/磁盘满时告警后停写,代理继续工作 | 有意的取舍,避免一个坏路径让网关变砖 |
|
|
298
|
+
| **限流是固定窗口** | 窗口边界最多放过 2 倍瞬时流量 | 对本产品的诉求(防整夜烧钱)足够 |
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 审计查询:list / stats / export。
|
|
3
|
+
*
|
|
4
|
+
* 读法是「新文件先读、文件内倒序读」:审计是追加写,时间天然有序,
|
|
5
|
+
* 所以一旦碰到早于 --since 的记录就可以整段停手,不需要把全部历史读进内存。
|
|
6
|
+
*/
|
|
7
|
+
import { readFileSync, readdirSync } from 'node:fs';
|
|
8
|
+
import { join } from 'node:path';
|
|
9
|
+
const DAY_FILE = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
|
|
10
|
+
const DURATION = /^(\d+)(s|m|h|d|w)$/;
|
|
11
|
+
const UNIT_MS = {
|
|
12
|
+
s: 1_000,
|
|
13
|
+
m: 60_000,
|
|
14
|
+
h: 3_600_000,
|
|
15
|
+
d: 86_400_000,
|
|
16
|
+
w: 604_800_000,
|
|
17
|
+
};
|
|
18
|
+
/** `7d` / `24h` / `30m` / `2026-11-01` / 完整 ISO 都能用 */
|
|
19
|
+
export function parseSince(text, now = Date.now()) {
|
|
20
|
+
const duration = DURATION.exec(text.trim());
|
|
21
|
+
if (duration !== null) {
|
|
22
|
+
return now - Number(duration[1]) * UNIT_MS[duration[2]];
|
|
23
|
+
}
|
|
24
|
+
const parsed = Date.parse(text);
|
|
25
|
+
if (Number.isNaN(parsed)) {
|
|
26
|
+
throw new Error(`无法识别的时间 "${text}"(可用:7d / 24h / 30m / 2026-11-01)`);
|
|
27
|
+
}
|
|
28
|
+
return parsed;
|
|
29
|
+
}
|
|
30
|
+
/** 按日期倒序返回审计文件全路径 */
|
|
31
|
+
export function listAuditFiles(dir) {
|
|
32
|
+
let names;
|
|
33
|
+
try {
|
|
34
|
+
names = readdirSync(dir);
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return [];
|
|
38
|
+
}
|
|
39
|
+
return names
|
|
40
|
+
.filter((name) => DAY_FILE.test(name))
|
|
41
|
+
.sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
|
|
42
|
+
.map((name) => join(dir, name));
|
|
43
|
+
}
|
|
44
|
+
export function readRecords(filter) {
|
|
45
|
+
const limit = filter.limit ?? Number.POSITIVE_INFINITY;
|
|
46
|
+
const out = [];
|
|
47
|
+
for (const file of listAuditFiles(filter.dir)) {
|
|
48
|
+
let text;
|
|
49
|
+
try {
|
|
50
|
+
text = readFileSync(file, 'utf8');
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
const lines = text.split('\n');
|
|
56
|
+
for (let i = lines.length - 1; i >= 0; i--) {
|
|
57
|
+
const line = lines[i].trim();
|
|
58
|
+
if (line === '')
|
|
59
|
+
continue;
|
|
60
|
+
let record;
|
|
61
|
+
try {
|
|
62
|
+
record = JSON.parse(line);
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
continue; // 半行(进程被强杀)直接跳过,不因此中断查询
|
|
66
|
+
}
|
|
67
|
+
const ts = Date.parse(record.ts);
|
|
68
|
+
if (Number.isNaN(ts))
|
|
69
|
+
continue;
|
|
70
|
+
// 文件内是时间升序,倒序读时一旦早于 since 就可以整个文件收手
|
|
71
|
+
if (filter.since !== undefined && ts < filter.since)
|
|
72
|
+
break;
|
|
73
|
+
if (filter.until !== undefined && ts > filter.until)
|
|
74
|
+
continue;
|
|
75
|
+
if (filter.decision !== undefined && record.decision !== filter.decision)
|
|
76
|
+
continue;
|
|
77
|
+
if (filter.tool !== undefined && record.tool !== filter.tool)
|
|
78
|
+
continue;
|
|
79
|
+
out.push(record);
|
|
80
|
+
if (out.length >= limit)
|
|
81
|
+
return out;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return out;
|
|
85
|
+
}
|
|
86
|
+
function csvCell(value) {
|
|
87
|
+
const text = value === null || value === undefined
|
|
88
|
+
? ''
|
|
89
|
+
: typeof value === 'string'
|
|
90
|
+
? value
|
|
91
|
+
: JSON.stringify(value);
|
|
92
|
+
if (/[",\r\n]/.test(text))
|
|
93
|
+
return `"${text.replace(/"/g, '""')}"`;
|
|
94
|
+
return text;
|
|
95
|
+
}
|
|
96
|
+
export function toCsv(records) {
|
|
97
|
+
const header = ['ts', 'reqId', 'tool', 'decision', 'raw', 'ruleId', 'ms', 'session', 'agent', 'args'];
|
|
98
|
+
const rows = records.map((r) => [
|
|
99
|
+
r.ts,
|
|
100
|
+
r.reqId,
|
|
101
|
+
r.tool,
|
|
102
|
+
r.decision,
|
|
103
|
+
r.raw ?? '',
|
|
104
|
+
r.ruleId ?? '',
|
|
105
|
+
r.ms,
|
|
106
|
+
r.session,
|
|
107
|
+
r.agent ?? '',
|
|
108
|
+
r.args,
|
|
109
|
+
]
|
|
110
|
+
.map(csvCell)
|
|
111
|
+
.join(','));
|
|
112
|
+
return [header.join(','), ...rows].join('\n') + '\n';
|
|
113
|
+
}
|
|
114
|
+
export function summarize(records) {
|
|
115
|
+
const decisions = {};
|
|
116
|
+
const rules = new Map();
|
|
117
|
+
const tools = new Map();
|
|
118
|
+
let min = Number.POSITIVE_INFINITY;
|
|
119
|
+
let max = Number.NEGATIVE_INFINITY;
|
|
120
|
+
for (const record of records) {
|
|
121
|
+
decisions[record.decision] = (decisions[record.decision] ?? 0) + 1;
|
|
122
|
+
const rule = record.ruleId ?? '(未命中规则)';
|
|
123
|
+
rules.set(rule, (rules.get(rule) ?? 0) + 1);
|
|
124
|
+
tools.set(record.tool, (tools.get(record.tool) ?? 0) + 1);
|
|
125
|
+
const ts = Date.parse(record.ts);
|
|
126
|
+
if (!Number.isNaN(ts)) {
|
|
127
|
+
min = Math.min(min, ts);
|
|
128
|
+
max = Math.max(max, ts);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
return {
|
|
132
|
+
total: records.length,
|
|
133
|
+
decisions,
|
|
134
|
+
rules: [...rules.entries()]
|
|
135
|
+
.map(([ruleId, count]) => ({ ruleId, count }))
|
|
136
|
+
.sort((a, b) => b.count - a.count),
|
|
137
|
+
tools: [...tools.entries()]
|
|
138
|
+
.map(([tool, count]) => ({ tool, count }))
|
|
139
|
+
.sort((a, b) => b.count - a.count),
|
|
140
|
+
since: Number.isFinite(min) ? min : null,
|
|
141
|
+
until: Number.isFinite(max) ? max : null,
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
export function formatTime(iso) {
|
|
145
|
+
const ts = Date.parse(iso);
|
|
146
|
+
if (Number.isNaN(ts))
|
|
147
|
+
return iso;
|
|
148
|
+
const d = new Date(ts);
|
|
149
|
+
const pad = (n) => String(n).padStart(2, '0');
|
|
150
|
+
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
|
|
151
|
+
}
|