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（覆盖全局）中配置。
• 示例： 参见 config.yml 和 configs/ 下的策略样本。

---

示例规则（已精简）```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 支持多种认证方法：