agentsh

macOS 注意： 通过 ESF（端点安全框架）+ NE（网络扩展）实现的原生 macOS 强制执行功能目前处于 Alpha 阶段。它可以端到端工作——文件、进程和网络事件通过系统扩展流向 Go 策略引擎——但预期会存在粗糙的边缘以及版本间的破坏性变更。对于当前的生产环境使用，我们推荐使用 Linux。

Windows 注意： 我们正在努力完成微筛选器驱动程序的签名。在此之前，仅完全支持 Windows WSL2 模式用于生产环境。

面向 AI 代理的安全、策略强制的执行网关。

agentsh 位于你的代理/工具链之下——拦截文件、网络、进程和信号活动（包括子进程树），强制执行你定义的策略，并发出结构化审计事件。

平台说明： Linux 提供完全强制（100% 安全评分）。macOS ESF+NE（90% 评分）处于 Alpha 阶段——功能可用但尚未达到生产就绪。Windows WSL2 提供等效于 Linux 的完全强制（100% 评分）；原生 Windows 通过微筛选器驱动 + AppContainer（85% 评分）有待驱动签名。详见平台对比矩阵。

agentsh 是什么？

即插即用的 shell/执行端点，将每个命令（及其子进程）转化为可审计事件。
按操作定义的策略引擎：allow（允许）、deny（拒绝）、approve（需人工确认）、soft_delete（软删除）或 redirect（重定向）。
完整的 I/O 可见性：
- 文件打开/读取/写入/删除
- 网络连接 + DNS
- 进程启动/退出
- PTY 活动
- 包含 DLP 和使用追踪的 LLM API 请求
- 通过声明的 db_services 实现的 Postgres 系列数据库流量
- 信号发送/阻塞（Linux 强制执行，macOS/Windows 审计）
- 通过嵌入式 PostgreSQL 代理 实现的数据库查询——按语句分类和执行策略
- 通过声明的服务（http_services）路由出站 HTTP API 调用，支持按方法、按路径规则、批准门控和失败关闭的主机强制执行
两种输出模式：
- 人类友好的 shell 输出
- 面向代理/工具的紧凑 JSON 响应

为什么选择 agentsh？

代理工作流最终会执行任意代码（pip install、make test、python script.py）。传统的“执行命令前请求批准”控制止步于工具边界，无法看到该命令内部发生的情况。

agentsh 在运行时强制执行策略，因此子进程执行的隐藏工作仍然受到管控、记录，并在需要时获得批准。

有意义的阻止：拒绝 → 重定向（“引导”超能力）

大多数系统只能拒绝一个操作。agentsh 还可以重定向它。

这意味着当代理尝试错误的方法（或暴力破解的变通方案）时，策略可以将其引导至正确的路径——通过交换命令并返回指导——使代理保持在预设轨道上，减少无效重试。

示例：将 curl 重定向到经过审计的包装器```yaml command_rules:

name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**示例：将写入工作区外的操作重定向回内部**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

代理看到的是成功操作（而非错误），但你实际控制数据最终落地的位置。

容器 + agentsh：强强联合

容器隔离了主机面，而 agentsh 提供了容器内部的运行时可见性与策略。

每次操作审计（文件、网络、命令）展示安装/构建/测试期间发生的一切。
审批与规则在长生命周期 shell 和子进程树中持续生效——而不仅限于第一条命令。
对挂载的工作区/缓存/凭证提供路径级控制；容器原生无法提供如此细粒度。
在主机与容器内行为一致，因此 CI 和本地开发看到相同的策略结果。

快速开始

安装

macOS（Homebrew）```bash brew tap canyonroad/tap brew install --cask agentsh

这会安装包含 ESF+NE 系统扩展的 AgentSH 应用包。安装后，你将需要在**系统设置 > 通用 > 登录项与扩展**中批准该系统扩展。

**Linux（从 GitHub 发布版）**

