@yottameta/yotta-guardian 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +19 -3
  2. package/LICENSE +20 -20
  3. package/README.md +151 -163
  4. package/README.zh-CN.md +39 -51
  5. package/SKILL.md +5 -3
  6. package/bin/install.js +162 -162
  7. package/install.sh +131 -131
  8. package/package.json +6 -2
  9. package/scripts/yotta_guardian.py +1 -1
  10. package/skill-manifest.json +33 -0
  11. package/scripts/test_yotta_guardian.py +0 -454
package/CHANGELOG.md CHANGED
@@ -1,8 +1,24 @@
1
1
  # 更新日志
2
2
 
3
+ ## v0.1.3 (2026-09-13)
4
+
5
+ **P0-4.3 元盾 before_tool 试点**：
6
+
7
+ - 新增 `skill-manifest.json`，声明 `before_tool` / `guard_check` / `fallback: explicit-unverified`。
8
+ - 发布工作流 `.github/workflows/publish.yml` 纳入版本库，标签推送可触发 GitHub Actions。
9
+ - Codex 该事件为 `native-audit`：危险调用评估失败时只能审计并触发一次纠偏，不宣称动作前硬拦截。
10
+ - 元阁适配器回归验证 `native-audit` 结果、纠偏信号与审计证据写入。
11
+ - 补充使用范围、授权与法律红线声明，明确本技能不是操作系统沙箱，也不替代宿主权限控制与人工决策。
12
+
13
+ ## v0.1.2 (2026-08-29)
14
+
15
+ - 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-guardian --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-guardian.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
16
+ - 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.1.2。
17
+ - 无功能变更（仅文档与版本同步）。
18
+
3
19
  ## v0.1.1 (2026-08-28)
4
20
 
5
- 中英双语 README 对齐（老张拍板「英文门面 + 中文全档」）：
21
+ 中英双语 README 对齐（英文门面 + 中文全档）：
6
22
 
7
23
  - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 边界 / 开发校验全流程）。
8
24
  - **新增 README.zh-CN.md**：原中文完整主文档整体平移，顶部加语言切换链接。
@@ -13,7 +29,7 @@
13
29
 
14
30
  ## v0.1.0 (2026-08-26)
15
31
 
16
- YottaMeta 自有实现首版（护栏/拦截方向参考开源社区 safe-guardian 类技能思路，已完全重写，零依赖、无上游代码）：
32
+ YottaMeta 自有实现首版（护栏/拦截方向参考开源社区同类技能思路，已完全重写，零依赖）：
17
33
 
18
34
  - **零依赖自研引擎**（scripts/yotta_guardian.py，Python 3.8+ 标准库）：确定性规则引擎 + 可插拔意图验证，对 exec / write / edit / read / run / shell 工具调用做安全评估。
19
35
  - **四层规则**：文本模式（下载即执行 / 编码执行 / 反向 shell / 系统文件追加）+ argv 级动词/目标分析（rm / dd / mkfs / chmod / chown / 提权 / 防火墙 / 服务 / 持久化 / 反向 shell）+ 敏感路径（/etc 核心文件、/boot、/dev、SSH 授权、Windows 系统目录与 hosts、注册表启动项等）+ 写入内容（私钥 / 密钥令牌）。
@@ -23,4 +39,4 @@ YottaMeta 自有实现首版（护栏/拦截方向参考开源社区 safe-guardi
23
39
  - **输出**：文本 / JSON（stdout 纯净）/ Markdown 报告；--batch 批量预检。
24
40
  - **测试**：scripts/test_yotta_guardian.py 60 项全绿（命令/路径/内容/策略/放行/批量/JSON/报告/审计/验证器/配置/GBK 控制台）。
25
41
  - **文档**：SKILL.md / README.md / references（rules / policies / intent-verifier）/ assets/banner.png。
26
- - 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明；README 一行上游致谢。
42
+ - 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明。
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 YottaMeta
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1
+ MIT License
2
+
3
+ Copyright (c) 2026 YottaMeta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
21
  SOFTWARE.
