Secure Agents

一个用于构建完全在您本地硬件上运行的 AI 代理的开源框架。
本地-only LLM 推理。数据不会离开您的机器。默认安全。

快速开始 • 安全性 • 架构 • 使用 Claude Code 构建代理 • 配置 • CLI 参考

## 什么是 Secure Agents？ Secure Agents 是一个用于**在您自己的机器上完全运行** AI 驱动的自动化工作流的框架。您可以定义编排**工具**（邮件、文档解析、存储）和**本地 LLM**（通过 [Ollama](https://ollama.com)）的**代理**——所有这些都通过配置连接，而不是代码。 **没有任何数据会离开您的机器。** 云 LLM 提供商已被刻意从代码库中删除。每个文档、每封邮件、每次 LLM 调用都保留在您的硬件上。 它是为处理敏感数据的专业人士构建的——律师、金融分析师、合规官员——但该框架是通用性的。任何您能描述的工作流，都可以实现自动化。 **包含的 NDA 审阅代理**是一个工作示例：它监控 Gmail 收件箱中的 NDA 文档，使用本地 LLM 进行逐条款风险分析，并将结果通过邮件发送回发件人。 ### 为什么选择 Secure Agents？ | | 云 AI 平台 | Secure Agents | |---|---|---| | **数据隐私** | 文档发送到第三方服务器 | **文档永远不会离开您的机器** | | **LLM 推理** | 在供应商服务器上运行 | 通过 Ollama 在本地运行 | | **凭据** | 存储在配置文件或仪表板中 | macOS Keychain，永不以明文形式存储 | | **文档解析** | 服务端，信任供应商 | 在 Docker 中沙箱化——无网络、只读、临时 | | **定制化** | 供应商锁定，扩展性有限 | 插件系统——添加一个装饰器即可添加代理/工具 | | **基础设施** | 云账户、计费、网络 | 在 Mac 上运行 `bash setup.sh`。就这样。 | ## 快速开始 ``` # 克隆并设置（安装 Python、Ollama、venv，拉取 LLM 模型） git clone https://github.com/NeilJain56/secure-agents.git cd secure-agents bash setup.sh # 激活环境 source .venv/bin/activate # 将凭据存储在 macOS Keychain 中（切勿存储在文件中） secure-agents auth setup # 使用您的电子邮件设置编辑配置 cp config.example.yaml config.yaml nano config.yaml # 验证所有连接是否正确 secure-agents validate # 启动一个代理 secure-agents start nda_reviewer # 或启动 Web 仪表板 secure-agents ui ``` ### 需求 - **macOS**（Keychain 集成；计划支持 Linux） - **Python 3.11+** - **Ollama**（本地 LLM 推理；由 `setup.sh` 安装） - **Docker**（必需——沙箱默认启用） ## 安全性 该框架从设计之初就默认为**安全**。每个设置都以最严格的状态发货。您必须明确选择退出安全功能——而不是选择加入。 ### 1. 零数据外泄——强制执行，不可配置 云 LLM 提供商（Anthropic、OpenAI、Gemini）已从代码库中**移除**。不是禁用——是删除。没有配置选项可以发送数据到外部 API。所有 LLM 推理都通过 Ollama 在本地运行。 ### 2. 沙箱化文档解析（默认启用） 文档解析（PDF、DOCX）在 **Docker 容器**内运行，具有： - 无网络访问（`--network=none`） - 只读文件系统（`/output` 除外） - 内存限制（512MB），CPU 节流（50%） - 每个任务后自动销毁 如果缺少 Docker 且沙箱已启用，框架**拒绝解析**——不会静默回退到本地执行。要禁用沙箱，您必须明确设置 `security.sandbox_enabled: false`（不推荐）。 ### 3. 凭据永不以明文形式接触磁盘 密码和 API 密钥**永不存储在配置文件中**。凭据解析链： 1. **macOS Keychain** — 由操作系统加密，锁定到您的用户账户 2. **环境变量** — 用于 CI/CD 或容器 3. **OAuth2 令牌** — 访问/刷新令牌以 `0600` 权限存储；OAuth2 `client_secret` 存储在 Keychain 中，永不在磁盘上 ### 4. 原生 Gmail OAuth2 无需 Google 应用密码。一个命令即可设置带令牌刷新的 OAuth2： ``` @.claude/agent-development.md Build me an agent called "contract_analyzer" that: - Monitors my inbox for contract documents (PDF/DOCX) - Extracts text and identifies key clauses (termination, liability, IP ownership) - Uses the LLM to score risk on each clause - Saves a structured JSON report - Emails a summary back to the sender Use the existing email_reader, document_parser, file_storage, and email_sender tools. Follow the same patterns as the nda_reviewer agent. ``` ### 5. 使用魔术字节验证文件 每个文件在任何解析库处理之前都会经过验证： - **魔术字节验证** — `.pdf` 必须以 `%PDF` 开头，`.docx` 必须以 `PK` 开头（ZIP）。重命名的可执行文件会被拒绝。 - 文件类型白名单（默认为 `.pdf`、`.docx`） - 大小限制（每个代理可配置） - 路径遍历防护 - 文件名清理（仅限字母数字、点、连字符、下划线；最多 255 个字符） ### 6. 输入清理（20+ 种模式） 所有文档文本在到达 LLM 之前都会经过清理。清理器： - 检测 **20+ 种提示注入模式**（指令覆盖、角色切换、系统提示提取、数据泄露尝试） - 应用 **Unicode 规范化**（NFKC）以防止同形字绕过 - 将检测事件记录到审计日志 ### 7. 路径遍历防护 文件存储操作被**限制**在配置的输出目录内。文件名和子文件夹名称都会被清理和解析，然后验证是否保持在边界内。目录遍历（`../`）和绝对路径会被拒绝。 ### 8. 临时处理 临时文件在处理后会被清理。沙箱容器在每个任务后会被销毁。LLM 实例无法在分析之间保留信息。 ### 9. 仅元数据审计日志 审计日志记录发生了什么、何时发生、对哪个文件发生——但**永不记录文档内容、邮件正文或 PII**。完全的操作可见性，而不会创建敏感数据的第二份副本。 ### 10. 加固仪表板 Web 仪表板： - 仅绑定到 **`127.0.0.1`** — 即使请求也阻止远程绑定 - 强制执行**严格 CORS** — 仅允许 `localhost` 来源 - 需要**每个会话的 auth 令牌**（在启动时生成，打印到终端，自动注入仪表板）在所有状态更改端点上 - **清理错误消息** — 不向客户端泄露内部路径、堆栈跟踪或凭据 ### 11. 最小攻击面 - 使用 SQLite 作为任务队列（无需暴露 Redis/RabbitMQ），文件权限为 `0600` - 代理模式下无开放端口（仪表板是可选的，仅 localhost） - 仅本地连接您的邮件服务器 - 邮件连接上**始终强制** TLS/SSL — 无 `use_tls: false` 切换 - 代理名称经过验证（`^[a-z][a-z0-9_]{0,63}$`）以防止通过配置注入 - 固定、最小化依赖项 - 无遥测或分析 ### 12. 供应链加固 - 依赖项在 `pyproject.toml` 中指定最低版本 - Docker 沙箱使用最小的 `python:3.12-slim` 基础镜像，带有固定的 pip 包 - 容器以非 root 用户运行 - 无需第三方运行时服务 ## 架构 ``` config.yaml | +---------+ | Builder | (discovers & wires components) +---------+ / | \ +-------+ +------+ +----------+ | Agent | | Tool | | Provider | +-------+ +------+ +----------+ | | | tick() loop execute() complete() | Ollama (local) ``` ### 代理 工作流编排器。每个代理通过组合工具和 LLM 提供商来定义*做什么*。代理是轻量级的——它们从不直接实现 I/O。添加新代理只需一个文件和一个装饰器。 ### 工具 跨代理共享的可重用功能。在 YAML 配置中声明代理需要哪些工具： | 工具 | 描述 | |------|-------------| | `email_reader` | 监控 IMAP 收件箱，下载附件（强制 SSL） | | `email_sender` | 通过 SMTP 发送带附件的邮件（强制 TLS） | | `document_parser` | 从 PDF/DOCX 提取文本（通过 Docker 沙箱化） | | `file_storage` | 本地保存和加载 JSON 报告（路径遍历保护） | ### 提供商 仅支持 **Ollama**（本地推理）。没有数据会离开您的机器。 | 提供商 | 类型 | 默认模型 | |----------|------|---------------| | `ollama` | 本地 | `llama3.2` | ### 插件系统 组件通过装饰器注册，在启动时自动发现： ``` @register_agent("my_agent") # Agents @register_tool("my_tool") # Tools ``` 无需手动导入或接线。将文件放入正确目录，添加装饰器，即可使用。 使用 Claude Code 构建代理 添加新代理的最快方式是使用 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)。您无需编写框架样板——只需描述您想要的工作流，Claude Code 就会使用框架的模式构建它。 ### 工作流 **第 1 步。** 在项目目录中打开 Claude Code： ``` cd secure-agents claude ``` **第 2 步。** 将上下文文件提供给 Claude Code，然后描述您的代理： ``` @.claude/agent-development.md Build me an agent called "contract_analyzer" that: - Monitors my inbox for contract documents (PDF/DOCX) - Extracts text and identifies key clauses (termination, liability, IP ownership) - Uses the LLM to score risk on each clause - Saves a structured JSON report - Emails a summary back to the sender Use the existing email_reader, document_parser, file_storage, and email_sender tools. Follow the same patterns as the nda_reviewer agent. ``` **第 3 步。** Claude Code 将： - 创建 `src/secure_agents/agents/contract_analyzer/agent.py`，包含正确的注册 - 创建 `src/secure_agents/agents/contract_analyzer/prompts.py`，包含领域特定提示 - 将配置条目添加到 `config.yaml` - 在 `tests/test_contract_analyzer.py` 中编写测试 - 将所有内容连接到现有框架 **第 4 步。** 运行它： ``` secure-agents start contract_analyzer ``` ### 常见代理类型的示例提示 **邮件分类代理：** ``` @.claude/agent-development.md Build an agent called "email_triage" that reads incoming emails, classifies them into categories (urgent, follow-up, informational, spam) using the LLM, and saves a daily digest report. Don't send any emails back — just categorize and store. ``` **合规监控器：** ``` @.claude/agent-development.md Build an agent called "compliance_checker" that watches a folder for new policy documents, compares them against a set of regulatory requirements I'll define in the prompts file, and flags any gaps or violations. Save reports with risk scores. ``` **研究助手：** ``` @.claude/agent-development.md Build an agent called "research_digest" that monitors email for newsletters and research papers, extracts the key findings using the LLM, and saves a structured summary. Group by topic. I want to review the summaries on the dashboard. ``` ### 获得最佳结果的技巧 - **始终引用上下文文件** `@.claude/agent-development.md` — 它为 Claude Code 提供完整的框架契约、命名约定和安全规则。 - **将 NDA 审阅者作为遵循的模式**：请查看 `src/secure_agents/agents/nda_reviewer/agent.py` 中的模式。" - **具体说明工具** — 指定要使用哪些现有工具（`email_reader`、`document_parser` 等），以便 Claude Code 正确连接它们。 - **请求测试** — Claude Code 将使用 mock 编写 pytest 测试，匹配项目的测试模式。 - **请求将提示放在单独文件中** — 将 LLM 系统提示保留在 `prompts.py` 文件中，而不是内联在代理中。 ### 使用 Claude Code 创建新工具 ``` @.claude/agent-development.md Build a new tool called "slack_notifier" that sends messages to a Slack webhook. It should accept channel, message, and optional severity level. Store the webhook URL in the credential system (macOS Keychain), never in config. Follow the BaseTool interface and update builder.py to wire the config. ``` ### 上下文文件 文件 `.claude/agent-development.md` 包含 Claude Code 需要的一切： - 框架契约（BaseAgent、BaseTool、BaseProvider 接口） - 现有工具和提供商及其参数 - 配置继承模型 - 所有 13 条安全规则 - 测试模式 - NDA 审阅者作为参考实现 此文件已检入仓库。在添加新工具或更改契约时，请保持更新。 ## 配置 `config.yaml` 使用**默认值 + 每个代理覆盖**模型： ``` # 仅支持 Ollama（本地）— 不支持云提供商 provider: active: ollama ollama: host: http://localhost:11434 model: llama3.2 # 共享默认值 — 每个代理都会继承这些 defaults: email: imap: host: imap.gmail.com username: you@gmail.com auth_method: oauth2 security: max_file_size_mb: 50 allowed_file_types: [.pdf, .docx] sandbox_enabled: true # Requires Docker (default: on) # 每个代理继承默认值并覆盖所需内容 agents: nda_reviewer: enabled: true poll_interval_seconds: 60 tools: [email_reader, email_sender, document_parser, file_storage] contract_analyzer: enabled: true tools: [email_reader, document_parser, file_storage] security: max_file_size_mb: 200 # Larger files for this agent ``` 两个代理可以拥有完全不同的文件大小限制、输出目录或轮询间隔，而不会相互影响。请参阅 `config.example.yaml` 获取完整的注释模板。 ## CLI 参考 | 命令 | 描述 | |---------|-------------| | `secure-agents start [agents...]` | 启动一个、几个或所有已启用的代理 | | `secure-agents list` | 列出已注册的代理、工具和提供商 | | `secure-agents validate` | 检查配置、Ollama、Docker、凭据 | | `secure-agents auth setup` | 将凭据存储到 macOS Keychain | | `secure-agents auth gmail `` | 设置 Gmail OAuth2 | | `secure-agents setup [agents...]` | 引导式设置向导 | | `secure-agents ui` | 启动 Web 仪表板（仅 localhost） | ## Web 仪表板 一个单页仪表板（无需 npm，无需构建步骤）用于监控和控制代理： - **代理选项卡** — 启动/停止代理，查看健康状态，启用/禁用开关 - **指标选项卡** — 任务计数、错误率、处理延迟、时间序列图表 - **输出选项卡** — 浏览和查看生成的报告 - **审计日志选项卡** — 可搜索的仅元数据事件日志 使用 `secure-agents ui` 启动并打开 `http://localhost:8420`。仪表板仅绑定到 localhost，使用严格 CORS，并在所有状态更改操作上需要每个会话的 auth 令牌。 ## 项目结构 ``` src/secure_agents/ core/ # Framework internals base_agent.py BaseAgent ABC (the agent contract) base_tool.py BaseTool ABC (the tool contract) base_provider.py BaseProvider ABC (the provider contract) registry.py Plugin registry and @register_* decorators config.py Config loading, validation, env var interpolation credentials.py Keychain / env var / OAuth2 credential resolution security.py File validation (magic bytes), input sanitization, audit log sandbox.py Docker-only sandboxed execution (no fallback) job_queue.py SQLite-backed job queue with retry and dead-letter builder.py Discovers all plugins and wires agents at startup providers/ # LLM backend (local only) ollama.py Local inference via Ollama tools/ # Reusable capabilities (shared across agents) email_reader.py IMAP inbox monitor (SSL enforced) email_sender.py SMTP email sending (TLS enforced) document_parser.py PDF/DOCX text extraction (sandboxed) file_storage.py Local JSON report storage (path-traversal protected) _template.py Copy this to create a new tool agents/ # Agent implementations nda_reviewer/ Example: NDA review via email monitoring _template/ Copy this directory to create a new agent ui/ # Web dashboard server.py FastAPI backend (localhost only, auth token, CORS) dashboard.html Single-page frontend (no build step) ``` ## 开发 ``` # 以开发模式安装 pip install -e ".[dev]" # 运行测试（59 个测试，包括安全套件） pytest tests/ -v # 验证配置、Ollama、Docker secure-agents validate # 列出所有已注册的组件 secure-agents list ``` ## 许可证 MIT

标签：AI代理框架, AI风险缓解, Docker沙箱, LLM推理, LLM评估, macOS Keychain, Ollama, 代理编排, 合规自动化, 工具集成, 开源框架, 持续集成, 敏感数据处理, 无云服务, 本地LLM, 本地推理, 本地部署, 模块化架构, 纵深防御, 网络安全, 请求拦截, 隐私保护, 零日漏洞检测