algorismo-au/lanekeep

English · 简体中文 · 日本語 · Español · 한국어 · Português · Deutsch · Français · Русский · Türkçe · العربية · Tiếng Việt · Italiano · हिन्दी

_{由 Algorismo 构建}

# LaneKeep AI 编程智能体常常会执行 `rm -rf`、读取 `.env` 文件、推送到错误的分支，并在失控的循环中大量消耗 token。**LaneKeep 会拦截每一次工具调用，并在它们执行前强制执行确定性的规则。** **171 条默认规则 · 12 个评估器 · 零网络调用 · Apache 2.0** - **实时面板：** 每一项决策都在本地记录 - **预算限制：** 使用模式、成本上限、token 和操作限制 - **完整审计追踪：** 每次工具调用都会记录匹配的规则和原因 - **深度防御：** 可扩展的策略层：12 个确定性评估器以及一个可选的语义层（另一个 LLM）作为评估器；PII 检测、配置完整性检查和注入检测 - **智能体记忆/知识视图：** 查看你的智能体所见的内容 - **覆盖范围与一致性：** 内置合规标签（NIST、OWASP、CWE、ATT&CK）；你也可以添加自己的标签 - **数据绝不离开你的机器。** 每一项策略和规则都由你掌控。 支持在 Linux、macOS 和 Windows（通过 WSL 或 Git Bash）上运行 Claude Code CLI。其他平台即将推出。 欲了解更多详情，请参阅[配置](#configuration)。