package/README.md CHANGED
@@ -1,163 +1,151 @@
1
- <p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
2
-
3
- <p align="center">
4
- <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
5
- </p>
6
-
7
- <h1 align="center">yotta-guardian · 元盾 (Yuandun)</h1>
8
-
9
- <p align="center">YottaMeta's tool-call interception guardrail: a <b>deterministic rule engine + pluggable intent verifier</b> that evaluates exec / write / edit / read / run / shell tool calls and returns <b>allow / deny + matched rules + audit logs</b>. Use it as a deterministic safety gate before an agent runs a high-risk command, writes a sensitive system path, or changes system configuration.</p>
10
- <p align="center">Activates when an agent is about to perform dangerous operations — recursive delete, disk formatting, privilege escalation, firewall changes, reverse shell, download-and-run, writes to core system files — <b>deterministic verdicts by rules, not prompt-engineering luck</b>.</p>
11
- <p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only evaluation by default, configurable allowances, full audit trail.</p>
12
-
13
- <p align="center">
14
- <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
15
- <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
16
- <a href="https://www.npmjs.com/package/@yottameta/yotta-guardian"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-guardian" /></a>
17
- <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-guardian" /></a>
18
- <a href="https://github.com/YottaMeta/yotta-guardian/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-guardian" /></a>
19
- <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
20
- </p>
21
-
22
- ## What it is
23
-
24
- When an AI agent acts autonomously, a single recursive delete, one disk write, or a download-and-run can cause irreversible damage. Yuandun packages these dangerous actions into a deterministic rule engine: every tool call (exec / write / edit / read / run / shell) is evaluated structurally — command text, argv-level verb and target analysis, sensitive paths, and written content — producing an allow / deny verdict with the matched rules and reasons, plus audit-log trails.
25
-
26
- It is not tied to any single platform: an agent-agnostic toolkit that works in any agent supporting Agent Skills. Read-only evaluation by default — it neither executes nor auto-approves dangerous actions; intent verification calls no model by default and can be plugged into any external verifier (e.g. an LLM gateway) through a JSON protocol.
27
-
28
- ## Core value
29
-
30
- - **Deterministic rule engine** — text patterns (download-and-run / encoded execution / reverse shell) + argv-level verb/target analysis (rm / dd / mkfs / chmod / chown / privilege escalation / firewall / services / persistence) + sensitive paths + written content: four stacked layers of rules.
31
- - **Sensitive-path guard** — writes to /etc/passwd, /etc/sudoers, SSH authorized keys, /boot, /dev devices, Windows system directories and hosts, and registry startup entries are denied.
32
- - **Pluggable intent verification (no model required)** — zero-dependency by default; optional built-in local heuristics (--heuristic), or any external intent verifier via a stdin/stdout JSON protocol (--verifier / config file).
33
- - **Three policies** — default (deny high+), strict (deny medium+), loose (deny critical only), chosen per scenario.
34
- - **Audit trail** — JSONL audit log + audit query subcommand; every allow / deny is traceable.
35
- - **Machine readable** — --json outputs pure JSON (per-call verdicts, rules, exit codes); --batch pre-checks a list of calls, ideal as a pre-execution gate.
36
-
37
- ## Why use it
38
-
39
- | Advantage | Description |
40
- |---|---|
41
- | **Zero dependency** | Python 3.8+ standard library; no daemon / database / external scanner; Windows + Linux + macOS |
42
- | **Deterministic** | Verdicts are reproducible and explainable, not model probability; intent verification is off by default and opt-in |
43
- | **Structural** | Evaluates commands, paths and content per tool type (exec / write / edit / read), not naive string matching |
44
- | **Configurable** | --allow / --allow-path / custom rule JSON (policy / deny / allow / verifier) |
45
- | **Traceable** | Every verdict lands in a JSONL audit log; audit subcommand filters by denied / tool / time |
46
- | **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
47
-
48
- ## Commands
49
-
50
- | Command | Description |
51
- |---|---|
52
- | check | Evaluate one or a batch of tool calls (--batch); text / JSON / Markdown reports |
53
- | audit | Query audit logs (--tail / --denied / --since / --tool / --json) |
54
- | rules | Print the built-in rule summary / validate a custom rules file |
55
- | version | Print the version |
56
-
57
- ## Quick start
58
-
59
- Windows uses python, Linux/macOS uses python3.
60
-
61
- ```bash
62
- # Check one exec call (0 = allowed)
63
- python3 scripts/yotta_guardian.py check exec --cmd "git status"
64
-
65
- # Check a dangerous command (denied by default, exit code 3)
66
- python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
67
-
68
- # Check a write (writing /etc/passwd is denied)
69
- python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
70
-
71
- # Batch pre-check (the agent hands the pending call list to the guardrail before running)
72
- python3 scripts/yotta_guardian.py check --batch calls.json --json
73
-
74
- # Audit
75
- python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
76
- python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
77
- ```
78
-
79
- Exit codes (same semantics as the YuanAn / YuanShen family): **0** = allowed; **1** = allowed with warning (manual review recommended); **2** = denied (high); **3** = denied (critical); **4** = usage error / fatal exception.
80
-
81
- ## Install
82
-
83
- Pick any one of the three methods; skill files are fetched from **npm** (GitHub is slower without a proxy; npm can use a domestic mirror).
84
-
85
- ### Method 1: npm (recommended, one-liner)
86
- ```bash
87
- # domestic mirror (optional): npm config set registry https://registry.npmmirror.com
88
- npx -y @yottameta/yotta-guardian -g
89
- npx -y @yottameta/yotta-guardian --dir <your-skills-dir> # any agent: install to a specific directory
90
- ```
91
- > Not in the preset list? Use --dir to point at the agent's skills directory, or manual copy (method 3). --list shows each agent's default directory. You can also npm pack @yottameta/yotta-guardian and unpack it to install via method 2 / 3.
92
-
93
- ### Method 2: install.sh one-shot
94
- After obtaining the skill folder (npm pack unpack or git clone), enter the folder:
95
- ```bash
96
- bash install.sh -g # user level; bash install.sh --list shows all directories
97
- bash install.sh --agent codex # specific agent (--list shows available ones)
98
- bash install.sh # project level: auto-detect existing .claude/.cursor/.codex skills dirs
99
- bash install.sh --dir /path/to/skills
100
- ```
101
- > Covers 17 agent families including Trae / Qwen / Comate / CodeBuddy / Kimi. Windows users: works with Git Bash; otherwise use method 3.
102
-
103
- ### Method 3: manual copy
104
- Copy the whole yotta-guardian folder into the target agent's skills directory. Common locations (user level; Windows uses %USERPROFILE%, Linux/macOS uses ~):
105
-
106
- | Agent | User-level directory | Project-level directory |
107
- |---|---|---|
108
- | Codex | %USERPROFILE%\.codex\skills\yotta-guardian\ | .codex\skills\ |
109
- | Claude Code | %USERPROFILE%\.claude\skills\yotta-guardian\ | .claude\skills\ |
110
- | Cursor | %USERPROFILE%\.cursor\skills\yotta-guardian\ | .cursor\skills\ |
111
- | Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-guardian\ | .windsurf\skills\ |
112
- | opencode | %USERPROFILE%\.config\opencode\skills\yotta-guardian\ | .opencode\skills\ |
113
- | Gemini | %USERPROFILE%\.gemini\skills\yotta-guardian\ | .gemini\skills\ |
114
- | Goose | %USERPROFILE%\.config\goose\skills\yotta-guardian\ | .goose\skills\ |
115
- | Amp | %USERPROFILE%\.config\agents\skills\yotta-guardian\ | .agents\skills\ |
116
- | Kiro | %USERPROFILE%\.kiro\skills\yotta-guardian\ | .kiro\skills\ |
117
- | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-guardian\ | .workbuddy\skills\ |
118
- | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-guardian\ | .traecli\skills\ |
119
- | Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-guardian\ | .trae\skills\ |
120
- | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-guardian\ | .qwen\skills\ |
121
- | Comate | %USERPROFILE%\.comate\skills\yotta-guardian\ | .comate\skills\ |
122
- | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-guardian\ | .codebuddy\skills\ |
123
- | Kimi | %USERPROFILE%\.kimi\skills\yotta-guardian\ | .kimi\skills\ |
124
- | Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-guardian\ | .agents\skills\ |
125
-
126
- > If Codex's CODEX_HOME is set, it overrides the default; the same applies to opencode's XDG_CONFIG_HOME. .agents\skills is not a universal directory — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; **Claude Code and Codex do not read it by default**. When unsure, use --dir or let the agent install it.
127
-
128
- ## Usage examples (AI agent)
129
-
130
- 1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
131
- 2. Before executing any high-risk tool call, run a check first:
132
- ```bash
133
- python3 scripts/yotta_guardian.py check exec --cmd "<pending command>" --json
134
- ```
135
- With exit code 2 / 3, do not execute — explain the matched rules to the user; only with explicit authorization use --allow / --allow-path / custom rules.
136
- 3. For multiple calls, pre-check in batch:
137
- ```bash
138
- python3 scripts/yotta_guardian.py check --batch calls.json --json
139
- ```
140
- 4. Before writing sensitive paths / changing system config, check the target path and content with write / edit.
141
- 5. High-risk operations land in the audit log; query them later with audit.
142
-
143
- ## Boundaries (security red lines)
144
-
145
- - **Read-only evaluation by default** — does not execute, does not auto-approve, does not modify anything; it is a gate before execution, not a substitute for the user's decision.
146
- - **No hidden audit** — every verdict is recorded and traceable; rules are configurable but critical rules cannot be overridden.
147
- - **Authorization** — for explicitly authorized / own-asset / educational environments only; using it to bypass real-world authorization is the user's own responsibility.
148
-
149
- ## Development & validation
150
-
151
- - Tests: python scripts/test_yotta_guardian.py (60 tests; Windows: python)
152
- - Base validation: python tools/validate-skill.py yotta-guardian (run at the repo root)
153
- - Rule details: references/rules.md; policies & exit codes: references/policies.md; intent-verifier protocol: references/intent-verifier.md
154
-
155
- Keep tests green and bump the version before releasing changes.
156
-
157
- ## Changelog
158
-
159
- See [CHANGELOG.md](./CHANGELOG.md).
160
-
161
- ## License
162
-
163
- [MIT](./LICENSE) © YottaMeta. "Yuandun" / "yotta-guardian" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The guardrail direction references open-source safe-guardian style skills; the implementation is YottaMeta's own new code.
1
+ <p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
2
+
3
+ <p align="center">
4
+ <img src="assets/banner.png" alt="yotta-guardian banner" width="100%" />
5
+ </p>
6
+
7
+ <h1 align="center">yotta-guardian · 元盾 (Yuandun)</h1>
8
+
9
+ <p align="center">YottaMeta's tool-call interception guardrail: a <b>deterministic rule engine + pluggable intent verifier</b> that evaluates exec / write / edit / read / run / shell tool calls and returns <b>allow / deny + matched rules + audit logs</b>. Use it as a deterministic safety gate before an agent runs a high-risk command, writes a sensitive system path, or changes system configuration.</p>
10
+ <p align="center">Activates when an agent is about to perform dangerous operations — recursive delete, disk formatting, privilege escalation, firewall changes, reverse shell, download-and-run, writes to core system files — <b>deterministic verdicts by rules, not prompt-engineering luck</b>.</p>
11
+ <p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only evaluation by default, configurable allowances, full audit trail.</p>
12
+
13
+ <p align="center">
14
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
15
+ <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
16
+ <a href="https://www.npmjs.com/package/@yottameta/yotta-guardian"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-guardian" /></a>
17
+ <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-guardian" /></a>
18
+ <a href="https://github.com/YottaMeta/yotta-guardian/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-guardian" /></a>
19
+ <a href="https://github.com/YottaMeta/yotta-guardian"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
20
+ </p>
21
+
22
+ ## What it is
23
+
24
+ When an AI agent acts autonomously, a single recursive delete, one disk write, or a download-and-run can cause irreversible damage. Yuandun packages these dangerous actions into a deterministic rule engine: every tool call (exec / write / edit / read / run / shell) is evaluated structurally — command text, argv-level verb and target analysis, sensitive paths, and written content — producing an allow / deny verdict with the matched rules and reasons, plus audit-log trails.
25
+
26
+ It is not tied to any single platform: an agent-agnostic toolkit that works in any agent supporting Agent Skills. Read-only evaluation by default — it neither executes nor auto-approves dangerous actions; intent verification calls no model by default and can be plugged into any external verifier (e.g. an LLM gateway) through a JSON protocol.
27
+
28
+ ## Core value
29
+
30
+ - **Deterministic rule engine** — text patterns (download-and-run / encoded execution / reverse shell) + argv-level verb/target analysis (rm / dd / mkfs / chmod / chown / privilege escalation / firewall / services / persistence) + sensitive paths + written content: four stacked layers of rules.
31
+ - **Sensitive-path guard** — writes to /etc/passwd, /etc/sudoers, SSH authorized keys, /boot, /dev devices, Windows system directories and hosts, and registry startup entries are denied.
32
+ - **Pluggable intent verification (no model required)** — zero-dependency by default; optional built-in local heuristics (--heuristic), or any external intent verifier via a stdin/stdout JSON protocol (--verifier / config file).
33
+ - **Three policies** — default (deny high+), strict (deny medium+), loose (deny critical only), chosen per scenario.
34
+ - **Audit trail** — JSONL audit log + audit query subcommand; every allow / deny is traceable.
35
+ - **Machine readable** — --json outputs pure JSON (per-call verdicts, rules, exit codes); --batch pre-checks a list of calls, ideal as a pre-execution gate.
36
+
37
+ ## Why use it
38
+
39
+ | Advantage | Description |
40
+ |---|---|
41
+ | **Zero dependency** | Python 3.8+ standard library; no daemon / database / external scanner; Windows + Linux + macOS |
42
+ | **Deterministic** | Verdicts are reproducible and explainable, not model probability; intent verification is off by default and opt-in |
43
+ | **Structural** | Evaluates commands, paths and content per tool type (exec / write / edit / read), not naive string matching |
44
+ | **Configurable** | --allow / --allow-path / custom rule JSON (policy / deny / allow / verifier) |
45
+ | **Traceable** | Every verdict lands in a JSONL audit log; audit subcommand filters by denied / tool / time |
46
+ | **Ecosystem distribution** | GitHub + npm + ClawHub synced; four install methods (npx / git clone / Download ZIP / install.sh) |
47
+
48
+ ## Commands
49
+
50
+ | Command | Description |
51
+ |---|---|
52
+ | check | Evaluate one or a batch of tool calls (--batch); text / JSON / Markdown reports |
53
+ | audit | Query audit logs (--tail / --denied / --since / --tool / --json) |
54
+ | rules | Print the built-in rule summary / validate a custom rules file |
55
+ | version | Print the version |
56
+
57
+ ## Quick start
58
+
59
+ Windows uses python, Linux/macOS uses python3.
60
+
61
+ ```bash
62
+ # Check one exec call (0 = allowed)
63
+ python3 scripts/yotta_guardian.py check exec --cmd "git status"
64
+
65
+ # Check a dangerous command (denied by default, exit code 3)
66
+ python3 scripts/yotta_guardian.py check exec --cmd "rm -rf /"
67
+
68
+ # Check a write (writing /etc/passwd is denied)
69
+ python3 scripts/yotta_guardian.py check write --path /etc/passwd --content "..."
70
+
71
+ # Batch pre-check (the agent hands the pending call list to the guardrail before running)
72
+ python3 scripts/yotta_guardian.py check --batch calls.json --json
73
+
74
+ # Audit
75
+ python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
76
+ python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
77
+ ```
78
+
79
+ Exit codes (same semantics as the YuanAn / YuanShen family): **0** = allowed; **1** = allowed with warning (manual review recommended); **2** = denied (high); **3** = denied (critical); **4** = usage error / fatal exception.
80
+
81
+ ## Install
82
+
83
+ Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
84
+
85
+ ### Method 1: npm one-liner (recommended)
86
+
87
+ ```text
88
+ # Optional China mirror: npm config set registry https://registry.npmmirror.com
89
+ npx -y @yottameta/yotta-guardian --agent <agent-name> # install to the agent's default user-level skills dir
90
+ npx -y @yottameta/yotta-guardian --dir <your-skills-dir> # point to the skills dir itself (e.g. ~/.codex/skills)
91
+ ```
92
+
93
+ - `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
94
+ - `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
95
+ - If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
96
+
97
+ ### Method 2: git clone (developers / git available)
98
+
99
+ ```text
100
+ git clone https://github.com/YottaMeta/yotta-guardian.git <your-skills-dir>/yotta-guardian
101
+ ```
102
+
103
+ ### Method 3: GitHub Download ZIP (manual / no git)
104
+
105
+ On the GitHub repository `YottaMeta/yotta-guardian`, click **Code → Download ZIP**, unzip it and put the `yotta-guardian` folder into the agent's skills directory.
106
+
107
+ ### Method 4: install.sh (multi-agent one-liner script)
108
+
109
+ ```text
110
+ bash install.sh --agent <name> # install to the agent's default user-level directory
111
+ bash install.sh --dir <path> # install to the given directory
112
+ bash install.sh --list # list agents -> default directories
113
+ ```
114
+
115
+ > Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
116
+ ## Usage examples (AI agent)
117
+
118
+ 1. Hook this repo's SKILL.md into any AI agent's skill/rule system (see install above).
119
+ 2. Before executing any high-risk tool call, run a check first:
120
+ ```bash
121
+ python3 scripts/yotta_guardian.py check exec --cmd "<pending command>" --json
122
+ ```
123
+ With exit code 2 / 3, do not execute — explain the matched rules to the user; only with explicit authorization use --allow / --allow-path / custom rules.
124
+ 3. For multiple calls, pre-check in batch:
125
+ ```bash
126
+ python3 scripts/yotta_guardian.py check --batch calls.json --json
127
+ ```
128
+ 4. Before writing sensitive paths / changing system config, check the target path and content with write / edit.
129
+ 5. High-risk operations land in the audit log; query them later with audit.
130
+
131
+ ## Boundaries (security red lines)
132
+
133
+ - **Read-only evaluation by default** — does not execute, does not auto-approve, does not modify anything; it is a gate before execution, not a substitute for the user's decision.
134
+ - **No hidden audit** — every verdict is recorded and traceable; rules are configurable but critical rules cannot be overridden.
135
+ - **Authorization** — for explicitly authorized / own-asset / educational environments only; using it to bypass real-world authorization is the user's own responsibility.
136
+
137
+ ## Development & validation
138
+
139
+ - Tests: python scripts/test_yotta_guardian.py (60 tests; Windows: python)
140
+ - Base validation: python tools/validate-skill.py yotta-guardian (run at the repo root)
141
+ - Rule details: references/rules.md; policies & exit codes: references/policies.md; intent-verifier protocol: references/intent-verifier.md
142
+
143
+ Keep tests green and bump the version before releasing changes.
144
+
145
+ ## Changelog
146
+
147
+ See [CHANGELOG.md](./CHANGELOG.md).
148
+
149
+ ## License
150
+
151
+ [MIT](./LICENSE) © YottaMeta. "Yuandun" / "yotta-guardian" and the YottaMeta family names (yotta-* prefix) are YottaMeta brand identifiers; derived works must not reuse them, see [NOTICE](./NOTICE). The guardrail direction references open-source safe-guardian style skills; the implementation is YottaMeta's own new code.
package/README.zh-CN.md CHANGED
@@ -44,7 +44,7 @@ AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段
44
44
  | **结构化** | 按工具类型（exec / write / edit / read）分别评估命令、路径与内容，不是简单字符串匹配 |
