codethor0/boundary-layer

# 边界层

      **一个开源的LLM基础设施安全实验室** 模型只是解释器。边界决定了爆炸半径。 **仓库：** https://github.com/codethor0/boundary-layer ## 开始这里 **什么是BoundaryLayer？** 一个本地防御性AI基础设施安全实验室。它模拟了模型被欺骗后的情况：工具路由、会话状态、授权、上传、数据生命周期、写入压力、流、背压、缓存隔离和警报传递。 **谁应该使用它？** 平台工程师、安全/DevSecOps团队、AI构建者和想要动手实践基础设施边界（而不仅仅是提示注入演示）的教育工作者。 **它教授什么？** 每个实验室都在`vulnerable`或`hardened`模式下运行，以便您可以比较不安全的默认设置与防御性控制，并使用Prometheus指标和本地Alertmanager传递。 **最佳首次演示（约5分钟）：** ``` git clone https://github.com/codethor0/boundary-layer.git cd boundary-layer make setup make up make smoke make demo ``` **完整验证（高级，几分钟）：** ``` make validate make validate-prod # production-like profile on machines you control make bug-hunt-prod # optional adversarial checks ``` **演示预览：** `make smoke`和`make demo`的净化终端输出在[docs/assets/demo-transcript.txt](docs/assets/demo-transcript.txt)中。有关简短指南，请参阅[docs/assets/demo-preview.md](docs/assets/demo-preview.md)（除非您使用可选工具在本地捕获，否则没有GIF）。 ``` PASS health: {"status":"ok","service":"boundary-layer-api","version":"1.3.5",...} Vulnerable: blocked=false (privilege escalation accepted) Hardened: blocked=true (HMAC verification rejected tamper) Alert delivered to local webhook. ``` 由于没有捕获工具，未生成GIF；请参阅[docs/DEMO_ASSETS.md](docs/DEMO_ASSETS.md）。 对于引导式浏览，请参阅[docs/WORKSHOP.md](docs/WORKSHOP.md）。有关复制粘贴curl示例，请参阅[docs/EXAMPLES.md](docs/EXAMPLES.md）。有关常见的Docker/端口问题，请参阅[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md）。 ### 你应该看到什么 `GET /health`： ``` {"status":"ok","service":"boundary-layer-api","version":"1.3.5","environment":"development"} ``` Redis脆弱（`blocked: false`）： ``` {"lab":"redis","mode":"vulnerable","blocked":false,"summary":"Vulnerable mode accepted a tampered Redis session blob; role escalated from viewer to admin."} ``` Redis强化（`blocked: true`）： ``` {"lab":"redis","mode":"hardened","blocked":true,"control":"HMAC session integrity verification","summary":"Hardened mode rejected tampered Redis session; privilege escalation blocked."} ``` 断路器后的Webhook（简略）： ``` {"count":1,"alerts":[{"labels":{"alertname":"BoundaryLayerInferenceCircuitBreakerOpen"}}]} ``` BoundaryLayer是一个**本地实验室**，而不是托管的生产SaaS。不要将默认的开发堆栈暴露给公共互联网。 ## 文档地图 | 如果你想… | 阅读 | |-----------------|------| | 在5-30分钟内运行你的第一个实验室 | [docs/WORKSHOP.md](docs/WORKSHOP.md), `make smoke`, `make demo` | | 查看复制粘贴curl示例和示例JSON | [docs/EXAMPLES.md](docs/EXAMPLES.md) | | 理解实时与模拟实验室的现实感 | [docs/LIVE_VS_SIMULATED.md](docs/LIVE_VS_SIMULATED.md) | | 浏览指标和PromQL示例 | [docs/METRICS.md](docs/METRICS.md) | | 遍历Prometheus和Alertmanager | [docs/OBSERVABILITY_WALKTHROUGH.md](docs/OBSERVABILITY_WALKTHROUGH.md) | | 修复Docker、端口或警报问题 | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | | 添加新的实验室（贡献者） | [docs/ADD_A_LAB.md](docs/ADD_A_LAB.md) | | 规划终端GIF或README截图 | [docs/DEMO_ASSETS.md](docs/DEMO_ASSETS.md) | | 理解服务、指标和实验室行为 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | | 审查威胁和信任边界 | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | | 将实验室映射到控制和安全规则 | [docs/CONTROLS_MAP.md](docs/CONTROLS_MAP.md) | | 运行安全的地方红队场景 | [docs/RED_TEAM_PLAYBOOK.md](docs/RED_TEAM_PLAYBOOK.md) | | 使用类似生产环境的本地验证配置文件 | [docs/PRODUCTION.md](docs/PRODUCTION.md) | | 运行完整的Docker验证门 | [docs/E2E_VALIDATION.md](docs/E2E_VALIDATION.md) | | 发布、标记或发布（维护者） | [CHANGELOG.md](CHANGELOG.md), [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md), [docs/GITHUB_RELEASE.md](docs/GITHUB_RELEASE.md) | | 浏览图表 | [docs/DIAGRAMS.md](docs/DIAGRAMS.md) 或下面的架构部分 | 可选的深入研究：[docs/DEEP_QA.md](docs/DEEP_QA.md), [docs/LIVE_RELEASE_GATE.md](docs/LIVE_RELEASE_GATE.md), [docs/GOVERNANCE_MODEL.md](docs/GOVERNANCE_MODEL.md), [docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md), [docs/DEMO.md](docs/DEMO.md）。 ## BoundaryLayer是什么 一个带有FastAPI编排器、相关Redis和PostgreSQL（如有必要）、Prometheus指标、Alertmanager路由到本地Webhook以及九对脆弱/强化实验室的本地Docker Compose实验室。没有外部LLM API依赖。 BoundaryLayer包括一个确定性的**模拟LLM服务**（`mock-llm:8080`）用于演示和扩展点。当前的实验室运行器是确定性的，并且大多数在**进程内**执行。实时实验室直接使用Redis和PostgreSQL——在正常实验室运行期间，它们不会调用模拟LLM的HTTP API。 ## 实时与模拟实验室 | 实验室 | 现实感 | |-----|---------| | 工具路由器 | 进程内模拟 | | Redis篡改 | 实时Redis（+回退） | | 授权 | 进程内模拟 | | 文件上传 | 元数据模拟（不是真实解析器） | | 治理 | 实时PostgreSQL（+回退） | | 写入风暴 | 实时PostgreSQL（有界插入） | | 断路器 | 合成工作单元 | | SSE耗尽 | 合成流（没有真实套接字） | | 提示缓存 | 实时Redis（+回退） | 完整矩阵：[docs/LIVE_VS_SIMULATED.md](docs/LIVE_VS_SIMULATED.md）。 ## 它为什么存在 大多数AI安全演示都停在提示注入。真正的失败发生在基础设施边界：检索、缓存、授权、上传、数据库、流和可观察性。BoundaryLayer提供了成对的脆弱和强化实验室模式，带有指标和本地警报验证，以便工程师可以在没有生产风险的情况下练习检测和控制设计。 ## 它模拟什么 九个确定性的实验室涵盖了基础设施级别的风险。每个实验室接受`{"mode": "vulnerable"}`或`{"mode": "hardened"}`，并返回包含`lab`、`mode`、`blocked`、`risk`、`control`、`events`和`summary`的结构化JSON。 重点领域包括工具路由、Redis会话完整性、平面授权、文件沙盒强化、提示治理、PostgreSQL写入风暴、断路器背压、SSE耗尽和提示缓存隔离。 ## 它不做什么 - 它不调用付费的外部LLM API - 它不使用外部解析器解析真实的上传文件 - 它不重现已确认的生产漏洞 - 它默认不将警报路由到外部值班系统 - 它不是一个生产安全产品或WAF替代品 BoundaryLayer仅用于防御性教育、安全工程和受控的本地测试。 ## 生产部署（类似生产环境的配置文件，v1.3.5） BoundaryLayer提供了一个类似生产环境的本地验证配置文件（`docker-compose.prod.yml`），用于在您控制的机器上进行防御性测试。它**不是**一个托管SaaS产品，也不**打算**直接暴露给公共互联网，除非您进行了自己的操作加固。 默认的开发堆栈（`make up`）仍然是一个仅限本地的实验室，并且已禁用身份验证。 ``` cp .env.production.example .env.production bash deploy/nginx/generate-certs.sh make prod-up ``` 有关完整的部署指南，请参阅[docs/PRODUCTION.md](docs/PRODUCTION.md）。 对于类似生产环境的配置文件，存在备份和恢复脚本。`make validate`证明了表级别的`write_storm_events`恢复；`make validate-restore-fresh-volume`证明了将完整数据库恢复到新的Compose卷（种子`requested_writes: 25`）。请参阅[docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md）。 **警告：** `make validate-restore-fresh-volume`重置BoundaryLayer的本地Docker Compose卷。这对于实验室是安全的，但它将删除本地实验室数据。 ## 概观架构 BoundaryLayer作为一个本地Docker Compose实验室运行，具有API、模拟LLM、Redis、PostgreSQL、Prometheus、Alertmanager和本地警报Webhook。

