本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

安全策略

受支持的版本

只有最新的次版本线会收到安全补丁。在针对较旧版本线报告漏洞之前，请先升级到当前 次版本。

报告漏洞

我们认真对待安全。如果你发现漏洞，请负责任地报告：

1. 私下联系：使用 AutomatosX 联系渠道 请求一条保密的安全报告途径。不要在公开社区消息中包含利用细节或凭据。
2. Discord：在我们的 Discord 中报告：https://discord.gg/gf9UyPxaN2

我们会在 6 个工作日 内确认你的报告，并让你了解修复进展。

注意： 我们不接受 AI 生成的安全报告。提交此类报告将导致被项目封禁。请确保你的报告包含具体的复现步骤，并证明真实影响。

威胁模型

概述

ax-code 是运行在你本机上的 AI 编程助手。它提供一个代理系统，可以访问包括 shell 执行、文件操作和网页访问在内的强力工具。

运行时隔离默认是 full-access（沙盒关闭），文件系统写入和网络访问不受限制。这是面向受信任本地项目的便利姿态，不是安全边界。在把 AX Code 用于不受信任的仓库或无人值守工作负载之前，请选择 workspace-write 或 read-only。

执行隔离沙盒

ax-code 包含内置的执行隔离沙盒，限制 AI 代理可以访问什么。有三种模式：

关键属性：

• 默认行为 — AX Code 以 full-access 启动，除非 --sandbox、AX_CODE_ISOLATION_MODE 或配置设置了不同模式
• 推荐的受限模式 — 对不受信任或团队仓库使用 workspace-write；它把写入限制在工作区内，并默认禁用网络
• 工具级强制 — 所有变更工具（bash、edit、write、apply_patch）和网络工具（webfetch、websearch、codesearch）都会在执行前检查隔离策略
• 受保护路径 — .git 和 .ax-code 目录始终受到写保护，即使在工作区写入模式下也是如此
• 升级提示 — 在受限模式下，隔离违规会显示批准对话框，而不是静默失败；用户可以允许一次被阻止的操作，而不更改配置
• CLI 控制 — --sandbox read-only、--sandbox workspace-write、--sandbox full-access
• 环境变量 — AX_CODE_ISOLATION_MODE

隔离后端

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

或者设置 AX_CODE_ISOLATION_BACKEND=os|auto|app。

用于 bash 的操作系统隔离会拒绝工作区根之外的写入，并在 network: false 时拒绝网络。应用层检查仍然始终运行。在没有 Seatbelt/bubblewrap 的平台上，使用 backend: "app" 或容器/虚拟机。

服务器安全

• 默认仅本地主机 — 服务器绑定到 127.0.0.1，无法从网络访问
• 网络访问需要密码 — 绑定到 0.0.0.0 或任何非本地主机地址都要求设置 AX_CODE_SERVER_PASSWORD；没有它，服务器拒绝启动
• 强制基本身份验证 — 设置了 AX_CODE_SERVER_PASSWORD 时，所有 API 端点都要求 HTTP Basic Auth
• CORS 可配置 — 可以通过 --cors 指定额外允许的来源

凭据存储

提供商 API 密钥使用带 PBKDF2 密钥派生的 AES-256-GCM 在静态时加密，并存放在本地 AX Code 数据目录（~/.local/share/ax-code/）中，文件权限仅限用户（0600）。

加密密钥派生自本地机器属性（主机名、平台、架构）。这可以防止随意的离线泄露（例如意外的文件分享），但 不能 防止能够访问主机的坚定攻击者。它不等同于操作系统钥匙串或硬件支持的机密存储。

MCP OAuth 令牌、客户端机密，以及账户访问/刷新令牌也使用同一机制在静态时加密。非敏感元数据（服务器 URL、到期时间戳、电子邮件、账户 ID）仍为明文。

发布产物验证

Bash 安装器（install）和 Windows PowerShell 安装器（install.ps1）都会在解压之前用 Minisign 验证已下载的 GitHub 发行归档。发行归档和 PowerShell 安装器脚本本身都带有分离签名。钉住的 AX Code 发布公钥是：

RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO

每个安装器都会为所选归档下载匹配的 .minisig 资产，并在验证失败时失败即关闭。如果 minisign 尚不在 PATH 上，安装器会从 https://download.ax-code.com/vendor/minisign/0.12/ 下载钉住的官方 minisign 0.12 归档，检查归档 SHA-256，并在缓存之前再次检查解压出的可执行文件。已经在 PATH 上的 minisign 二进制是操作者的工具，不会被重新哈希。只有当你有意接受无法验证的发布下载时，才设置 AX_CODE_SKIP_MINISIGN_VERIFY=1。

便利的一行命令 irm …/install.ps1 | iex 不会在执行之前验证安装器脚本。对于安全敏感的安装，请下载 install.ps1 和 install.ps1.minisig，用 Minisign 验证脚本，然后在本地运行它（见 安装与运行时渠道）。

维护者应保持 Minisign 私钥加密。在 macOS 上做本地发布签名时，把口令存在钥匙串中，而不是明文文件：

security add-generic-password -U -a ax-release -s ax-minisign -w