45
45
  | **可配置** | --allow / --allow-path / 自定义规则 JSON（policy / deny / allow / verifier） |
46
46
  | **可追溯** | 每次判定落 JSONL 审计日志，audit 子命令可按拒绝 / 工具 / 时间过滤 |
47
- | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
47
+ | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式 |
48
48
 
49
49
  ## 功能体系
50
50
 
@@ -59,7 +59,7 @@ AI 代理在自主执行时，一条递归删除、一次磁盘写入、一段
59
59
 
60
60
  Windows 用 python，Linux/macOS 用 python3。
61
61
 
62
- `````bash
62
+ ```bash
63
63
  # 检查一条 exec（0 = 允许）
64
64
  python3 scripts/yotta_guardian.py check exec --cmd "git status"
65
65
 
@@ -75,69 +75,57 @@ python3 scripts/yotta_guardian.py check --batch calls.json --json
75
75
  # 审计
76
76
  python3 scripts/yotta_guardian.py check exec --cmd "..." --audit-log .yotta-guardian/audit.jsonl
77
77
  python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tail 20
78
- `````
78
+ ```
79
79
 
80
80
  退出码语义（与元安 / 元审家族一致）：0 = 允许；1 = 允许但带警告（建议人工复核）；2 = 拒绝（high）；3 = 拒绝（critical）；4 = 用法错误 / 致命异常。