系统架构

``` flowchart LR User[User / curl] --> API[BoundaryLayer API :8000] API --> Labs[Lab Modules] API --> MockLLM[Mock LLM :8080] API --> Redis[(Redis :6379)] API --> Postgres[(PostgreSQL :5432)] API --> Metrics[/GET /metrics/] Prometheus[Prometheus :9090] -->|scrape 15s| API Prometheus -->|firing alerts| AM[Alertmanager :9093] AM -->|POST /alerts| Hook[Alert Webhook :8081] GH[GitHub Actions CI] -->|tests lint hygiene| Repo[boundary-layer repo] ``` 注意：模拟LLM出现在拓扑中用于演示和未来的扩展。实验室运行器在进程内执行，并在启用实时模式时使用Redis/PostgreSQL；在正常实验室运行期间，它们不会调用mock-llm。

Docker Compose运行时拓扑

``` flowchart TB subgraph Host[Docker Compose Network] API[api :8000] Mock[mock-llm :8080] Redis[(redis :6379)] PG[(postgres :5432)] Prom[prometheus :9090] AM[alertmanager :9093] Hook[alert-webhook host 8081 to 8080] end API --> Mock API --> Redis API --> PG Prom -->|scrape api:8000| API Prom --> AM AM --> Hook ``` 注意：`API --> Mock`显示了可选的模拟LLM伴随服务。正常实验室执行保持在API容器内进行。

