canyonroad/agentsh
GitHub: canyonroad/agentsh
为 AI Agent 提供运行时执行层安全防护的策略强制 Shell 网关，实现对文件、网络、进程、信号等操作的细粒度管控与全量审计。
Stars: 110 | Forks: 6
# agentsh
**为 AI agent 提供安全、策略强制的执行网关。**
agentsh 位于你的 agent/工具*之下*——拦截**文件**、**网络**、**进程**和**信号**活动（包括子进程树），强制执行你定义的策略，并发出**结构化审计事件**。
_linux_amd64.deb
```
**从源码构建 (Linux)**
```
make build
sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin
```
**从源码构建 (macOS)**
```
# FUSE-T 模式（标准模式，需要 brew install fuse-t）
CGO_ENABLED=1 go build -o bin/agentsh ./cmd/agentsh
# ESF+NE 企业模式（需要 Xcode 15+，Apple entitlements）
make build-macos-enterprise
```
详细的 macOS 构建说明请参见 [macOS 构建指南](docs/macos-build.md)。
### 本地运行
```
# 启动服务器（如果使用 autostart 则为可选）
./bin/agentsh server --config configs/server-config.yaml
# 创建 session 并运行命令（shell 输出）
SID=$(./bin/agentsh session create --workspace . | jq -r .id)
./bin/agentsh exec "$SID" -- ls -la
# 面向 agents 的结构化输出
./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com
```
### 告诉你的 agent 使用它 (AGENTS.md / CLAUDE.md 片段)
```
## Shell 访问
- Run commands via agentsh, not directly in bash/zsh.
- Use: `agentsh exec $SID -- `
- For structured output: `agentsh exec --output json --events summary $SID -- `
- Get session ID first: `SID=$(agentsh session create --workspace . | jq -r .id)`
```
### 自动启动（无需手动执行 daemon 步骤）
你**不需要**自己启动 `agentsh server`。
* 第一个 `agentsh exec`（或任何通过 shim 处理的 `/bin/sh`/`/bin/bash`）将使用 `configs/server-config.yaml`（或已设置的 `AGENTSH_CONFIG`）自动启动一个本地服务器。
* 该服务器在会话生命周期内保持 FUSE 层和策略引擎处于活动状态；后续命令将复用它。
* 如果你想手动管理 server 的生命周期，请设置 `AGENTSH_NO_AUTO=1`。
## 在 Docker 中使用（配合 shell shim）
请参阅 `Dockerfile.example` 以获取最小化的基于 Debian 的镜像。
在镜像内部，安装一个 release 包（或复制你的构建结果），然后激活 shim：
```
agentsh shim install-shell \
--root / \
--shim /usr/bin/agentsh-shell-shim \
--bash \
--i-understand-this-modifies-the-host
```
将 shim 指向你的 server（sidecar 或宿主机）：
```
ENV AGENTSH_SERVER=http://127.0.0.1:18080
```
现在，容器中的任何 `/bin/sh -c ...` 或 `/bin/bash -lc ...` 都将通过 agentsh 路由。
### 非交互式强制执行
默认情况下，当 stdin 不是 TTY 时，shim 会绕过策略（为管道命令保留二进制数据）。在那些命令始终是非交互式但仍需要强制执行策略的平台上（例如 exe.dev、sandbox API），请添加 `--force`：
```
agentsh shim install-shell \
--root / \
--shim /usr/bin/agentsh-shell-shim \
--bash \
--force \
--i-understand-this-modifies-the-host
```
这会将带有 `force=true` 的内容写入 `/etc/agentsh/shim.conf`，shim 会在启动时读取该文件。无论 shell 是如何生成的（不像环境变量或 profile 脚本），此配置文件都有效。进程环境中的 `AGENTSH_SHIM_FORCE=1` 可实现相同的按进程生效的效果。
**推荐模式：**在同一个 pod/service 中将 agentsh 作为 sidecar（或 PID 1）运行，并共享一个工作区卷；shim 可确保每一次 shell 跳转都处于策略管控之下。
## 策略模型
### 决策
* `allow`
* `deny`
* `approve` (人工放行)
* `redirect` (替换命令)
* `audit` (允许 + 记录)
* `soft_delete` (隔离删除并支持恢复)
### 作用域
* 文件操作
* 命令
* 环境变量
* 网络 (DNS/连接)
* PTY/session 设置
### 评估
* **匹配到的第一条规则生效**
规则存在于命名的策略中；会话选择一个策略。
默认值：
* 示例配置：`configs/server-config.yaml`
* 默认策略：`configs/policies/default.yaml`
* 环境变量覆盖：将 `AGENTSH_POLICY_NAME` 设置为**允许的**策略名称（无后缀）。如果未设置/无效/不允许，则使用默认值。
* 环境策略：在策略文件中配置 `policies.env_policy`（allow/deny、max_bytes、max_keys、block_iteration）以及按命令的 `env_*` 覆盖。空的 allowlist 默认为带有内置秘密拒绝列表的最小化 PATH/LANG/TERM/HOME；设置 `block_iteration` 以隐藏环境变量的遍历（需要 env shim）。
* allowlist：在 `config.yml` 中配置 `policies.allowed`；为空表示只允许默认策略。
* 可选完整性：将 `policies.manifest_path` 设置为 SHA256 清单，以便在加载时验证策略文件。
### 环境策略快速参考
- **默认值：**没有 `env_allow` 时，agentsh 会构建一个最小化的 env (PATH/LANG/TERM/HOME) 并剥离内置的 secret 密钥。
- **覆盖：**按命令的 `env_allow`/`env_deny` 以及 `env_max_keys`/`env_max_bytes` 在 exec 时限制和过滤子进程的 env。
- **阻止遍历：**`env_block_iteration: true`（全局或按规则）隐藏 env 的遍历枚举；将 `policies.env_shim_path` 设置为 `libenvshim.so`，以便 agentsh 注入 `LD_PRELOAD` + `AGENTSH_ENV_BLOCK_ITERATION=1`。
- **限制：**超过限制时将引发错误；在每次执行命令前，env 构建器都会被应用。
- **env_inject：**操作员信任的环境变量被注入到所有命令中，绕过策略过滤。主要用途：通过 `BASH_ENV` 禁用绕过 seccomp 的 shell 内建命令。在 `sandbox.env_inject`（全局）或策略级的 `env_inject`（覆盖全局）中进行配置。
- **示例：**请参阅 `config.yml` 和 `configs/` 下的策略示例。
### 示例规则（已精简）
```
version: 1
name: default
file_rules:
- name: allow-workspace
paths: ["/workspace", "/workspace/**"]
operations: [read, open, stat, list, write, create, mkdir, chmod, rename]
decision: allow
- name: approve-workspace-delete
paths: ["/workspace", "/workspace/**"]
operations: [delete, rmdir]
decision: approve
message: "Delete {{.Path}}?"
timeout: 5m
- name: deny-ssh-keys
paths: ["/home/**/.ssh/**", "/root/.ssh/**"]
operations: ["*"]
decision: deny
network_rules:
- name: allow-api
domains: ["api.example.com"]
ports: [443]
decision: allow
command_rules:
- name: block-dangerous
commands: ["rm", "shutdown", "reboot"]
decision: deny
```
### 使用策略
```
# 使用您的 policy 启动服务器
./bin/agentsh server --config configs/server-config.yaml
# 创建绑定到 policy 的 session
SID=$(./bin/agentsh session create --workspace /workspace --policy default | jq -r .id)
# 执行命令；响应在 blocked/approved 时包含 decision + guidance
./bin/agentsh exec "$SID" -- rm -rf /workspace/tmp
```
### 身份验证
agentsh 支持多种身份验证方法：
| 类型 | 使用场景 |
|------|----------|
| `api_key` | 使用静态密钥的简单部署 |
| `oidc` | 企业 SSO (Okta, Azure AD 等) |
| `hybrid` | 接受上述两种方法 |
用于人工介入 (human-in-the-loop) 验证的**审批模式**：
- `local_tty` - 终端提示（默认）
- `totp` - 身份验证器应用代码
- `webauthn` - 硬件安全密钥 (YubiKey)
- `api` - 通过 REST 进行远程审批
详情请参见 [SECURITY.md](SECURITY.md)。
### MCP 安全
- **工具白名单**：通过白名单/黑名单策略控制可以调用哪些 MCP 工具
- **版本锁定**：检测工具定义的变更（防范 rug pull 攻击）并提供可配置的响应
- **跨服务器检测**：阻止数据外发模式（从服务器 A 读取 -> 通过服务器 B 发送）
- **速率限制**：针对 MCP 服务器和网络域名的令牌桶速率限制
完整的配置选项请参见 [SECURITY.md](SECURITY.md)，或运行 **[MCP 防护演示](https://github.com/canyonroad/agentsh-mcp-protection-demo)** 以查看这些检测的实际运行情况。
## 60 秒演示
“理解它”的最快方式是运行一些会生成子进程并涉及文件系统/网络的操作。
```
# 1) 在您的 repo/workspace 中创建 session
SID=$(agentsh session create --workspace . | jq -r .id)
# 2) 运行一些简单的命令（人类易读的输出）
agentsh exec "$SID" -- uname -a
# → 打印系统信息，与正常情况一样
# 3) 运行访问网络的命令（JSON 输出 + event 摘要）
agentsh exec --output json --events summary "$SID" -- curl -s https://example.com
# → JSON 响应包含：exit_code、stdout 和 events[]，显示 dns_query + net_connect
# 4) 触发 policy decision - 尝试删除某些内容
agentsh exec "$SID" -- rm -rf ./tmp
# → 使用 default policy：根据您的规则提示批准或拒绝
# 5) 查看发生了什么（结构化审计追踪）
agentsh exec --output json --events all "$SID" -- ls
# → events[] 显示每个文件操作，甚至包括来自 subprocesses 的操作
```
**你将在 JSON 输出中看到的内容：**
- `exit_code`：命令的退出状态
- `stdout` / `stderr`：捕获的输出
- `events[]`：每个带有策略决策的文件/网络/进程操作
- `policy.decision`：`allow`、`deny`、`approve` 或 `redirect`
提示：在测试策略时保持打开一个带有 `--output json` 的终端——这能让你清楚地看到触碰了哪些内容。
### 会话报告
生成汇总会话活动的 markdown 报告：
```
# 快速总结
agentsh report latest --level=summary
# 详细调查
agentsh report --level=detailed --output=report.md
```
报告包括：
- 决策汇总（允许、阻止、重定向）
- 自动发现检测（违规、异常）
- 按类别划分的活动明细
- 完整的事件时间线（详细模式）
流水线示例请参见 [CI/CD 集成指南](docs/cicd-integration.md)。
### 工作区检查点
创建工作区状态的快照，以便从破坏性操作中恢复：
```
# 在执行有风险的操作前创建 checkpoint
agentsh checkpoint create --session $SID --workspace /workspace --reason "before cleanup"
# 列出 session 的 checkpoints
agentsh checkpoint list --session $SID
# 显示自某个 checkpoint 以来的更改
agentsh checkpoint show --session $SID --workspace /workspace --diff
# 预览 rollback 将恢复的内容（dry-run）
agentsh checkpoint rollback --session $SID --workspace /workspace --dry-run
# 将 workspace 恢复到 checkpoint 状态
agentsh checkpoint rollback --session $SID --workspace /workspace
# 清理旧的 checkpoints
agentsh checkpoint purge --session $SID --older-than 24h --keep 5
```
**自动检查点：**启用后，agentsh 会在执行危险命令（`rm`、`mv`、`git reset`、`git checkout` 等）之前自动创建检查点。在 `sessions.checkpoints.auto_checkpoint` 中进行配置。
完整的配置选项请参见 [SECURITY.md](SECURITY.md#checkpoint-and-rollback)。
### LLM 代理和 DLP
agentsh 包含一个嵌入式代理，可以拦截来自 agent 的所有 LLM API 请求：
```
# 检查 session 的 proxy 状态
agentsh proxy status
# 查看特定于 LLM 的事件
agentsh session logs --type=llm
```
**功能：**
- **自动路由**：设置 `ANTHROPIC_BASE_URL` 和 `OPENAI_BASE_URL`，以便 agent SDK 通过代理进行路由
- **自定义提供商**：路由到 LiteLLM、Azure OpenAI、vLLM 或企业网关
- **DLP 脱敏**：PII（电子邮件、电话号码、API 密钥等）在到达 LLM 提供商之前会被脱敏处理
- **自定义模式**：为敏感数据定义组织特定的模式
- **使用情况追踪**：提取并记录 token 数量，用于成本归因
- **审计追踪**：所有请求/响应都记录到会话存储中
**提供商配置：**
```
proxy:
mode: embedded
providers:
anthropic: https://api.anthropic.com # Default Anthropic API
openai: https://api.openai.com # Default OpenAI API
# Or use alternative providers:
# openai: http://localhost:8000 # LiteLLM / vLLM
# openai: https://your-resource.openai.azure.com # Azure OpenAI
# anthropic: https://llm.corp.example.com # Corporate gateway
```
**DLP 配置：**
```
dlp:
mode: redact
patterns:
email: true
api_keys: true
custom_patterns:
- name: customer_id
display: identifier
regex: "CUST-[0-9]{8}"
```
完整的配置选项请参见 [LLM 代理文档](docs/llm-proxy.md)。
### 策略生成
从观察到的会话行为生成严格的策略（“先分析后锁定”工作流）：
```
# 从最新 session 生成 policy
agentsh policy generate latest --output=ci-policy.yaml
# 使用自定义名称和阈值生成
agentsh policy generate abc123 --name=production-build --threshold=10
# 输出到 stdout 的快速预览
agentsh policy generate latest
```
生成的策略：
- 仅允许在会话期间观察到的操作
- 当同一目录中有许多文件时，将路径分组成 glob 模式
- 将子域折叠为通配符（例如，`*.github.com`）
- 使用参数模式标记危险命令 (curl, wget, rm)
- 将被阻止的操作作为注释掉的规则包含在内，以供审查
**使用场景：**
- **CI/CD 锁定**：分析一次 build/test 运行，将未来的运行锁定在该行为模式上
- **Agent 沙盒化**：让一个 AI agent 运行一项任务，并为未来的运行生成策略
- **容器分析**：分析一个工作负载，为生产环境生成最小化策略
## 网络重定向
agentsh 可以透明地重定向 DNS 和 TCP 连接，支持将 API 调用路由通过企业代理或在无需代码改动的情况下切换 AI 提供商等用例。
### DNS 重定向
拦截 DNS 解析并返回配置的 IP 地址：
```
dns_redirect:
- match: "api.anthropic.com"
redirect_ip: "10.0.0.50"
visibility: audit_only
on_failure: fail_closed
- match: ".*\\.openai\\.com" # Regex pattern
redirect_ip: "10.0.0.51"
visibility: warn
```
### 连接重定向
将 TCP 连接重定向到不同的目标，并可选地进行 TLS 处理：
```
connect_redirect:
- match: "api.anthropic.com:443"
redirect_to: "vertex-proxy.internal:8443"
tls_mode: passthrough # Forward encrypted traffic unchanged
visibility: silent
- match: "api.openai.com:443"
redirect_to: "azure-proxy.internal:443"
tls_mode: rewrite_sni # Modify SNI in TLS ClientHello
rewrite_sni: "azure-openai.example.com"
visibility: audit_only
```
### 选项
|段 | 值 | 描述 |
|-------|--------|-------------|
| `visibility` | `silent`, `audit_only`, `warn` | 重定向的记录/显示方式 |
| `on_failure` | `fail_closed`, `fail_open`, `retry_original` | 如果重定向失败会发生什么 |
| `tls_mode` | `passthrough`, `rewrite_sni` | 用于连接重定向的 TLS 处理方式 |
### 平台支持
| 特性 | Linux | macOS | Windows |
|---------|-------|-------|---------|
| DNS 重定向 | ✅ eBPF | ✅ pf/proxy | ✅ WinDivert |
| 连接重定向 | ✅ eBPF | ✅ pf/proxy | ✅ WinDivert |
| SNI 重写 | ✅ | ✅ | ✅ |
### 使用场景
- **API 网关路由**：通过企业 LLM 网关路由 Anthropic/OpenAI 调用
- **提供商切换**：将 Claude API 重定向到 GCP Vertex AI 或 Azure OpenAI
- **测试**：将生产 API 重定向到模拟服务器
- **合规性**：强制所有 LLM 流量通过审计代理
## 信号过滤
agentsh 拦截进程之间发送的信号（`kill`、`SIGTERM` 等），提供基于策略的控制，决定哪些信号可以到达哪些目标。
### 平台支持
| 平台 | 阻止 | 重定向 | 审计 |
|----------|----------|----------|-------|
| Linux | 是 (seccomp user-notify) | 是 | 是 |
| macOS | 否 | 否 | 是 (ES) |
| Windows | 部分 | 否 | 是 (ETW) |
### 信号规则示例
```
signal_rules:
# Allow signals to self and children
- name: allow-self
signals: ["@all"]
target:
type: self
decision: allow
- name: allow-children
signals: ["@all"]
target:
type: children
decision: allow
# Redirect SIGKILL to graceful SIGTERM
- name: graceful-kill
signals: ["SIGKILL"]
target:
type: children
decision: redirect
redirect_to: SIGTERM
# Block fatal signals to external processes
- name: deny-external-fatal
signals: ["@fatal"]
target:
type: external
decision: deny
```
### 信号组
- `@all` - 所有信号 (1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2
### 目标类型
- `self` - 进程向自身发信号
- `children` - 直接子进程
- `descendants` - 所有后代进程
- `session` - agentsh 会话中的任何进程
- `external` - 会话之外的 PID
- `system` - PID 1 和内核线程
完整的配置选项请参见[策略文档](docs/operations/policies.md#signal-rules)。
## 入门策略包
你已经拥有一个默认策略 (`configs/policies/default.yaml`)。这些带有强烈主张的策略包作为单独的文件提供，以便团队可以挑选：
* **[`policies/dev-safe.yaml`](configs/policies/dev-safe.yaml)**：对本地开发安全
* 允许工作区读写
* 审批工作区中的删除操作
* 拒绝 `~/.ssh/**`, `/root/.ssh/**`
* 将网络限制在白名单域名/端口
* **[`policies/ci-strict.yaml`](configs/policies/ci-strict.yaml)**：对 CI 运行器安全
* 拒绝工作区之外的任何操作
* 除 artifact 注册中心外，拒绝出站网络
* 除非明确允许，否则拒绝交互式 shell
* 审计所有内容（汇总事件）
* **[`policies/agent-sandbox.yaml`](configs/policies/agent-sandbox.yaml)**："agent 运行未知代码"模式
* 默认拒绝 + 显式白名单
* 审批任何凭证/路径访问
* 将网络工具的使用重定向到内部代理/镜像
* 软删除破坏性操作以便于轻松恢复
## AI 助手集成示例
现成的代码片段，用于配置 AI 编程助手以使用 agentsh：
* **[Claude Code](examples/claude/)** - 用于 Claude Code 集成的 CLAUDE.md 片段
* **[Cursor](examples/cursor/)** - agentsh 集成的 Cursor 规则
* **[AGENTS.md](examples/agents/)** - 通用 AGENTS.md 片段（适用于多种 AI 工具）
## 参考文献
* **MCP 防护演示：**[`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - 跨服务器数据外发检测、rug pull 拦截和策略生成的实时演示
* **安全性与威胁模型：**[`SECURITY.md`](SECURITY.md) - agentsh 防护的内容、已知限制、操作员检查清单
* **外部 KMS：**[`SECURITY.md#external-kms-integration`](SECURITY.md#external-kms-integration) - 用于审计完整性密钥的 AWS KMS、Azure Key Vault、HashiCorp Vault、GCP Cloud KMS
* 配置模板：[`configs/server-config.yaml`](configs/server-config.yaml)
* 默认策略：[`configs/policies/default.yaml`](configs/policies/default.yaml)
* 示例 Dockerfile (带 shim)：[`Dockerfile.example`](Dockerfile.example)
* **策略文档：**[`docs/operations/policies.md`](docs/operations/policies.md) - 策略变量、信号规则、网络重定向
* **策略编写技能：**[`skills/`](skills/) - 用于在 Claude Code、NanoClaw 等工具中创建和编辑策略的 AI 助手技能
* **平台对比：**[`docs/platform-comparison.md`](docs/platform-comparison.md) - 按平台划分的功能支持、安全分数、性能
* **Bubblewrap 与 agentsh 对比：**[`docs/bubblewrap-vs-agentsh-comparison.md`](docs/bubblewrap-vs-agentsh-comparison.md) - 与 Bubblewrap 在 Linux 容器沙盒方面的比较
* **LLM 代理与 DLP：**[`docs/llm-proxy.md`](docs/llm-proxy.md) - 嵌入式代理配置、DLP 模式、使用情况追踪
* **macOS 构建指南：**[`docs/macos-build.md`](docs/macos-build.md) - FUSE-T 和 ESF+NE 构建说明
* **macOS ESF+NE 架构：**[`docs/macos-esf-ne-architecture.md`](docs/macos-esf-ne-architecture.md) - System Extension、XPC 和部署细节
* **macOS XPC sandbox：**[`docs/macos-xpc-sandbox.md`](docs/macos-xpc-sandbox.md) - 用于沙盒化进程的 XPC/Mach IPC 控制
* 环境变量（所有 `AGENTSH_*` 覆盖、自动启动开关、传输选择）：[`docs/spec.md` §15.3 "Environment Variables"](docs/spec.md#153-environment-variables)
* 架构与数据流 (FUSE + 策略引擎 + API)：[`configs/server-config.yaml`](configs/server-config.yaml) 和 [`internal/netmonitor`](internal/netmonitor) 中的内联注释
* CLI 帮助：`agentsh --help`, `agentsh exec --help`, `agentsh shim --help`
在 agent 的帮助下为 agent 而创。
标签：AI代理, AI安全, Chat Copilot, DLP, DNS 解析, Docker镜像, EVTX分析, IP 地址批量处理, JSONLines, Lerna, Python, RASP, Shell审计, Streamlit, 命令重定向, 大语言模型安全, 子进程监控, 安全网关, 审计日志, 底层编程, 执行层安全, 无后门, 日志审计, 机密管理, 沙箱, 策略执行, 系统调用拦截, 网络安全, 节点安全, 访问控制, 请求拦截, 进程行为管控, 隐私保护, 零信任