当未设置 AX_CODE_MINISIGN_PASSWORD 时，发布工具会自动读取该钥匙串项。

由标签驱动的 GitHub 发布工作流会在上传之前签名归档。它需要 这些仓库机密：

AX_CODE_MINISIGN_SECRET_KEY_B64
AX_CODE_MINISIGN_PASSWORD

AX_CODE_MINISIGN_SECRET_KEY_B64 必须是加密的 ax.minisign.key Minisign 私钥内容的 base64 编码（本地路径可以是指向 ax.sec 的符号链接）。工作流把它写到一个 临时的 0600 密钥文件，验证钉住的公钥，签名每个发行 归档，并与归档一起上传匹配的 .minisig 资产。

对于 macOS CLI 归档，工作流需要并导入 Apple Developer ID 证书，使用这些仓库机密：

APPLE_CERTIFICATE
APPLE_CERTIFICATE_PASSWORD
APPLE_TEAM_ID
APPLE_API_KEY_B64
APPLE_API_KEY_ID
APPLE_API_ISSUER

在该路径上，捆绑的原生库用导入的 Developer ID Application 身份签名，macOS ZIP 被提交到 Apple 的公证服务， 然后未更改的 ZIP 再由分离的 Minisign 签名保护。ZIP 归档不能装订，因此公证必须发生在产物上传之前， 以及 .minisig 生成之前。当任何 Apple 签名或公证凭据缺失时，发行构建失败即关闭。

发布签名密钥历史

发布签名密钥最近一次轮换是在 2026-07-19。安装器 和发布工作流只钉住当前密钥，因此用已退役 密钥签名的归档会无法通过签名验证。轮换之后，维护者必须用 script/resign-release-assets.ts 重新签名 历史发行归档，以便每个 已发布的版本都能对照钉住的密钥验证，而不信任已退役的密钥。

要用当前密钥重新签名并重新上传现有发布的 .minisig 资产：

tsx script/resign-release-assets.ts --tag v5.5.0 --key-dir ~/signkey

范围

范围内

范围外

企业安全能力

AX Code 面向企业使用设计，具有以下加固特性：

• 细粒度权限：代理专属和基于模式的规则集（allow/deny/ask）。安全代理默认为只读。规则在项目、代理和已批准列表之间评估。
• 会话审计轨迹：每一次工具调用、权限决定和文件变更都连同快照记录在 SQLite 中。支持重放、分叉和导出，用于合规审阅。
• 确定性重构（DRE）：impact_analyze、refactor_plan 和 refactor_apply（影子工作树 + 代码检查/类型检查/测试）提供可审计、可逆的变更。
• 凭据管理：所有密钥/令牌都使用 AES-256-GCM 加密。通过 InstanceState 按目录隔离。
• 选择加入的沙盒强制：应用级隔离，并解析 bash 命令（tree-sitter）。选择 workspace-write 或 read-only 来强制沙盒边界；受保护路径（.git、.ax-code）适用于沙盒模式。
• 服务器加固：默认仅本地主机；带 Basic Auth 的密码保护远程访问。
• 代码智能与扫描：内置机密/硬编码检测，以及依赖影响分析。

CodeQL 辅助的编码反馈

仓库把 CodeQL 作为拉取请求、推送到 dev、计划扫描和手动分发的后台安全分析层来运行。CodeQL 不是 实时 LSP 或代码智能路径的一部分；它是更慢、更深的证据 来源，用于数据流、污点和安全质量发现，这些发现更适合 在源变更稳定之后处理。

当前工作流分析：

• JavaScript 和 TypeScript 运行时、TUI、SDK、集成和脚本代码。
• GitHub Actions 工作流和本地复合操作。
• crates/ 下的 Rust crate，并使用手动 Cargo 构建，以便原生插件和 TUI 代码被一致地提取。

预期的开发者体验是：

1. PR 作者在 GitHub 代码扫描中获得 CodeQL 警报，与现有的 类型检查、确定性测试、OSV 依赖扫描和仓库结构 防护并列。
2. 维护者在把 CodeQL 当作硬性合并 门禁之前，先分拣初始结果，以便新发现有用而不是嘈杂。
3. 未来的 AX Code 审阅/调试流程可以把 CodeQL SARIF 或 GitHub 代码 扫描警报当作显式的安全证据来摄入，并带有出处字段，例如 source: "codeql"、规则 id、严重性、文件、行、数据流跟踪，以及 被分析的提交 SHA。
4. CodeQL 证据应当显示在本地 security_scan、 hardcode_scan、LSP 诊断和基于图的影响分析旁边，而不是作为 对其中任何一项的隐藏替代。

添加自定义 CodeQL 查询时，优先选择仓库专属的安全 边界，而不是宽泛的代码风格检查。高价值目标包括沙盒 逃逸路径、带未净化参数的命令执行、围绕工作区包含的路径遍历、 向子进程传播机密/环境变量， 以及缺失的服务器路由验证。

完整的企业治理（RBAC、策略即代码、SIEM 导出、加密审计）请与 AX Trust 集成（路线图项目）。

隔离配置和运行时行为见 docs/guides/sandbox.md。