## 快速开始 ### 前置条件 | 依赖 | 必需 | 备注 | |------------|----------|-------| | **bash** >= 4 | 是 | 核心运行时 | | **jq** | 是 | JSON 处理 | | **socat** | 用于 sidecar 模式 | 在仅 hook 模式下不需要 | | **Python 3** | 可选 | Web 面板 (`lanekeep ui`) | ``` sudo apt install jq socat # Debian/Ubuntu brew install bash jq socat # macOS (bash 4+ required) sudo apt install jq socat # Windows (inside WSL) ``` ### 安装 ``` git clone https://github.com/algorismo-au/lanekeep.git cd lanekeep ``` 将 `bin/` 永久添加到你的 PATH 中： ``` bash scripts/add-to-path.sh ``` 此操作会检测你的 shell 并写入到你的 rc 文件中。该操作是幂等的。 或者仅对当前会话生效： ``` export PATH="$PWD/bin:$PATH" ``` 无需构建步骤。纯 Bash 编写。 ### 1. 尝试演示 ``` lanekeep demo ``` ``` DENIED rm -rf / Recursive force delete DENIED DROP TABLE users SQL destruction DENIED git push --force Dangerous git operation ALLOWED ls -la Safe directory listing Results: 4 denied, 2 allowed ``` ### 2. 在你的项目中安装 ``` cd /path/to/your/project lanekeep init . ``` 创建 `lanekeep.json`、`.lanekeep/traces/`，并在 `.claude/settings.local.json` 中安装 hooks。 ### 3. 启动 LaneKeep ``` lanekeep start # sidecar + web dashboard lanekeep serve # sidecar only # 或跳过两者 — hooks 内联评估（较慢，无后台进程） ``` ### 4. 正常使用你的智能体 被拒绝的操作会显示原因。允许的操作将静默执行。在 **[面板](#dashboard)** (`lanekeep ui`) 中查看决策，或者在终端中使用 `lanekeep trace` / `lanekeep trace --follow` 查看。 | | | |:---:|:---:| | | | | | | | | | ## 管理 LaneKeep ### 启用与禁用 `lanekeep init` 会自动注册 hooks，但你也可以独立管理 hook 的注册： ``` lanekeep enable # Register hooks in Claude Code settings lanekeep disable # Remove hooks from Claude Code settings lanekeep status # Check if LaneKeep is active and show governance state ``` **在 `enable` 或 `disable` 后重启 Claude Code 以使更改生效。** `enable` 会将三个 hooks（PreToolUse、PostToolUse、Stop）写入你的 Claude Code 设置文件：如果项目本地的 `.claude/settings.local.json` 存在则写入该文件，否则写入 `~/.claude/settings.json`。`disable` 会将它们干净地移除。 ### 启动与停止 仅使用 Hooks 也能工作：每个工具调用都会在行内进行评估。Sidecar 增加了一个 常驻后台进程，用于更快的评估和提供 Web 面板： ``` lanekeep start # Sidecar + web dashboard (recommended) lanekeep serve # Sidecar only (no dashboard) lanekeep stop # Shut down sidecar and dashboard lanekeep status # Check running state ``` ### 暂时禁用 LaneKeep 这里有两个级别的“禁用”： | 范围 | 命令 | 作用 | |-------|---------|-------------| | **整个系统** | `lanekeep disable` | 移除所有 hooks。停止任何评估。重启 Claude Code。 | | **单个策略** | `lanekeep policy disable --reason "..."` | 禁用单个策略类别（例如 `governance_paths`），同时保持其他所有策略继续执行。 | 要暂停单个策略并重新启用它： ``` lanekeep policy disable governance_paths --reason "Updating CLAUDE.md" # ... 进行更改 ... lanekeep policy enable governance_paths ``` 要完全禁用 LaneKeep 并将其恢复： ``` lanekeep disable # Remove hooks — restart Claude Code # ... 在没有 governance 的情况下工作 ... lanekeep enable # Re-register hooks — restart Claude Code ``` ## 什么会被拦截 请参阅[配置](#configuration) 以覆盖、扩展或禁用任何内容。 | 类别 | 示例 | 决策 | |----------|----------|----------| | 破坏性操作 | `rm -rf`, `DROP TABLE`, `truncate`, `mkfs` | 拒绝 | | IaC / 云服务 | `terraform destroy`, `aws s3 rm`, `helm uninstall` | 拒绝 | | 危险的 git 操作 | `git push --force`, `git reset --hard` | 拒绝 | | 代码中的机密 | AWS 密钥、API 密钥、私钥 | 拒绝 | | 治理文件 | `claude.md`, `.claude/`, `lanekeep.json`, `.lanekeep/`, `plugins.d/` | 拒绝 | | 自我保护 | `kill lanekeep-serve`, `export LANEKEEP_FAIL_POLICY` | 拒绝 | | 网络命令 | `curl`, `wget`, `ssh` | 询问 | | 包安装 | `npm install`, `pip install` | 询问 | ### 自我保护 LaneKeep 会保护自身及智能体自身的治理文件，防止其受到所管理的智能体的修改。 如果没有这一点，被入侵或遭到 prompt 注入的智能体可能会禁用强制执行、 篡改审计日志或绕过预算限制。 | 路径 | 保护内容 | |------|-----------------| | `claude.md`, `.claude/` | Claude Code 指令、设置、hooks、记忆 | | `lanekeep.json`, `.lanekeep/` | LaneKeep 配置、规则、追踪、运行时状态 | | `lanekeep/bin/`, `lib/`, `hooks/` | LaneKeep 源代码 | | `plugins.d/` | 插件评估器 | **写入**操作会被 `governance_paths` 策略（Write/Edit 工具）拦截。 对活动配置（`lanekeep.json`，`.lanekeep/` 状态文件）的**读取** 会被规则 `sec-039` 和 `sec-040` 拦截。暴露规则集会让 智能体逆向工程匹配模式并精心构造规避方法。LaneKeep 源 代码（`bin/`，`lib/`）仍然可读；引擎的安全性是公开的，但 受管智能体无法看到活动配置。详情请参阅 [REFERENCE.md](REFERENCE.md#self-protection-governance_paths--rules)。 ## 工作原理 它会挂载到 [PreToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) 中，并在每次工具调用执行前通过分层流水线运行。遇到第一个拒绝就会停止流水线。 | 层级 | 评估器 | 检查内容 | |------|-----------|----------------| | 0 | 配置完整性 | 启动后配置哈希值未改变 | | 0.5 | Schema | 工具与 TaskSpec 允许/拒绝列表对比 | | 1 | 硬阻断 | 快速子串匹配；总是运行 | | 2 | 规则引擎 | 策略，先匹配先生效规则 | | 3 | 隐藏文本 | CSS/ANSI 注入、零宽字符 | | 4 | 输入 PII | 工具输入中的 PII（社会安全号码、信用卡） | | 5 | 预算 | 操作数、token 跟踪、成本限制、实际运行时间 | | 6 | 插件 | 自定义评估器（子 shell 隔离） | | 7 | 语义 | LLM 意图检查：目标不一致、任务本质违规、伪装的数据外泄（可选启用） | | 后置 | 结果转换 | 输出中的机密/注入 | 语义评估器从 TaskSpec 读取任务目标。可以通过 `lanekeep serve --spec DESIGN.md` 设置，或者直接编写 `.lanekeep/taskspec.json`。 详情请参阅 [REFERENCE.md](REFERENCE.md#budget--taskspec)。 有关详细的层级描述和数据流，请参阅 [CLAUDE.md](CLAUDE.md)。 ## 核心概念 | 术语 | 是什么 | |------|------------| | **事件** | 原始的工具调用发生：每次触发 hook（`PreToolUse` 或 `PostToolUse`）产生一条记录。无论结果如何，`total_events` 总是会增加。 | | **评估** | 流水线中的单项检查。每个评估器模块（`eval-hardblock.sh`、`eval-rules.sh`、`eval-budget.sh` 等）独立检查事件并设置 `EVAL_PASSED`/`EVAL_REASON`。单个事件会触发多次评估；结果记录在追踪的 `evaluators[]` 数组中，包含 `name`、`tier` 和 `passed`。 | | **决策** | 最终的流水线判定结果：`allow`（允许）、`deny`（拒绝）、`warn`（警告）或 `ask`（询问）。存储在每个追踪条目的 `decision` 字段中，并在累计指标的 `decisions.deny / warn / ask / allow` 中统计。 | | **操作** | 工具实际执行的事件（`allow` 或 `warn`）。被拒绝和待询问（pending-ask）的调用不计入。`action_count` 是 `budget.max_actions` 测量的内容；当达到上限时，预算评估器将开始拦截。 | ``` Event (raw hook call) └── Evaluations (N checks run against it) └── Decision (single verdict: allow/deny/warn/ask) └── Action (only if tool actually ran; counts against max_actions) ``` ## 配置 一切皆可配置：内置默认规则、用户定义的规则以及社区提供的包，都会合并到一个策略中。你可以覆盖任何默认规则、添加自己的规则，或禁用不需要的规则。 配置解析顺序：`$PROJECT_DIR/lanekeep.json` -> `$LANEKEEP_DIR/defaults/lanekeep.json`。 配置在启动时进行哈希校验；会话期间的修改将拒绝所有调用。 ### 策略 在规则之前进行评估。内置 20 个类别，每个类别都有专用的提取 逻辑（例如 `domains` 解析 URL，`branches` 提取 git 分支名称）。 类别：`tools`、`extensions`、`paths`、`commands`、`domains`、 `mcp_servers` 等等。可以通过 `lanekeep policy` 或面板的 **Governance** 标签页进行切换。 **策略与规则的对比：** 策略是针对预定义 类别的结构化、有类型的控制。规则是灵活的兜底方案：它们将任何工具名称 + 任何 正则表达式模式与完整的工具输入进行匹配。如果你的使用场景不符合某个策略 类别，请改为编写规则。 要临时禁用某个策略（例如为了更新 `CLAUDE.md`）： ``` lanekeep policy disable governance_paths --reason "Updating CLAUDE.md" # ... 进行更改 ... lanekeep policy enable governance_paths ``` ### 规则 有序的匹配先生效表。未匹配 = 允许。匹配字段使用 AND 逻辑。 ``` [ {"match": {"command": "rm", "target": "node_modules"}, "decision": "allow"}, {"match": {"command": "rm -rf"}, "decision": "deny"} ] ``` 你不需要复制全部默认值。使用 `"extends": "defaults"` 并添加你的规则： ``` { "extends": "defaults", "extra_rules": [ { "id": "my-001", "match": { "command": "docker compose down" }, "decision": "deny", "reason": "Block tearing down the dev stack" } ] } ``` `extra_rules` 会被**前置**到已解析的规则集中，因此在先匹配先生效的原则下，它们会优先于重叠的默认规则生效。要按 id 修补或禁用默认规则（无需复制它），请使用 `overrides` 块 — 详见 REFERENCE.md § 自定义默认规则。 或者使用 CLI： ``` lanekeep rules add --match-command "docker compose down" --decision deny --reason "..." ``` 也可以在面板的 **Rules** 标签页中添加、编辑和试运行规则，或者先从 CLI 进行测试： ``` lanekeep rules test "docker compose down" ``` ### 更新 LaneKeep 当你安装新版本的 LaneKeep 时，新的默认规则会自动变为活动状态。**你的自定义项（`extra_rules`、`rule_overrides`、`disabled_rules`）绝不会被触碰。** 在升级后首次启动 sidecar 时，你会看到一个一次性通知： ``` [LaneKeep] Updated: v1.2.0 → v1.3.0 — 8 new default rule(s) now active. [LaneKeep] Run 'lanekeep rules whatsnew' to review. Your customizations are preserved. ``` 要确切查看发生了什么变化： ``` lanekeep rules whatsnew # 显示带有 IDs、decisions 和 reasons 的新增/移除 rules lanekeep rules whatsnew --skip net-019 # Opt out of a specific new rule lanekeep rules whatsnew --acknowledge # Record current state (clears future notices) ``` ### 强制执行配置文件 | 配置文件 | 行为 | |---------|----------| | `strict` | 拒绝 Bash，询问 Write/Edit。500 次操作，2.5 小时。 | | `guided` | 询问 `git push`。2000 次操作，10 小时。**(默认)** | | `autonomous` | 宽松，仅预算 + 追踪。5000 次操作，20 小时。 | 通过 `LANEKEEP_PROFILE` 环境变量或 `lanekeep.json` 中的 `"profile"` 进行设置。 有关规则字段、策略类别、设置 和环境变量，请参阅 [REFERENCE.md](REFERENCE.md)。 ## CLI 参考 完整命令列表请参阅 [REFERENCE.md: CLI 参考](REFERENCE.md#cli-reference)。 ## 面板 在智能体构建时准确查看它在做什么：实时决策、token 使用情况、文件活动和审计追踪，尽在一处。 ### 治理 实时的输入/输出 token 计数器、上下文窗口使用率 (%) 和预算进度条。在会话偏离正轨并浪费时间和金钱之前将其揪出。为操作、token 和时间设置硬性上限，达到上限时自动强制执行。

