✦ Nullsec Legion

Nullsec Legion 是一款用于软件项目的开源 AI 操作系统。你只需下达任务 —— agent 会自动进行规划、构建、审查和安全扫描 —— 并且没有你的加密签名，就不会发生任何不可逆的操作。

## 为什么选择 Legion Legion 将 agent 的工作视为专业团队处理变更的方式：作为一个包含计划、审查、安全扫描以及需由人类签名的关卡的工作单元。Agent 在受限环境中执行劳动；而你掌握着密钥。每一个决策——每一个计划、prompt、diff、发现结果和签名——都会被写入一个只能追加的账本中，因此“agent 做了什么，以及谁批准了它？”这个问题始终有一个确切的答案。 | 功能 | 具体含义 | | --- | --- | | **是任务，而非聊天** | 持久化、基于事件溯源的工作单元，具有类型化的状态机和微秒级精度的只能追加的账本。 | | **各司其职的 Legion** | 专门的规划、编码和审查 agent；编码 agent 在一个移除了 git remote 的隔离克隆环境中工作，因此它无法推送到你的仓库。 | | **在你查看前先进行扫描** | 在你进行评判之前，每个 diff 都会扫描机密信息 (gitleaks) 和不安全的模式 (semgrep)；错误会阻断流程，发现结果会随工作返回。 | | **人类关卡** | 合并操作需等待你的 passkey (WebAuthn)，并在加密级别与 diff 和扫描报告的确切字节绑定。篡改其中任何一项，批准即告失效。 | | **操作系统强制的限制** | Agent 在内核级别的沙盒 (seatbelt/bwrap) 下运行：受限的文件系统，通过过滤了 SSRF 的代理进行出站访问，机密信息不可读。宁可拒绝启动，也绝不不受限地运行。 | | **只读的研究任务** | Agent 搜索实时网络并返回带有引用、经过扫描和签名的报告。 | | **与提供商无关** | 带来你自己的 OpenRouter key；支持任何模型，没有供应商锁定。 | | **完整的记录** | 每一个计划、prompt、commit、发现结果和签名，都永久保存在账本中。 | ## 快速安装 一条命令即可克隆、配置并启动 Legion。它会先检查你的环境，并准确地告诉你缺少什么——不会有任何静默运行： ``` npx @trynullsec/legion ``` 它会提示你输入 OpenRouter key（仅写入 `.env`，绝不记录日志），配置 worker 运行时和扫描器，启动 Postgres，运行数据库迁移，并打开任务看板。使用 `--dir ` 选择安装位置，或使用 `--no-start` 仅进行设置而不启动；请参阅 `npx @trynullsec/legion --help`。

手动安装 — 相同的步骤，手动执行

``` git clone https://github.com/trynullsec/legion.git cd legion git submodule update --init # vendored agent runtime (Hermes Agent) pnpm install bash scripts/setup-workers.sh # worker runtime (uv-managed Python venv + agent) bash scripts/setup-scanners.sh # gitleaks + semgrep cp .env.example .env # add your OPENROUTER_API_KEY docker compose up -d # Postgres (pgvector) on :5434 pnpm migrate pnpm dev # board + API at http://localhost:4242 ``` 如果端口 `5434` 已被占用（例如第二个 Legion 实例），请在另一个端口上发布 Postgres 并保持 `DATABASE_URL` 同步 —— 执行 `LEGION_PG_PORT=5500 docker compose up -d`，然后在 `.env` 中设置 `...@localhost:5500/...`。`npx` 安装程序会自动为你完成此操作。 在 Linux 上，还需要安装 bubblewrap (`sudo apt-get install -y bubblewrap`)：Legion 会在操作系统级别限制每一个 worker，并拒绝不受限地运行。