实验室执行流程

``` sequenceDiagram participant User participant API as BoundaryLayer API participant Lab as Lab Module participant Metrics as Metrics Registry participant Infra as Redis or PostgreSQL User->>API: POST /labs/{lab}/run API->>API: Validate mode and fields API->>Lab: Execute vulnerable or hardened path Lab->>Infra: Live or fallback interaction Lab->>Metrics: Record counters and gauges Lab-->>API: Structured result dict API->>API: Strip internal metric keys API-->>User: lab mode blocked risk control events summary ```

可观察性和警报管道

``` flowchart LR API[API /metrics] -->|scrape| Prom[Prometheus] Prom --> Rules[alerts.yml rules] Rules -->|firing| AM[Alertmanager] AM --> Hook[Local webhook :8081] Validate[make validate] -->|trigger circuit breaker| API Validate -->|poll GET /alerts| Hook ```

信任边界模型

``` flowchart TB subgraph Untrusted[Untrusted Inputs] Req[Lab requests] Retrieved[Retrieved content] FileMeta[Synthetic file metadata] Prefix[Synthetic prompt prefix] Work[Work units and streams] end subgraph Controls[Boundary Controls] Val[Request validation] Policy[Mode policy] Wrap[Untrusted wrapping] NS[Tenant namespacing] Budget[Write and stream budgets] CB[Circuit breaker] end subgraph State[State and Telemetry] Redis[(Redis)] PG[(PostgreSQL)] M[Prometheus metrics] end subgraph Detect[Detection] Rules[Alert rules] AM[Alertmanager] Hook[Local webhook] end Req --> Val Retrieved --> Wrap FileMeta --> Val Prefix --> NS Work --> Budget Work --> CB Val --> Policy Policy --> Redis Policy --> PG Policy --> M M --> Rules --> AM --> Hook ```