从[发布页面](https://github.com/erans/agentsh/releases)下载适用于你平台的 `.deb`、`.rpm` 或 `.apk`。```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

来自源码（Linux）```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**从源代码 (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

参见 macOS Build Guide 获取详细的 macOS 构建说明。

本地运行```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---

### 检查实际强制的内容

`agentsh detect` 探测主机并报告哪些强制原语实际可用 —— seccomp、Landlock、FUSE、eBPF、ptrace、cgroups —— 按每个域的保护评分分组，再加上所选的安全模式。在受限主机（Daytona、E2B、Firecracker 类）上，如果 seccomp user-notify listener 无法安装，它会报告 *实际* 强制执行的模式，而不仅仅是内核所支持的模式。```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

请参阅安全模式了解模式矩阵和调节参数。

告诉您的代理使用它（AGENTS.md / CLAUDE.md 片段）```md

Shell access

Run commands via agentsh, not directly in bash/zsh.
Use: agentsh exec $SID -- <your-command-here>
For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### 自动启动（无需手动守护进程步骤）

你**不需要**自己启动 `agentsh server`。

* 首次执行 `agentsh exec`（或任何被拦截的 `/bin/sh`/`/bin/bash`）将自动使用 `configs/server-config.yaml`（或 `AGENTSH_CONFIG` 如果已设置）启动一个本地服务器。
* 该服务器在会话生命周期内保持 FUSE 层和策略引擎运行；后续命令会复用该服务器。
* 如果你希望手动管理服务器生命周期，请设置 `AGENTSH_NO_AUTO=1`。

---

## 在 Docker 中使用（带 Shell 拦截）

参见 `Dockerfile.example`，获取基于 Debian 的最小镜像示例。

在镜像内部，安装发布包（或复制你的构建产物），然后激活拦截：```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

将垫片指向您的服务器（边车或主机）：```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

现在容器中的任何 `/bin/sh -c ...` 或 `/bin/bash -lc ...` 都会通过 agentsh 路由。

### 非交互式执行

默认情况下，当标准输入不是 TTY 时，shim 会绕过策略（以保留管道命令的二进制数据）。在命令始终是非交互式但仍需执行策略的平台上（例如 exe.dev、sandbox API），请添加 `--force`：```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

这将写入 /etc/agentsh/shim.conf 并设置 force=true，shim 在启动时会读取该配置。无论 shell 是如何生成的（与环境变量或 profile 脚本不同），该配置文件始终有效。在进程环境中设置 AGENTSH_SHIM_FORCE=1 可达到相同的逐进程效果。

推荐模式： 在同一个 Pod/Service 中以 sidecar（或 PID 1）方式运行 agentsh，并共享一个工作区卷；shim 确保每一次 shell 跳转都保持在策略管控之下。

策略模型

决策

allow
deny
approve（人工批准）
redirect（替换命令）
audit（允许 + 记录）
soft_delete（隔离删除并支持恢复）

范围

文件操作
命令
环境变量
网络（DNS/连接）
数据库（通过 PostgreSQL 代理的 SQL 语句）
PTY/会话设置
声明的 HTTP 服务

评估

首个匹配的规则生效

规则位于命名的策略中；会话选择某个策略。

默认值：

示例配置：configs/server-config.yaml
默认策略：configs/policies/default.yaml
环境变量覆盖：将 AGENTSH_POLICY_NAME 设置为允许的策略名称（无后缀）。如果未设置/无效/不允许，则使用默认策略。
环境策略：在策略文件中配置 policies.env_policy（allow/deny、max_bytes、max_keys、block_iteration）和每个命令的 env_* 覆盖。空允许列表默认为最小的 PATH/LANG/TERM/HOME 并包含内置的拒绝列表；设置 block_iteration 以隐藏环境变量迭代（需要环境 shim）。
允许列表：在 config.yml 中配置 policies.allowed；空值表示仅允许默认策略。
可选完整性检查：设置 policies.manifest_path 为 SHA256 清单，以便在加载策略文件时进行验证。

环境策略快速参考

默认行为： 如果没有 env_allow，agentsh 会构建一个最小的环境（PATH/LANG/TERM/HOME）并移除内置的密钥。
覆盖： 每个命令的 env_allow/env_deny 以及 env_max_keys/env_max_bytes 在执行时限制并过滤子进程环境。
阻止迭代： env_block_iteration: true（全局或每条规则）隐藏环境枚举；设置 policies.env_shim_path 为 libenvshim.so，以便 agentsh 注入 LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1。
限制： 超出限制时会报错；环境构建器在每个命令执行前应用。
env_inject： 操作员信任的环境变量注入到所有命令中，绕过策略过滤。主要用途：BASH_ENV 用于禁用绕过 seccomp 的 shell 内建命令。在 sandbox.env_inject（全局）或策略级别的 env_inject（覆盖全局）中配置。

示例规则（已精简）```yaml

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

---

### 使用策略```bash
# Start the server with your policy
./bin/agentsh server --config configs/server-config.yaml

# Create a session pinned to a policy
SID=$(./bin/agentsh session create --workspace /workspace --policy default --json | jq -r .id)

# Exec commands; responses include decision + guidance when blocked/approved
./bin/agentsh exec "$SID" -- rm -rf /workspace/tmp

认证

agentsh 支持多种认证方法：

类型	使用场景
`api_key`	简单部署，使用静态密钥
`oidc`	企业SSO（Okta、Azure AD等）
`hybrid`	两种方法都接受

审批模式：用于人工参与的验证：

local_tty - 终端提示（默认）
totp - 认证器应用代码
webauthn - 硬件安全密钥（YubiKey）
api - 通过REST远程审批

参见 SECURITY.md 了解配置详情。

MCP 安全

工具白名单：通过允许列表/拒绝列表策略控制可调用的MCP工具
版本锁定：检测工具定义变更（防止恶意替换），并配置响应策略
跨服务器检测：阻止数据外泄模式（从服务器A读取→通过服务器B发送）
速率限制：对MCP服务器和网络域使用令牌桶速率限制

参见 SECURITY.md 获取完整配置选项，或运行 MCP 保护演示 查看这些检测的实际效果。

60秒演示

最快"理解"它的方法是运行一些生成子进程并触及文件系统/网络的程序。```bash

1) Create a session in your repo/workspace

SID=$(agentsh session create --workspace . --json | jq -r .id)

2) Run something simple (human-friendly output)

agentsh exec "$SID" -- uname -a

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

agentsh exec --output json --events summary "$SID" -- curl -s https://example.com

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

agentsh exec "$SID" -- rm -rf ./tmp

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

agentsh exec --output json --events all "$SID" -- ls

→ events[] shows every file operation, even from subprocesses

**在 JSON 输出中你会看到的内容：**
- `exit_code`：命令的退出状态
- `stdout` / `stderr`：捕获的输出
- `events[]`：每个文件/网络/进程操作及其策略决策
- `policy.decision`：`allow`、`deny`、`approve` 或 `redirect`

提示：测试策略时，保持一个带有 `--output json` 的终端打开——这样可以清楚地看到哪些被触及了。

---

### 会话报告

生成总结会话活动的 Markdown 报告：```bash
# Quick summary
agentsh report latest --level=summary

# Detailed investigation
agentsh report <session-id> --level=detailed --output=report.md

Reports include:

决策摘要（已允许、已阻止、已重定向）
自动发现检测（违规、异常）
按类别划分的活动明细
完整事件时间线（详细模式）

See CI/CD 集成指南获取流水线示例。

工作区检查点

创建工作区状态的快照，以便从破坏性操作中恢复：```bash

Create a checkpoint before risky operations

agentsh checkpoint create --session $SID --workspace /workspace --reason "before cleanup"

List checkpoints for a session

agentsh checkpoint list --session $SID

Show what changed since a checkpoint

agentsh checkpoint show --session $SID --workspace /workspace --diff

Preview what rollback would restore (dry-run)

agentsh checkpoint rollback --session $SID --workspace /workspace --dry-run

Restore workspace to checkpoint state

agentsh checkpoint rollback --session $SID --workspace /workspace

Clean up old checkpoints

agentsh checkpoint purge --session $SID --older-than 24h --keep 5

**自动检查点：** 启用后，agentsh 会在风险命令（`rm`、`mv`、`git reset`、`git checkout` 等）之前自动创建检查点。在 `sessions.checkpoints.auto_checkpoint` 中配置。

有关完整配置选项，请参阅 [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback)。

---

### LLM 代理与 DLP

agentsh 包含一个嵌入式代理，它拦截来自所有智能体的 LLM API 请求：```bash
# Check proxy status for a session
agentsh proxy status <session-id>

# View LLM-specific events
agentsh session logs <session-id> --type=llm

功能：

自动路由：设置 ANTHROPIC_BASE_URL 和 OPENAI_BASE_URL，以便代理 SDK 通过代理路由
自定义提供商：路由到 LiteLLM、Azure OpenAI、vLLM 或企业网关
DLP 脱敏：PII（邮件、电话号码、API 密钥等）在到达 LLM 提供商之前被脱敏
自定义模式：定义组织特定的敏感数据模式
使用跟踪：提取并记录令牌计数以进行成本归属
审计追踪：所有请求/响应记录到会话存储

提供商配置：```yaml 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 配置：**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

参见 LLM 代理文档获取完整配置选项。

同一个代理也会分派声明的 http_services 条目 —— 即命名 API 上游，带有按方法、按路径的规则。详见声明的 HTTP 服务和 HTTP 服务食谱。

数据库访问控制（目前仅限 Postgres）

agentsh 可以通过 db_services、database_connection_rules 和 database_rules 对声明的数据库服务实施策略。当前实现仅限 Postgres 系列：PostgreSQL 是受支持的目标，Aurora Postgres 使用相同路径，Redshift/CockroachDB 被视为兼容 Postgres 的方言（beta 覆盖）。MySQL、MongoDB、Snowflake、BigQuery、Databricks、ClickHouse、MSSQL、Cassandra、Redis 和 Oracle 属于路线图项目，不支持当前运行时。

当前 Postgres 支持包括：

连接允许/拒绝/审批/审计决策。
PostgreSQL wire 协议 v3 的语句分类，包括简单查询、扩展查询、SQL 预编译语句、COPY、FunctionCall 拒绝、事务状态以及 CancelRequest 映射。
严格的按对象策略覆盖，拒绝优先。
基于目录的关系/函数选择器，用于解析对象策略。
安全的运行时 redirect，用于只读 Postgres 关系替换。
绕过检测和 CI 中的真实 Postgres Docker E2E 覆盖。

Postgres 代理运行时目前仅在 Linux 进程中运行。请使用原生 Linux、WSL2 或 Linux VM 环境进行数据库执行。

参见数据库访问控制和策略文档。

策略生成

从观察到的会话行为生成限制性策略（“先分析后锁定”工作流）：```bash

Generate policy from latest session

agentsh policy generate latest --output=ci-policy.yaml

Generate with custom name and threshold

agentsh policy generate abc123 --name=production-build --threshold=10

Quick preview to stdout

agentsh policy generate latest

生成的策略：
- 仅允许会话期间观察到的操作
- 当同一目录中存在多个文件时，将路径分组为通配符
- 将子域简化为通配符（例如 `*.github.com`）
- 标记具有参数模式的风险命令（curl、wget、rm）
- 将阻止的操作作为注释规则包含在内，以供审查

**用例：**
- **CI/CD 锁定**：对构建/测试运行进行配置分析，将未来运行锁定为该行为
- **代理沙箱**：让 AI 代理运行任务，为未来运行生成策略
- **容器配置分析**：对工作负载进行配置分析，为生产环境生成最小化策略

---

## 数据库访问（PostgreSQL）

agentsh 内置了一个 **PostgreSQL 代理**，该代理使数据库访问具有代理感知性并受策略管控。它采用 Postgres 有线协议，将每条语句分类为一系列*效果*（读取、写入、DDL、DCL、事务/会话控制、批量 `COPY`/导出等），并在转发至上游之前根据 `database_rules` 评估每个效果——因此 `UPDATE`、`DROP` 或未指定范围的 `DELETE` 会以与文件写入或网络连接相同的方式受到管控。

- **按效果、多对象评估**——规则为收集所有 / **任何拒绝即获胜**（最严格的谓词决定），而非优先匹配。
- **决策：** `allow`（允许）、`deny`（拒绝）、`approve`（需人工确认）、`audit`（审计）以及语句级 `redirect`（重定向）。
- **`require_where` 保护**——拒绝缺少 `WHERE` 子句的顶层 `UPDATE`/`DELETE`。
- **连接级规则**（`database_connection_rules`）控制哪些会话可以到达哪些声明的 `db_service`。
- **认证 + 语句审计事件**，用于每次连接和查询；语句文本日志记录可配置（`policies.db.log_statements: none | parameters_redacted | full`）。

第一阶段涵盖 PostgreSQL v3 有线协议（方言：`postgres`、`aurora_postgres`；`redshift` / `cockroachdb` 处于 Beta 阶段）。复制和 GSSAPI 加密连接默认拒绝。```yaml
database_rules:
  # normal reads + updates on the declared service
  - name: app-read-and-update
    db_service: appdb
    operations: [READ, UPDATE]
    decision: allow

  # allow UPDATE/DELETE only when scoped by a WHERE clause
  - name: app-guard-unscoped-dml
    db_service: appdb
    operations: [UPDATE, DELETE]
    require_where: true
    decision: allow

  # block schema/DDL mutations; terminate the transaction on violation
  - name: app-deny-ddl
    db_service: appdb
    operations: [CREATE, DROP, ALTER, EXPORT]
    decision: deny
    deny_mode_in_tx: terminate
    message: "appdb is read+update only. Requested: {{.Operation}}"

请参阅数据库访问控制规范以了解完整的操作分类、效果模型、连接规则以及不可避免性威胁模型。

网络重定向

agentsh 能够透明地重定向 DNS 和 TCP 连接，从而在无需修改代码的情况下，支持将 API 调用路由到企业代理或切换 AI 提供商等场景。

DNS 重定向

拦截 DNS 解析并返回配置的 IP 地址：```yaml 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 处理：```yaml
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

选项

平台支持

使用场景

API 网关路由：通过企业 LLM 网关路由 Anthropic/OpenAI 调用
提供商切换：将 Claude API 重定向到 GCP Vertex AI 或 Azure OpenAI
测试：将生产 API 重定向到模拟服务器
合规：强制所有 LLM 流量通过审计代理

信号过滤

agentsh 拦截进程间发送的信号（kill、SIGTERM 等），提供基于策略的控制，决定哪些信号可以到达哪些目标。

平台支持

信号规则示例```yaml

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 和内核线程

有关完整配置选项，请参阅[策略文档](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules)。

---

## macOS 文件 I/O 监控

在 macOS 上，agentsh 使用 Endpoint Security Framework (ESF) 监控文件 I/O，同时订阅 AUTH 和 NOTIFY 事件。跟踪的操作包括文件打开、创建、删除、重命名、写入（通过关闭-修改检测），以及在 macOS 26+ 上，通过属性更改事件进行的 chmod 和 chown。每个文件事件都通过基于 PID 的解析关联到原始会话和命令，从而在子进程树中提供完整的审计轨迹。

ESF 提供内核级别的允许/拒绝强制执行，但不支持像 Linux FUSE 那样的透明文件拦截。需要拦截的策略操作（例如 `redirect`（路径重写）和 `soft_delete`（隔离））通过“拒绝 + 指导”方式实现：操作在 ESF 级别被阻止，代理收到指令，要么使用正确的路径重试，要么确认文件受保护。有关事件流详细信息，请参阅 [macOS ESF+NE 架构文档](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md)；有关每个操作的行为，请参阅[策略文档](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf)。

---

## 入门策略包

您已拥有一个默认策略 (`configs/policies/default.yaml`)。以下这些有意见倾向的包作为单独文件提供，以便团队选择：

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: 适用于本地开发的安全策略
  * 允许工作区读写
  * 批准工作区内的删除操作
  * 拒绝 `~/.ssh/**`、`/root/.ssh/**`
  * 将网络限制为允许列表中的域名/端口

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: 适用于 CI 运行器的安全策略
  * 拒绝工作区之外的任何操作
  * 拒绝出站网络，除制品仓库外
  * 拒绝交互式 shell，除非明确允许
  * 审计所有内容（摘要事件）

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: “代理运行未知代码”模式
  * 默认拒绝 + 显式允许列表
  * 批准任何凭据/路径访问
  * 将网络工具使用重定向到内部代理/镜像
  * 对破坏性操作进行软删除，便于恢复

---

## AI 助手集成示例

用于配置 AI 编码助手以使用 agentsh 的即用型代码片段：

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - 用于 Claude Code 集成的 CLAUDE.md 代码片段
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - 用于 agentsh 集成的 Cursor 规则
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - 通用 AGENTS.md 代码片段（适用于多种 AI 工具）

> **注意：** 这些示例适用于在容器内运行 AI 代理不切实际的本地开发场景。对于生产或 CI/CD 环境，建议在已安装 shell shim 的容器中运行代理——请参阅[在 Docker 中使用](#use-in-docker-with-the-shell-shim)。

---

## 参考资料

* **MCP 保护演示:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - 跨服务器泄露检测、rug pull 阻止和策略生成的现场演示
* **安全与威胁模型:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - agentsh 防护的内容、已知限制、操作员检查清单
* **外部 KMS:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#external-kms-integration) - AWS KMS、Azure Key Vault、HashiCorp Vault、GCP Cloud KMS，用于审计完整性密钥
* 配置模板: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* 默认策略: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* 示例 Dockerfile（含 shim）: [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **策略文档:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - 策略变量、信号规则、网络重定向
* **数据库访问控制:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - 仅限 Postgres 数据库强制执行范围、策略语义、重定向行为和路线图
* **命令策略食谱:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - 如何允许新的二进制文件、何时使用 `wrap` 而非 `exec`、如何调试拒绝
* **HTTP 服务食谱:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - 通过声明式服务路由出站 HTTP API 调用并带有规则和审批门的配方
* **沙箱 SDK 集成食谱:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - Tensorlake / E2B / Modal / Daytona 的 `shim_install` 配置，其中命令作为 agentsh 服务器的兄弟进程运行
* **策略编写技能:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - 用于在 Claude Code、NanoClaw 等工具中创建和编辑策略的 AI 助手技能
* **平台对比:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - 按平台划分的功能支持、安全评分、性能
* **Bubblewrap 与 agentsh 对比:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - 与用于 Linux 容器沙箱的 Bubblewrap 的对比
* **数据库访问控制:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - PostgreSQL 代理分类、效果模型、`database_rules`、连接规则、威胁模型
* **安全模式与 `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - 执行模式、保护评分以及 `agentsh detect` 报告的内容
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - 系统调用过滤、execve 拦截和套接字族阻止
* **ptrace 模式:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - 针对受限容器的 PTRACE_SEIZE 强制执行（`attach_mode`、seccomp 预过滤器）
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - eBPF 网络跟踪与策略执行
* **LLM 代理与 DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - 嵌入式代理配置、DLP 模式、使用跟踪
* **macOS 构建指南:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - ESF+NE 构建说明
* **macOS ESF+NE 架构:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - 系统扩展、XPC 和部署细节
* **macOS XPC 沙箱:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - 针对沙箱化进程的 XPC/Mach IPC 控制
* 环境变量（所有 `AGENTSH_*` 覆盖项、自动启动开关、传输选择）: [`docs/spec.md` §15.3 "环境变量"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* 架构与数据流（FUSE + 策略引擎 + API）: 在 [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) 和 [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor) 中的内联注释
* CLI 帮助: `agentsh --help`、`agentsh exec --help`、`agentsh shim --help`

---

借助代理并在代理的帮助下创建。

`visibility`	`silent`, `audit_only`, `warn`	重定向的日志/显示方式
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	重定向失败时的处理方式
`tls_mode`	`passthrough`, `rewrite_sni`	连接重定向的 TLS 处理方式

DNS 重定向	✅ eBPF	✅ pf/代理	✅ WinDivert
连接重定向	✅ eBPF	✅ pf/代理	✅ WinDivert
SNI 重写	✅	✅	✅

Linux	是（seccomp user-notify）	是	是
macOS	否	否	是（ES）
Windows	部分	否	是（ETW）

agentsh

最受欢迎

agentsh

agentsh 是什么？

为什么选择 agentsh？

有意义的阻止：拒绝 → 重定向（“引导”超能力）

容器 + agentsh：强强联合

快速开始

安装

本地运行```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

告诉您的代理使用它（AGENTS.md / CLAUDE.md 片段）```md

Shell access

策略模型

决策

范围

评估

环境策略快速参考

示例规则（已精简）```yaml

认证

MCP 安全

60秒演示

1) Create a session in your repo/workspace

2) Run something simple (human-friendly output)

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

→ events[] shows every file operation, even from subprocesses

工作区检查点

Create a checkpoint before risky operations

List checkpoints for a session

Show what changed since a checkpoint

Preview what rollback would restore (dry-run)

Restore workspace to checkpoint state

Clean up old checkpoints

数据库访问控制（目前仅限 Postgres）

策略生成

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

网络重定向

DNS 重定向

选项

平台支持

使用场景

信号过滤

平台支持

信号规则示例```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes