Secure Execution Gateway

一个面向自动化平台的安全执行网关，用严格的白名单操作替代任意命令执行。
专为安全自动化、工作流引擎和内部平台而设计。

## 目录 - [1. 概述](#1-overview) - [2. 动机](#2-motivation) - [3. 核心特性](#3-key-features) - [4. 架构概览](#4-architecture-overview) - [5. 安全模型](#5-security-model) - [6. 快速开始](#6-quick-start) - [7. 配置说明](#7-configuration) - [8. API 概览](#8-api-overview) - [9. 可观测性](#9-observability) - [10. 项目结构](#10-project-structure) - [11. 测试策略](#11-testing-strategy) - [12. CI / DevSecOps](#12-ci--devsecops) - [13. 文档](#13-documentation) - [14. 开发](#14-development) - [15. 贡献指南](#15-contributing) - [16. 安全报告](#16-security-reporting) - [17. 许可证](#17-license) ## 1. 概述 Secure Execution Gateway (SEG) 是一个专注于安全的 FastAPI 微服务，在沙盒化的容器文件系统中暴露一组严格的白名单文件操作。 SEG 作为一个内部执行网关，适用于需要受控文件处理但又不暴露任意 Shell 执行的自动化和平台工作流。 该服务接受 HTTP 请求，通过纵深防御的中间件堆栈对其进行验证，从内存中的显式白名单解析已注册的操作，并仅在配置好的文件系统沙盒内执行该操作。 这种设计保持了暴露的能力集小且可预测。API 以一个操作执行端点加上由 SEG 管理的文件 CRUD 端点、强类型请求和响应模型、稳定的错误码以及面向容器的部署为中心。SEG 面向受信任的内部环境，并非一个通用的命令运行器。 ### 执行边界模型 ``` flowchart TD subgraph Risky Automation Patterns A[Arbitrary Command Execution] B[Dynamic Expressions] C[Unrestricted Scripts] D[Privileged Workflow Automation] end subgraph SEG Execution Gateway E[Allowlisted Actions] F[Filesystem Sandbox] G[Typed API Contracts] H[Observability & Auditability] end subgraph Controlled Operations I[Deterministic Execution Operations] J[Safe Automation Workflows] end A --> E B --> E C --> E D --> E E --> F F --> G G --> H H --> I I --> J ``` ### 应用场景 可能的应用场景包括： - 诸如 n8n 等自动化平台的安全执行层 - 微服务架构中的受控文件系统操作 - 内部平台内的安全文件处理网关 - 替代后端服务中不安全的命令执行模式 - 为工作流引擎和任务运行器提供强化的执行边界 ## 2. 动机 低代码自动化平台、Agentic AI 系统以及工作流编排工具的快速普及，极大地增加了能够执行复杂自动化任务并访问敏感数据和基础设施的系统数量。 这些平台中有许多将**推向市场的速度和易用性**置于防御性系统设计之上。结果，诸如命令执行、动态表达式或不受限制的脚本等执行原语，往往成为高风险的攻击面。 当结合以下因素时： - 自动化平台的病毒式普及 - 广泛的自托管部署 - 对内部系统和数据的特权访问 - 许多用户有限的安全专业知识 这些特征创造了一个**存在远程代码执行 (RCE)、权限提升和数据泄露高风险的环境**。 Secure Execution Gateway (SEG) 的设计正是作为对这类问题的**架构级响应**。 SEG 没有暴露任意命令执行，而是引入了一个经过强化的执行边界，在此边界内： - 操作是**明确列入白名单的** - 文件系统访问是**沙盒化且受限的** - 执行发生在**无根 (rootless) 的容器环境中** - API 强制执行**强类型请求契约** - 可观测性支持**可追踪且可审计的操作** 此模型使用**受控的、确定性的操作**取代了不安全的执行模式，适用于必须在灵活性与安全性之间取得平衡的自动化系统。 ### 说明风险的漏洞示例 在 2025 年末至 2026 年初之间，工作流自动化平台中发现的几个严重漏洞说明了暴露任意执行能力的内在风险。 | CVE | 类型 | 描述 | | ---- | ---- | ---- | | [CVE-2025-68613](https://nvd.nist.gov/vuln/detail/CVE-2025-68613) | 需认证的 RCE | 表达式求值缺陷，允许在 n8n 工作流内执行代码 | | [CVE-2026-21858](https://nvd.nist.gov/vuln/detail/CVE-2026-21858) | 无需认证的 RCE | "Ni8mare" 漏洞，可通过 webhook 处理实现远程接管 | | [CVE-2026-21877](https://nvd.nist.gov/vuln/detail/CVE-2026-21877) | 需认证的 RCE | 不安全的文件处理，允许通过上传的内容执行代码 | ## 3. 核心特性 - 仅针对已注册操作的严格白名单执行模型 - 受限于 `SEG_SANDBOX_DIR` 和 `SEG_ALLOWED_SUBDIRS` 的沙盒化文件系统操作 - 通过环境变量和 `.env` 文件进行运行时配置 - 纵深防御中间件，用于身份认证、请求完整性、速率限制、超时、请求 ID 和可观测性 - 使用 FastAPI 和 Pydantic 构建的强类型请求和响应模型 - 面向 API 消费者的稳定 JSON 响应封装 - 兼容 Prometheus 的指标和请求关联支持 - 无根的、面向容器的部署模型 - 自动化的 CI、安全扫描、发布和文档流水线 ## 4. 架构概览 在运行时，请求会经过一个简短且明确的执行流水线。当前的高级架构如下： ``` flowchart TD Client --> SEG SEG --> MiddlewareStack MiddlewareStack --> Dispatcher Dispatcher --> FileActions FileActions --> SandboxFilesystem ``` 在请求到达分发器之前，中间件会验证身份认证、请求完整性、速率限制、超时、请求 ID、可观测性以及可选的安全头。 分发器验证操作名称，根据已注册的 Pydantic 模型验证参数，执行操作处理程序，并将成功或失败的结果规范化到标准的响应封装中。 有关完整的架构演练，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 5. 安全模型 SEG 的设计围绕显式控制而非宽泛的执行能力。 - 受保护端点上的 Bearer token 身份验证 - ASGI 边界处的请求完整性验证 - 严格的内存操作白名单 - 仅限于 `SEG_SANDBOX_DIR` 的文件系统访问 - 通过 `SEG_ALLOWED_SUBDIRS` 实施顶层白名单强制 - 拒绝路径遍历、反斜杠、NUL 字节和控制字符 - 路径解析和安全文件打开路径中的符号链接拒绝 - 进程本地的速率限制 - 每请求超时强制执行 - 无根容器运行时模型 - 用于审计的 Prometheus 指标和请求关联头 有关完整的威胁分析，请参阅 [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)。 ## 6. 快速开始 SEG 被设计为在 Docker 内部运行，并作为共享 Docker 网络上的内部服务。 最小化本地启动： ``` git clone https://github.com/Libertocrat/seg.git cd seg # 从模板创建运行时配置文件 # ".env" 文件定义了沙箱限制、运行时安全保障， # 以及 SEG 容器使用的 Docker 基础设施参数 cp .env.example .env mkdir -p secrets openssl rand -hex 32 > secrets/seg_api_token.txt # 如果您在 .env 中更改了 SHARED_DOCKER_NETWORK，请替换 docker-network docker network create docker-network || true ./scripts/init-shared-volume.sh --env-file .env docker compose up -d --build ``` 注意事项： - `docker-compose.yml` 不会公开暴露 SEG - 运行时配置由 `.env` 中设置的环境变量定义 - 有关环境变量的详细信息，请查看 `.env.example` 文件 - 容器会加入由 `SHARED_DOCKER_NETWORK` 定义的外部网络 - 在执行 `docker compose up` 之前，外部 Docker 网络必须已存在 - 共享卷必须在堆栈启动前初始化 - 运行时 API token 通过 Docker secret 挂载从 `secrets/seg_api_token.txt` 加载 有用的后续检查： ``` docker compose ps docker compose logs -f ``` 在开发期间，如果不希望在 Compose 中发布端口而从宿主机访问容器化服务： ``` ./scripts/seg-forward.sh --env-file .env ``` 本地开发工作流记录在 [DEVELOPMENT.md](DEVELOPMENT.md) 中。 ## 7. 配置说明 SEG 运行时行为通过本地 `.env` 文件中定义的环境变量进行配置。Docker Compose 读取这些变量并将其注入到容器环境中，SEG 在启动时会在容器内验证并加载其运行时配置。请查阅 [.env.example](.env.example) 以获取包含详细注释的完整变量列表。 ``` flowchart LR EnvFile[.env] --> Compose[Docker Compose] EnvFile --> RuntimeEnv[Container Environment] Compose --> SEG[SEG Container] RuntimeEnv --> Settings[SEG Settings Validation] Settings --> Runtime[SEG Runtime Configuration] ``` `.env.example` 中显示的值为占位部署值，不一定代表应用程序默认值或您特定部署环境所需的配置。 ### 核心变量 | 变量 | 描述 | 默认值 | | --- | --- | --- | | `SEG_SANDBOX_DIR` | 容器内用于文件操作的绝对沙盒根目录。 | `None` -> **必填** | | `SEG_ALLOWED_SUBDIRS` | 顶层沙盒子目录的 CSV 白名单，或 `*`。 | `None` -> **必填** | | `SEG_MAX_BYTES` | 基于文件的操作允许的最大文件大小。 | `104857600` | | `SEG_TIMEOUT_MS` | 每请求的超时时间（毫秒）。 | `5000` | | `SEG_RATE_LIMIT_RPS` | 每个客户端的进程本地请求速率限制。 | `10` | | `SEG_LOG_LEVEL` | 应用程序日志详细程度。 | `INFO` | | `SEG_APP_VERSION` | 运行时和 OpenAPI 元数据暴露的语义版本。 | `0.1.0` | | `SEG_ENABLE_DOCS` | 启用 `/docs`、`/redoc` 和 `/openapi.json`。 | `false` | | `SEG_ENABLE_SECURITY_HEADERS` | 启用基线响应安全头。 | `true` | | `SHARED_DOCKER_NETWORK` | 用于将 SEG 与内部服务连接的外部 Docker 网络。 | `docker-network` | | `SEG_PORT` | 容器内部的应用程序侦听端口。 | `8080` | 有关容器身份、共享卷命名、时区和其他部署设置，请参阅 [.env.example](.env.example) 中的完整参考。 ## 8. API 概览 主要 API 模型目前包含用于白名单操作的 `POST /v1/execute`，以及用于 SEG 管理的文件生命周期操作的 `/v1/files` 端点。 ### 端点 公开的 HTTP 接口是有意保持精简的。 | 端点 | 用途 | | --- | --- | | `POST /v1/execute` | 执行白名单操作 | | `POST /v1/files` | 上传并持久化托管文件 | | `GET /v1/files/{id}` | 通过 `file_id` 检索托管文件元数据 | | `GET /v1/files` | 使用游标分页列出托管文件 | | `GET /v1/files/{id}/content` | 通过 `file_id` 流式传输托管文件内容 | | `DELETE /v1/files/{id}` | 通过 `file_id` 删除托管文件 | | `GET /health` | 服务就绪检查 | | `GET /metrics` | Prometheus 指标 | 交互式文档端点仅在 `SEG_ENABLE_DOCS=true` 时可用： - `/docs` - `/redoc` - `/openapi.json` 托管的 API 文档发布于： - [https://libertocrat.github.io/seg/api-docs/](https://libertocrat.github.io/seg/api-docs/) ### 请求示例 针对 `file_checksum` 的请求示例： ``` { "action": "file_checksum", "params": { "path": "uploads/file.bin", "algorithm": "sha256" } } ``` 在此示例中： - `action` 选择一个已注册的操作处理程序 - `params` 根据特定操作的 schema 进行验证 - `path` 必须保留在配置的沙盒和允许的子目录内 成功响应示例： ``` { "success": true, "data": { "algorithm": "sha256", "checksum": "abc123...", "size_bytes": 20480 }, "error": null } ``` 目前在 `src/seg/actions/file/` 中实现的当前文件操作有： - `file_checksum` - `file_delete` - `file_mime_detect` - `file_move` - `file_verify` ## 9. 可观测性 SEG 导出结构化的请求可观测性数据和兼容 Prometheus 的指标。 `/metrics` 端点暴露由中间件和路由堆栈生成的指标，包括： - 请求计数器 - 延迟直方图 - 进行中请求追踪 - 错误分类计数器 - 请求完整性拒绝计数器 - 速率限制计数器 - 超时计数器 可观测性层还会传播或生成 `X-Request-Id`，以便调用者可以跨系统关联请求。 有关实现细节，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 10. 项目结构 代码库布局是有意保持紧凑的，并围绕应用程序包、测试、运维工具和项目文档进行组织。 ``` seg/ |-- src/ | `-- seg/ | |-- actions/ # registered execution actions | |-- core/ # config, schemas, security, and OpenAPI helpers | |-- middleware/ # security and observability middleware stack | |-- routes/ # HTTP endpoints | `-- app.py # FastAPI application factory |-- tests/ # smoke, unit, and integration tests |-- docs/ # architecture, testing, CI, and threat model docs |-- scripts/ # developer and release helper utilities |-- requirements/ # runtime, testing, linting, security, and dev sets |-- .github/workflows/ # CI, security, release, and docs publishing |-- docker-compose.yml # local container stack |-- Dockerfile # container image build |-- .env.example # runtime configuration template `-- Makefile # local quality and security workflow entry point ``` 概要： - `src/seg/` 包含应用工厂、中间件、路由、操作系统和核心助手 - `tests/` 覆盖冒烟测试、单元测试、集成测试和与安全相关的行为 - `docs/` 包含架构、测试、CI 和威胁模型文档 - `scripts/` 包含用于本地开发和文档导出的辅助工具 - `requirements/` 区分运行时、测试、代码检查、安全和聚合开发依赖 - `.github/workflows/` 包含 CI、安全、发布和文档发布工作流 ## 11. 测试策略 测试套件结合了冒烟测试、单元测试和集成测试当前的覆盖范围包括： - 分发器和注册表行为 - 文件操作实现 - 请求和响应 schema - 中间件强制执行 - 路由行为 - 文件系统沙盒保护 - OpenAPI 生成行为 当前的测试执行模型为： ``` flowchart TD Developer --> Pytest Pytest --> UnitTests Pytest --> IntegrationTests Pytest --> SmokeTests IntegrationTests --> AppFactory AppFactory --> Middleware AppFactory --> Routes Routes --> Dispatcher Dispatcher --> ActionHandlers ActionHandlers --> SandboxHelpers ``` 使用以下命令在本地运行测试套件： ``` make test ``` 有关完整的测试文档，请参阅 [docs/TESTING.md](docs/TESTING.md)。 ## 12. CI / DevSecOps SEG 使用 GitHub Actions 和基于 Makefile 的本地工作流，进行可重复的质量和安全检查。 代码库目前包含以下流水线类别： - CI 质量门禁 - 深度安全分析 - 容器发布流水线 - 文档发布流水线 这些工作流中使用的工具包括： - Ruff - Black - MyPy - pytest - Bandit - pip-audit - Semgrep - Trivy 当前的 CI 和发布拓扑如下： ``` flowchart TD Developer --> Push Developer --> PullRequest Developer --> TagPush Push --> CIWorkflow PullRequest --> CIWorkflow PullRequest --> SecurityWorkflow TagPush --> ReleaseWorkflow TagPush --> DocsWorkflow CIWorkflow --> QualityGate QualityGate --> DockerBuildValidation SecurityWorkflow --> Semgrep SecurityWorkflow --> TrivyFS SecurityWorkflow --> TrivyImage ReleaseWorkflow --> BuildImage BuildImage --> TrivyScan TrivyScan --> PushGHCR PushGHCR --> GitHubRelease GitHubRelease --> OpenAPIAssets DocsWorkflow --> ExportOpenAPI ExportOpenAPI --> BuildDocsSite BuildDocsSite --> PublishGHpages ``` 有关流水线的详细信息，请参阅 [docs/CI.md](docs/CI.md)。 ## 13. 文档 README 是高级入口点。详细的设计、工作流和操作资料位于以下文档中。 | 文档 | 描述 | | --- | --- | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 系统架构、执行流程和运行时设计 | | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | 威胁模型、信任边界和缓解措施 | | [docs/TESTING.md](docs/TESTING.md) | 测试策略、套件结构和本地执行 | | [docs/CI.md](docs/CI.md) | CI、安全扫描、发布和文档发布工作流 | | [CHANGELOG.md](CHANGELOG.md) | 项目发布历史和重要变更 | | [DEVELOPMENT.md](DEVELOPMENT.md) | 本地开发环境和 Makefile 工作流 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 当前的贡献策略和项目参与状态 | | [SECURITY.md](SECURITY.md) | 漏洞披露和安全报告策略 | | [scripts/README.md](scripts/README.md) | 开发者和发布辅助脚本 | ## 14. 开发 本地开发在 [DEVELOPMENT.md](DEVELOPMENT.md) 中单独记录。 开发工作流主要围绕： - Python 3.12 - Docker - Makefile 目标 - pre-commit 钩子 - `scripts/` 下的辅助脚本 典型的本地质量门禁： ``` make ci ``` 有用的开发者入口点： - [DEVELOPMENT.md](DEVELOPMENT.md) - [scripts/README.md](scripts/README.md) - [CONTRIBUTING.md](CONTRIBUTING.md) ## 15. 贡献指南 在项目稳定其以下方面期间，暂不接受外部拉取请求： - API 设计 - 安全模型 - 测试覆盖率 - CI 工作流 - 发布流程 但我们仍然欢迎反馈和非安全相关问题报告。 有关当前的贡献策略，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 16. 安全报告 请勿在公开的 Issue 中报告漏洞。 请使用 [SECURITY.md](SECURITY.md) 中记录的负责任的披露流程。对于加密报告，代码库还包含了 [SECURITY_PGP_KEY.asc](SECURITY_PGP_KEY.asc)。 ## 17. 许可证 SEG 采用 Apache License 2.0 授权。有关完整文本，请参阅 [LICENSE](LICENSE)。

标签：API网关, Docker, GitHub Advanced Security, Go语言工具, HTTP API, OpenAPI, Python, 内部平台安全, 命令执行替代, 安全加固, 安全执行网关, 安全防御评估, 审计, 工作流引擎, 执行网关, 提示词模板, 文件操作, 无后门, 权限控制, 沙箱隔离, 白名单机制, 网络安全审计, 自动化平台, 自定义请求头, 请求拦截