然后打开 **http://localhost:4242**，注册一个 passkey，并创建你的第一个任务。 ## 快速开始 ``` pnpm dev # Build the board and start the daemon (board + API on :4242) pnpm migrate # Apply database migrations pnpm test # Full suite — fast tier + real-agent tier pnpm test:fast # Fast tier only (no live agents required) pnpm typecheck # Type-check every package docker compose up -d # Start Postgres docker compose down # Stop Postgres ``` 在 `.env` 中设置你的 key： ``` DATABASE_URL=postgres://legion:legion@localhost:5434/legion OPENROUTER_API_KEY=sk-or-... # any model, via OpenRouter LEGION_SEARCH_PROVIDER=tavily # for read-only research missions LEGION_SEARCH_API_KEY=tvly-... ``` ## 任务流程 任务会通过一个单一的、类型化的状态机进行流转。状态转移表永远不会改变；各个阶段会适应任务的类型。 ``` CREATED → PLANNING → AWAITING_PLAN_APPROVAL → BUILDING → REVIEW → SCANNING → AWAITING_MERGE_APPROVAL → MERGED ``` 1. **计划。** 规划 agent 会读取克隆的仓库（或者对于研究任务，仅读取目标）并提出结构化的计划。你可以批准或拒绝；拒绝时会将你的反馈原封不动地携带至下一步。 2. **构建。** 编码 agent 在隔离的工作区中执行已批准的计划——这是一个移除了 git remote 的克隆环境，因此 agent 无法将任何内容推送到上游。 3. **审查。** 审查 agent 会结合计划读取 diff 并做出裁决，这个过程包含一个有界的修订循环。 4. **扫描。** diff 将由 **gitleaks**（扫描机密信息）和 **semgrep**（扫描不安全模式）扫描，并生成 SARIF 工件。错误级别的发现会阻断流程；它们会随工作一起路由到下一次尝试中。 5. **关卡。** 合并操作将暂停，直到你签名。（详情见下文。） 6. **合并。** 只有在签名验证通过后，Legion 才会在你的仓库中执行真正的 `git merge --no-ff`。 ## 人类关卡 该关卡是始终如一的。每个任务、每个风险级别，最终都要经过 passkey 验证流程——没有任何绕过的方法。 当任务到达 `AWAITING_MERGE_APPROVAL` 状态时，Legion 会派生出一个与工作本身绑定的 WebAuthn 验证请求： ``` challenge = base64url( sha256( missionId | diffSha256 | sarifSha256 | serverNonce ) ) ``` 工件的哈希值在发出验证请求以及再次验证你的断言时，都会**从磁盘重新计算**。如果在此期间 diff 或扫描报告的任何一个字节发生了改变，哈希值将不再匹配，批准将因 `INTEGRITY` 错误而失效——没有任何内容会被合并。你的签名批准的是*那些确切的字节*，而不是抽象意义上的“任务”。 风险级别会调整关卡*之前*的检查点，但永远不会改变关卡本身： - **low** — schema 验证通过的计划会自动批准（在账本中记录为策略决策，绝非静默处理）；构建过程将一路直达关卡，无需人工干预。 - **medium** — 默认级别；计划批准需人工进行。 - **high** — 扫描阈值收紧，使得警告（而不仅仅是错误）也会阻断流程。 对于上述三种情况，合并关卡是完全相同的。 ## 限制机制 Agent 不受信任；它们是被隔离的。每个 worker 在启动时都会被包装在一个操作系统级别的沙盒中，该沙盒的范围根据其角色设定，并且在它执行任何工作之前，其解析后的策略会被写入账本（`CAPABILITY_PROFILE`）。如果平台无法强制执行该策略，worker 将**拒绝启动**——它绝不会在不受限的情况下静默运行。 - **文件系统** — 基于角色的写入白名单（例如，编码 agent 只能写入其工作区）；其他所有写入都被拒绝，且机密路径不可读。 - **网络** — 对于构建角色为 `none`；研究 worker 仅能通过 Legion 控制的出站代理访问网络，该代理会记录每个请求，并在遇到环回地址、RFC1918 和云元数据地址时**默认拒绝**（防御 SSRF）。 - **进程** — 默认情况下拒绝派生子进程。 | 平台 | 机制 | 状态 | | --- | --- | --- | | macOS | `sandbox-exec` (seatbelt) | 已强制执行 | | Linux | `bubblewrap` (bwrap) namespaces | 已实现；部署目标路径 | 限制机制只能*减少* worker 可以执行的操作。它不能授予新的能力——它是一道底线，而不是功能开关。 ## 任务类型 | 类型 | 交付物 | 流水线 | | --- | --- | --- | | **code** | 合并到你仓库的 git diff | plan → build → review → scan → gate → merge | | **task** | 文件工件（报告、分析、数据集） | plan → build → review → gitleaks scan → gate → deliver | | **research** *(只读)* | 带有引用的 markdown 报告 | execute (web search + fetch) → gitleaks scan → gate → deliver | 任务和研究的交付物会被封装为与 sha256 绑定的工件，并受到与代码相同的 passkey 流程管控——即使是只读输出，在正式生效前也需要经过签名。 ## 架构 一个基于 pnpm + Turborepo 的 monorepo。表现层、编排层和限制层是分离的，因此每一层都可以独立进行推理和测试。 | 包 | 职责 | | --- | --- | | `@legion/core` | 领域类型、任务状态机以及纯策略（风险、调度、能力解析）。 | | `@legion/db` | PostgreSQL 迁移和双时性、只能追加的事件存储。 | | `@legion/scanner` | gitleaks + semgrep，通过阈值逻辑合并为单一的 SARIF 工件。 | | `@legion/runtime` | worker 监督程序、操作系统级限制 (seatbelt/bwrap) 以及过滤了 SSRF 的出站代理。 | | `@legion/orchestrator` | 计划 / 构建 / 审查 / 扫描 / 交付流程，以及合并/交付机制。 | | `apps/daemon` | Hono HTTP API、WebAuthn 关卡和调度循环。 | | `apps/board` | React 任务看板。 | Agent 运行时本身是 **[Hermes Agent](https://github.com/NousResearch/hermes-agent)**，作为 git submodule 引入，并由 Legion 的监督程序驱动——从未被修改过。 ## 目前可用的功能 Legion 对其功能范围非常坦诚。只有当有已提交并通过的测试作为支撑时，某项声明才会被列在“目前可用”下。 **已交付并验证 (M0–M7)：** - **代码任务** — 完整的 plan → build → review → scan → passkey gate → merge 流水线。 - **普通任务** — 作为经过扫描和签名的文件工件交付的、可追溯的非代码工作。 - **只读研究任务** — 实时网络搜索和抓取，以带引用的报告形式返回。 - **风险成比例的流水线** — 检查点随声明的风险而变化；合并关卡则始终如一。 - **操作系统强制的限制机制** — 基于角色的 seatbelt/bwrap 沙盒、出站代理、SSRF 防御、拒绝启动机制。 所有这些功能都经过了 **170 多项针对真实基础架构的测试**的检验——真实的 Postgres、真实的模型、真实的 git、真实的扫描器、真实的 WebAuthn。**没有使用任何 mock。** **下一步计划：** - **全能力执行** — 能够在沙盒化的容器中运行代码、驱动浏览器和编辑文件，以完成开放式任务（而不仅仅是描述它们）的 agent，且处于相同的关卡管控之下。 - **托管选项** — 无需本地设置的 Legion。 这些属于路线图，而非已兑现的承诺。如果某项功能目前尚未有通过的测试作为支撑，它就会被列在这里，而不是上面的列表中。 ## 从你的 AI 客户端使用它 (MCP) [`@trynullsec/legion-mcp`](mcp/) 是一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，允许 Cursor、Claude Desktop 或任何 MCP 客户端通过你正在运行的守护进程创建、监控和审查任务。将你的客户端指向它： ``` { "mcpServers": { "legion": { "command": "npx", "args": ["-y", "@trynullsec/legion-mcp"], "env": { "LEGION_API_URL": "http://localhost:4242" } } } } ``` 合并关卡依然由人类掌控：MCP 客户端可以计划、构建和读取交付物，但**批准合并是在看板中进行的 passkey 验证流程**——没有任何工具可以直接对其进行签名。请参阅 [`mcp/README.md`](mcp/README.md)。 ## 文档 完整的文档位于 **[heylegion.io](https://heylegion.io)**。 | 主题 | 涵盖内容 | | --- | --- | | 快速入门 | 安装 → 迁移 → 第一个任务 | | 任务 (Missions) | 状态机、任务类型和账本 | | 关卡 (The gate) | WebAuthn 绑定、验证请求派生、完整性规则 | | 限制机制 | 能力配置、出站代理、平台矩阵 | | 配置 | 环境变量、提供商、模型 | ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 由 Nullsec 构建。Agent 运行时源自 [Hermes Agent](https://github.com/NousResearch/hermes-agent) (Nous Research, MIT) —— 深表感谢。

标签：AI智能体, DevSecOps, 上游代理, 人工智能, 代码审查, 测试用例, 用户模式Hook绕过, 自动化攻击, 请求拦截, 软件开发, 逆向工具