81
81
 
82
82
  ## 安装
83
83
 
84
- 三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
85
-
86
- ### 方式一：npm（推荐，一行安装）
87
- `````bash
88
- # 国内加速（可选）：npm config set registry https://registry.npmmirror.com
89
- npx -y @yottameta/yotta-guardian -g
90
- npx -y @yottameta/yotta-guardian --dir <你的技能目录> # 任意智能体：指定目录安装
91
- `````
92
- > 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-guardian 解包后按方式二/三安装。
93
-
94
- ### 方式二：install.sh 一键安装
95
- 获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
96
- `````bash
97
- bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
98
- bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
99
- bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
100
- bash install.sh --dir /path/to/skills
101
- `````
102
- > 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
103
-
104
- ### 方式三：手动复制
105
- 把整个 yotta-guardian 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
106
-
107
- | 智能体 | 用户级目录 | 项目级目录 |
108
- |---|---|---|
109
- | Codex | %USERPROFILE%\.codex\skills\yotta-guardian\ | .codex\skills\ |
110
- | Claude Code | %USERPROFILE%\.claude\skills\yotta-guardian\ | .claude\skills\ |
111
- | Cursor | %USERPROFILE%\.cursor\skills\yotta-guardian\ | .cursor\skills\ |
112
- | Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-guardian\ | .windsurf\skills\ |
113
- | opencode | %USERPROFILE%\.config\opencode\skills\yotta-guardian\ | .opencode\skills\ |
114
- | Gemini | %USERPROFILE%\.gemini\skills\yotta-guardian\ | .gemini\skills\ |
115
- | Goose | %USERPROFILE%\.config\goose\skills\yotta-guardian\ | .goose\skills\ |
116
- | Amp | %USERPROFILE%\.config\agents\skills\yotta-guardian\ | .agents\skills\ |
117
- | Kiro | %USERPROFILE%\.kiro\skills\yotta-guardian\ | .kiro\skills\ |
118
- | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-guardian\ | .workbuddy\skills\ |
119
- | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-guardian\ | .traecli\skills\ |
120
- | Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-guardian\ | .trae\skills\ |
121
- | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-guardian\ | .qwen\skills\ |
122
- | Comate | %USERPROFILE%\.comate\skills\yotta-guardian\ | .comate\skills\ |
123
- | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-guardian\ | .codebuddy\skills\ |
124
- | Kimi | %USERPROFILE%\.kimi\skills\yotta-guardian\ | .kimi\skills\ |
125
- | 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-guardian\ | .agents\skills\ |
126
-
127
- > Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
84
+ 以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
128
85
 