### 洞察 实时决策流、拒绝趋势、按文件划分的活动、延迟百分位数，以及贯穿整个会话的决策时间线。

### 审计与覆盖范围 一键验证配置，此外还有一个将规则与监管框架（PCI-DSS、HIPAA、GDPR、NIST SP800-53、SOC2、OWASP、CWE、AU 隐私法案）相关联的覆盖范围映射图，并提供差距高亮和规则影响分析。

### 文件 你的智能体读取或写入的每一个文件，包含每个文件的 token 大小，以便了解是什么消耗了你的上下文窗口。此外还有操作计数、拒绝历史记录和内联编辑器。

### 设置 从面板配置强制执行配置文件、切换策略和调整预算限制。更改立即生效，无需重启 sidecar。

## 安全性 **LaneKeep 完全在你的机器上运行。没有云端，没有遥测，无需注册账号。** - **配置完整性：** 在启动时进行哈希校验；会话期间的更改将拒绝所有调用 - **故障关闭：** 任何评估错误都会导致拒绝 - **不可变的 TaskSpec：** 会话契约在启动后无法更改 - **插件沙箱：** 子 shell 隔离，无权访问 LaneKeep 内部组件 - **仅追加审计：** 智能体无法修改追踪日志 - **无网络依赖：** 纯 Bash + jq，没有供应链风险 ### 追踪隐私 在写入之前，`.lanekeep/traces/` 下的 JSONL 追踪文件会对机密进行脱敏。评估 流水线仍然能看到原始的工具输入 — 只有持久化 的记录会被清理。 - 工具输入中的 **`...` 信封** 被替换为 `[REDACTED:private]`。包裹敏感的文本内容，即可在不 禁用追踪的情况下将其排除在审计追踪之外。 - **键名以 `_KEY` / `_TOKEN` / `_SECRET` / `_PASSWORD` 结尾的 JSON 值**（不区分大小写）被替换为 `[REDACTED:keyname]`。 - AWS 访问密钥、GitHub token、Anthropic / `sk-` 密钥以及 `Bearer …` 标头会被模式匹配并替换为 `[REDACTED:]`。 完整的占位符映射请参阅 [REFERENCE.md § 追踪隐私](REFERENCE.md#trace-privacy)。 漏洞报告请参阅 [SECURITY.md](SECURITY.md)。 ## 开发 有关架构和约定，请参阅 [CLAUDE.md](CLAUDE.md)。使用 `bats tests/` 或 `lanekeep selftest` 运行测试。包含 Cursor 适配器（未经测试）。 ## 许可证 [Apache License 2.0](LICENSE) ## 关键词 AI 智能体护栏，AI 智能体治理，AI 编程智能体安全，代理式 AI 安全，随性编程安全，AI 智能体策略引擎，治理 sidecar，AI 智能体防火墙，AI 智能体审计追踪，AI 智能体最小权限，AI 智能体 沙箱，prompt 注入防护，MCP 安全，MCP 护栏，Claude Code 安全，Claude Code 护栏，Claude Code hooks，Cursor 护栏， Copilot 治理，Aider 护栏，AI 智能体监控，AI 智能体 可观测性，AI 编程助手安全性，策略即代码，治理即代码， AI 智能体运行时安全，AI 智能体访问控制，AI 智能体权限，AI 智能体允许列表拒绝列表，OWASP 代理式 Top 10，NIST AI 风险管理，SOC2 AI 合规，HIPAA AI 合规，欧盟 AI 法案合规工具，PII 检测， 机密检测，AI 智能体预算限制，token 预算强制执行，AI 智能体 成本控制，影子 AI 治理，AI 开发护栏，DevSecOps AI，AI 智能体命令拦截，AI 智能体文件访问控制，AI 深度防御，零 信任 AI 智能体，故障关闭安全性，仅追加审计日志，确定性 护栏，规则引擎 AI，合规自动化 AI，AI 智能体行为 监控，AI 智能体风险管理，开源 AI 治理，CLI 护栏 工具，基于 shell 的策略引擎，无云 AI 安全，零网络调用，AI 编程工具审计日志

### 有兴趣与我们共同构建吗？

联系我们 → info@algorismo.com · algorismo.com

标签：AI治理, AI编程助手, Bash, SOC Prime, 代理监督, 多包管理, 应用安全, 开发工具