有关完整的图表集（包括每个实验室的流程和CI验证的13个图表），请参阅[docs/DIAGRAMS.md](docs/DIAGRAMS.md）。服务端口、指标和实验室行为在[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md）中记录。 ## 包含的实验室 | 实验室 | 端点 | 风险 | |-----|----------|------| | 工具路由器注入 | `POST /labs/tool-router/run` | 检索中毒路由到破坏性工具 | | Redis状态篡改 | `POST /labs/redis/run` | 未签名的会话blob允许提权 | | 平面认证/授权 | `POST /labs/authz/run` | 广泛的令牌访问受限工具 | | 文件上传注入 | `POST /labs/file-upload/run` | 不安全的提取与沙盒提取 | | 提示治理 | `POST /labs/governance/run` | 不完整删除导致下游记录孤儿 | | PostgreSQL写入风暴 | `POST /labs/postgres-write-storm/run` | 逃逸的提示记录饱和PostgreSQL写入器 | | 断路器 | `POST /labs/circuit-breaker/run` | 没有背压的无界推理工作 | | SSE耗尽 | `POST /labs/sse-exhaustion/run` | 无界SSE流耗尽工作单元和内存 | | 提示缓存隔离 | `POST /labs/prompt-cache-isolation/run` | 共享提示前缀缓存键跨租户泄漏 | 示例： ``` curl -sf -X POST http://localhost:8000/labs/redis/run \ -H "Content-Type: application/json" \ -d '{"mode":"hardened"}' ``` ## 实时基础设施组件 | 服务 | 端口 | 角色 | |---------|------|------| | API | 8000 | FastAPI实验室编排器和`/metrics`导出器 | | 模拟LLM | 8080 | 确定性模型模拟器（演示/扩展；实验室默认不调用它） | | Redis | 6379 | Redis和提示缓存实验室的实时会话和缓存目标 | | PostgreSQL | 5432 | 治理和写入风暴后端 | | Prometheus | 9090 | 抓取指标，评估警报规则 | | Alertmanager | 9093 | 将触发警报路由到本地Webhook | | 警报Webhook | 8081 | 存储Alertmanager有效载荷以进行验证 | 将`.env.example`复制到`.env`以进行本地覆盖。永远不要提交`.env`。 ## 可观察性和警报 API在`GET /metrics`处公开Prometheus指标。实验室运行增加`boundary_layer_lab_runs_total`和特定模式的计数器。Prometheus在`detections/prometheus/alerts.yml`（包括工具注入、Redis篡改、授权拒绝、治理、写入风暴、断路器、SSE、提示缓存和文件上传警报）中评估规则，并将触发警报发送到Alertmanager。Alertmanager路由到`http://localhost:8081/alerts`处的本地Webhook。 ``` curl -sf http://localhost:8000/metrics | head -40 curl -sf http://localhost:8081/alerts ``` 有关实验室到警报映射，请参阅[docs/CONTROLS_MAP.md](docs/CONTROLS_MAP.md）。指标目录：[docs/METRICS.md](docs/METRICS.md）。指南：[docs/OBSERVABILITY_WALKTHROUGH.md](docs/OBSERVABILITY_WALKTHROUGH.md）。 ## 端到端验证 | 目标 | 目的 | |--------|---------| | `make smoke` | 快速检查（约30秒）：健康、实验室列表、指标、Redis配对 | | `make demo` | 指导演示：Redis、提示缓存、断路器警报轮询 | | `make validate-alerts` | 扩展警报传递：六个确定性的警报 | | `make validate-restore-fresh-volume` | 新卷Postgres备份/恢复证明（重置本地Compose卷） | |make capture-demo` | 生成净化后的`docs/assets/demo-transcript.txt` | | `make validate` | 完整本地门（测试、lint、所有实验室、指标、警报传递，包括通过`validate-alerts`的六个警报） | | `make validate-prod` | 类似生产环境的本地验证配置文件 | 权威的本地门是`make validate`（186个测试、lint、所有实验室、指标、警报传递，包括通过`validate-alerts`的六个警报）。 ## 视觉身份 标志资产位于[assets/logo/](assets/logo/README.md）。选定的标志是从[Concept A](assets/logo/CONCEPT_REVIEW.md）派生出的层状管道堆栈。包括SVG标志、文字标志、浅色和深色标志以及社交预览卡片。 ## 仓库卫生 有意排除Git中的生成报告、命令转储、本地捆绑包、编辑器文件和构建提示。它们可能存在于本地或审查捆绑包（`make bundle`）中，但不是公共仓库的一部分。 ## 命令 | 目标 | 描述 | |--------|-------------| | `make setup` | 创建虚拟环境并安装依赖项 | | `make up` | 构建并启动Docker Compose服务 | | `make down` | 停止Docker Compose服务 | | `make smoke` | 快速检查（需要堆栈启动） | | `make demo` | 带有警报轮询的指导演示（需要堆栈启动） | | `make test` | 运行pytest（186个测试） | | `make lint` | 运行ruff lint和格式检查 | | `make validate-alerts` | 扩展警报传递（6个确定性的警报） | | `make validate-restore-fresh-volume` | 新卷Postgres证明（重置本地Compose卷） | | `make capture-demo` | 生成净化后的演示转储 | | `make validate` | 完整验证管道 | | `make validate-e2e` | 完整测试 + lint + prod + 本地验证 | | `make validate-prod` | 类似生产环境的本地验证配置文件 | | `make backup` | 将Postgres备份到`backups/postgres/` | | `make bundle` | 在`~/Downloads/`中创建本地审查ZIP | | `make clean` | 停止服务并删除生成的缓存 | | `make help` | 列出Makefile目标 | ## 持续集成 GitHub Actions在每次推送到`main`时运行：`make test`、`make lint`、仓库卫生检查、秘密扫描和标志SVG验证。工作流程：[.github/workflows/ci.yml](.github/workflows/ci.yml）。 完整的Docker堆栈验证仍然可在本地和通过手动[Docker Validate](.github/workflows/docker-validate.yml)工作流程中可用。 ## 它是为谁而存在的 -

标签：AI安全, AI构建者, AI系统加固, Alertmanager, Chat Copilot, DevSecOps, Docker, GitHub Advanced Security, PB级数据处理, Python, XML 请求, 上游代理, 代码审查, 反取证, 安全加固, 安全合规, 安全培训, 安全开发, 安全架构, 安全测试, 安全社区, 安全策略, 安全评估, 安全运维, 安全防御评估, 平台工程师, 开源, 提示词设计, 攻击性安全, 教育工具, 无后门, 模拟实验室, 红队平台, 网络代理, 自定义请求头, 请求拦截, 边界层, 逆向工具