86
+ ### 方式一：npm 一行装（推荐）
87
+
88
+ ```text
89
+ # 可选国内加速：npm config set registry https://registry.npmmirror.com
90
+ npx -y @yottameta/yotta-guardian --agent <智能体名称> # 装到指定智能体默认用户级技能目录
91
+ npx -y @yottameta/yotta-guardian --dir <智能体的技能目录> # 指到技能目录本身（如 ~/.codex/skills）
92
+ ```
93
+
94
+ - `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
95
+ - `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
96
+ - npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
97
+
98
+ ### 方式二：git clone（开发者 / 有 git 环境）
99
+
100
+ ```text
101
+ git clone https://github.com/YottaMeta/yotta-guardian.git <智能体的技能目录>/yotta-guardian
102
+ ```
103
+
104
+ ### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
105
+
106
+ 在 GitHub 仓库 `YottaMeta/yotta-guardian` 点 **Code → Download ZIP**，解压后把 `yotta-guardian` 文件夹放进智能体技能目录。
107
+
108
+ ### 方式四：install.sh（多智能体一键脚本）
109
+
110
+ ```text
111
+ bash install.sh --agent <name> # 装到指定智能体默认用户级目录
112
+ bash install.sh --dir <path> # 装到指定目录
113
+ bash install.sh --list # 列出智能体 -> 默认目录
114
+ ```
115
+
116
+ > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
129
117
  ## 使用示例（AI 智能体）
130
118
 
131
119
  1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
132
120
  2. 在执行任何高风险工具调用前，先跑一次 check：
133
- `````bash
121
+ ```bash
134
122
  python3 scripts/yotta_guardian.py check exec --cmd "<待执行命令>" --json
135
- `````
123
+ ```
136
124
  退出码 2 / 3 时不要执行，向用户说明命中规则；确有授权再用 --allow / --allow-path / 自定义规则放行。
137
125
  3. 一次要执行多条时，用 --batch 批量预检：
138
- `````bash
126
+ ```bash
139
127
  python3 scripts/yotta_guardian.py check --batch calls.json --json
140
- `````
128
+ ```
141
129
  4. 写敏感路径 / 修改系统配置前，用 write / edit 检查目标路径与内容。
142
130
  5. 高风险操作落审计日志，事后用 audit 查询。
143
131
 
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yotta-guardian
3
- version: 0.1.1
3
+ version: 0.1.3
4
4
  description: 元盾 —— 跨智能体的危险调用拦截护栏：确定性规则引擎 + 可插拔意图验证（不绑模型），拦截危险 exec / write / edit / read / run / shell 工具调用，提供审计日志。触发：代理要执行高风险命令（递归删除、磁盘格式化、提权、防火墙改动、反向 shell、下载即执行等）、要写入系统敏感路径或修改系统配置、要在执行危险操作前做安全检查、或用户说 护栏/拦截/危险操作/安全检查 等。边界：默认只读评估，不自动执行也不放行危险操作；不替代用户决策；不隐藏审计记录；规则可配置。
5
5
  license: MIT
6
6
  ---
@@ -72,6 +72,8 @@ python3 scripts/yotta_guardian.py audit --file .yotta-guardian/audit.jsonl --tai
72
72
  - references/policies.md — 策略 / 退出码 / 使用姿势
73
73
  - references/intent-verifier.md — 意图验证器协议
74
74
 
75
- ## 责任声明
75
+ ## 使用范围、授权与法律红线
76
76
 
77
- 本技能用于防止误操作与提升操作透明度，不替代人工决策。执行危险操作前请自行确认授权与合规。
77
+ - **范围**：本技能只对工具调用做执行前风险评估，并输出 allow / deny 与审计记录；它不是操作系统沙箱，不执行、不放行、不修改目标系统，也不替代宿主自身的权限控制。
78
+ - **授权**：仅用于你拥有或已获得明确授权的系统、账户与数据。被拒绝的操作必须由有权限的人确认；显式放行只用于已确认的合法运维场景。
79
+ - **法律与合规红线**：不得用于未授权访问、破坏、规避安全控制或其他违法用途；使用者应遵守适用法律、监管要求与组织安全政策。评估结果只作为决策辅助，最终责任由操作者承担。