eneamanzi/apiguard-assurance

[English version](README.en.md) | **意大利语版本** # APIGuard Assurance **针对云环境中 REST API 的自动化安全评估工具** APIGuard Assurance 是一款用于对受 API Gateway 保护的 REST API 进行安全审计的 CLI 工具。它针对任何使用 OpenAPI 3.x 或 Swagger 2.0 规范记录的目标，执行 APIGuard 方法论（涵盖 8 个领域，多达 29 项可验证的安全保证），并生成交互式 HTML 报告和正式、可复现的证据存档。 ## 目录 1. [附加价值与用例](#1-valore-aggiunto-e-casi-duso) 2. [要求与安装](#2-requisiti-e-installazione) 3. [配置](#3-configurazione) 4. [实际用法](#4-utilizzo-pratico) 5. [评估输出](#5-output-dellassessment) 6. [工作原理 — 高层流水线](#6-come-funziona--pipeline-ad-alto-livello) 7. [领域与测试优先级](#7-domini-e-priorità-dei-test) 8. [退出代码](#8-codici-di-uscita) 9. [仓库结构](#9-struttura-della-repository) ## 1. 附加价值与用例 对 API Gateway 进行手动审计速度慢、难以复现，且容易出现系统性遗漏。APIGuard Assurance 通过正式、确定性和有记录的方法解决了这些问题。 **对于安全审计人员：** - 在任何兼容的目标上可复现地执行相同的保证集：相同的测试、相同的顺序、相同的输出。 - 三个特权级别 — Black Box（无凭证）、Grey Box（适用于多种角色的有效 JWT）、White Box（Admin API 访问权限） — 可独立配置以适应约定的范围。 - 自动收集正式证据：每次违规都附带完整的请求、完整的响应以及一个 `record_id`，使分析师能够无需任何额外上下文即可复现攻击。 - 交互式 HTML 报告，包含每次执行 HTTP 事务的完整审计追踪，包括那些 PASS 的事务，作为覆盖率的证明。 **对于开发与 DevSecOps 团队：** - 通过结构化的 JSON 输出（`apiguard_report.json`）和语义化退出代码，原生集成到 CI/CD 流水线中。 - 采用 JSON 格式的结构化日志记录（`--log-format json`），兼容 Elasticsearch、Splunk、Datadog 及类似聚合器。 - 零秘密架构：凭证从不会以明文形式出现在受版本控制的配置文件中。 ## 2. 要求与安装 **系统要求：** - Python 3.11 或更高版本 - 目标 API 的网络访问权限（Gateway 代理及可选的 Admin API） **开发模式安装（推荐）：** ``` git clone cd apiguard-assurance # 创建并激活 virtual environment python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows # 安装包及所有 runtime 依赖 pip install -e . # 验证安装 apiguard version ``` **包含开发依赖的安装（面向贡献者）：** ``` pip install hatch hatch env create dev hatch run dev:pytest tests_e2e/ -v ``` **静态分析工具：** ``` # Linting 和 formatting（ruff — 替代 flake8 + isort + black） hatch run dev:ruff check src/ hatch run dev:ruff format src/ # strict 模式下的 Type checking（mypy） hatch run dev:mypy src/ ``` ## 3. 配置 配置被分为两层截然不同且有意解耦的部分：可受版本控制的结构化参数和来自环境的秘密信息。 ### 3.1 `config.yaml` — 结构化参数（可受版本控制） ``` target: base_url: "http://localhost:8000" # URL del proxy Gateway openapi_spec_url: "http://localhost:3000/swagger.v1.json" admin_api_url: "http://localhost:8001" # Ometti per disabilitare test WHITE_BOX credentials: # Le credenziali NON compaiono mai in chiaro qui. # I placeholder ${VAR} vengono risolti da variabili d'ambiente a runtime. admin_username: "${ADMIN_USERNAME}" admin_password: "${ADMIN_PASSWORD}" user_a_username: "${USER_A_USERNAME}" user_a_password: "${USER_A_PASSWORD}" user_b_username: "${USER_B_USERNAME}" user_b_password: "${USER_B_PASSWORD}" execution: min_priority: 3 # 0 = solo P0 | 1 = P0+P1 | 2 = P0-P2 | 3 = tutti (default) strategies: - BLACK_BOX - GREY_BOX - WHITE_BOX fail_fast: false # Se true, interrompe l'esecuzione al primo FAIL su test P0 connect_timeout: 5.0 read_timeout: 30.0 max_retry_attempts: 3 openapi_fetch_timeout_seconds: 60.0 output: directory: "outputs" # Accetta percorsi relativi o assoluti; creata se non esiste rate_limit_probe: max_requests: 150 # Massimo richieste per il probe empirico di rate limiting request_interval_ms: 50 tests: domain_1: max_endpoints_cap: 0 # 0 = testa tutti gli endpoint protetti (raccomandato) ``` ### 3.2 `.env` 文件 — 秘密信息（请勿进行版本控制） ``` # 复制 template 并填充字段 cp .env.example .env ``` ``` # .env — 本地 variabili d'ambiente ADMIN_USERNAME=thesis-admin ADMIN_PASSWORD= USER_A_USERNAME=user-a USER_A_PASSWORD= USER_B_USERNAME=user-b USER_B_PASSWORD= ``` 加载器（`src/config/loader.py`）会在解析 YAML **之前** 执行环境变量插值。未解析的占位符（`${MISSING_VAR}`）会产生一个 `ConfigurationError`，明确指出缺失的变量名，使诊断变得立即且直接。进程环境中已存在的变量优先于 `.env` 文件中的变量（即 `load_dotenv` 的 `override=False` 行为），这使得该工具适用于通过编排器注入秘密信息的 CI/CD 环境。 ### 3.3 配置验证（不启动评估） ``` apiguard validate-config --config config.yaml ``` 仅执行阶段 1（加载和验证），如果配置有效则返回退出代码 0，否则返回 10。 ## 4. 实际用法 ### 启动评估 ``` # 标准执行（当前 working directory 中的 config.yaml） apiguard run # 显式路径中的 Config apiguard run --config /etc/apiguard/config.yaml # 面向 CI/CD 的 JSON Output — machine-readable log，无 banner apiguard run --log-format json --no-banner # 详细 Debug：每条 HTTP 事务均被单独 log apiguard run --log-level debug # 抑制 banner 同时保留 human-readable log（在脚本中很有用） apiguard run --no-banner ``` ### 选择测试子集 选择是通过 `config.yaml` 进行的，而不是通过 CLI 参数。修改 `execution` 参数以缩小范围： ``` # 仅 Black Box 测试 — 无需 credenziale execution: min_priority: 0 strategies: - BLACK_BOX # 所有 strategie 中仅 P0 关键测试 execution: min_priority: 0 strategies: - BLACK_BOX - GREY_BOX - WHITE_BOX ``` ### 集成到 CI/CD 流水线 ``` #!/bin/bash set -e apiguard run \ --config config.yaml \ --log-format json \ --no-banner EXIT_CODE=$? case $EXIT_CODE in 0) echo "CLEAN: nessuna violazione rilevata"; exit 0 ;; 1) echo "FAIL: almeno una garanzia di sicurezza e violata"; exit 1 ;; 2) echo "ERROR: almeno una verifica non e stata completata"; exit 2 ;; 10) echo "INFRA: errore di infrastruttura, assessment non completato"; exit 10 ;; esac ``` ## 5. 评估输出 每次运行结束后，会在配置的目录（`output.directory`）中生成三个文件： | 文件 | 格式 | 用途 | |---|---|---| | `assessment_report.html` | 交互式 HTML | 供分析师阅读的报告，包含每项事务的完整审计追踪 | | `evidence.json` | JSON | FAIL（失败）证据的取证存档（完整、可复现的 payload） | | `apiguard_report.json` | JSON | 用于 CI/CD、SIEM 及机器间集成的结构化报告 | ### `evidence.json` — 取证存档 包含按时间排序的 `EvidenceRecord` 数组，每条记录对应一个产生 FAIL 或被测试明确“固定”为关键上下文的 HTTP 事务。每条记录包括： - 完整的请求（方法、URL、带有 `Authorization: [REDACTED]` 的标头、主体） - 完整的响应（状态码、标头、截断为 10,000 个字符的主体） - 格式为 `{test_id}_{sequence}` 的 `record_id`（例如 `1.1_005`）— 与 HTML 报告进行交叉引用的键 单条 `EvidenceRecord` 足以复现触发漏洞的确切请求，而无需任何额外的上下文。这就是其设计目的：**每条记录都是自给自足的**。 ### `assessment_report.html` — 交互式报告 HTML 报告包括： - 带有汇总统计信息的执行摘要（PASS/FAIL/SKIP/ERROR、发送的 HTTP 请求总数、评估持续时间） - 按测试划分的结果表，包含领域、优先级、策略、CWE 及结果消息 - 对于每个 FAIL 测试：包含特定技术描述和标准参考（CWE、OWASP）的 `Finding` - 每个测试均可展开的审计追踪：包含预言机状态（`ENFORCED`、`BYPASS`、`RATE_LIMIT_HIT` 等）和主体预览的所有 HTTP 事务表 - 双向交叉引用：带有 `is_fail_evidence=true` 的条目会在 `evidence.json` 中报告相应的 `record_id` ## 6. 工作原理 — 高层流水线 该工具每次评估执行七个顺序阶段。阶段 1、2 和 4 是**阻塞的**：错误会产生退出代码 10，且不执行任何测试。阶段 5、6 和 7 是非阻塞的。 ``` config.yaml + .env | v Fase 1: Initialization — Legge e valida config.yaml, interpola segreti da env | v Fase 2: OpenAPI Discovery — Scarica la spec, derefenzia $ref, costruisce la mappa endpoint | v Fase 3: Context Construction — Crea i quattro oggetti di runtime | v Fase 4: Test Discovery — Scopre i test dinamicamente, ordina per dipendenze (DAG), | applica i filtri di priorita e strategia v Fase 5: Execution — Esegue ogni test in ordine topologico, raccoglie i TestResult | v Fase 6: Teardown — Rimuove (best-effort) le risorse create durante i test | v Fase 7: Report Generation — Serializza evidence.json, genera HTML e JSON di report | v Outputs: assessment_report.html evidence.json apiguard_report.json ``` ## 7. 领域与测试优先级 APIGuard 方法论将安全覆盖范围构建为 8 个主题领域和 4 个优先级： | 领域 | 名称 | 当前已实现的测试 | |---|---|---| | 0 | API Discovery and Inventory Management | 0.1 Shadow API, 0.2 Deny by Default, 0.3 Deprecated API Enforcement | | 1 | Identity and Authentication | 1.1 Authentication Required | | 2 | Authorization and Access Control | — | | 3 | Data Integrity | — | | 4 | Availability and Resilience | — | | 5 | Visibility and Auditing | — | | 6 | Configuration and Hardening | — | | 7 | Business Logic and Sensitive Flows | — | | 优先级 | 标签 | 典型策略 | 描述 | |---|---|---|---| | P0 | Critical | BLACK_BOX | 基本的边界控制。当 `fail_fast: true` 时，P0 上的 FAIL 会中断整个评估 | | P1 | High | GREY_BOX | 使用有效凭证的身份验证和授权保证 | | P2 | Medium | GREY_BOX | 应用逻辑、数据完整性、可见性 | | P3 | Low | WHITE_BOX | 通过 Gateway 的 Admin API 进行的配置审计 | **`min_priority` 映射 -> 包含的测试：** | `min_priority` | 包含的测试 | |---|---| | `0` | 仅 P0（纯 Black Box） | | `1` | P0 + P1 | | `2` | P0 + P1 + P2 | | `3` | 所有 — P0 + P1 + P2 + P3（推荐默认值） | **用于 E2E 测试中选择性过滤的 pytest 标记：** ``` pytest tests_e2e/ -m "p0 and domain_0" -v pytest tests_e2e/ -m "black_box" -v ``` ## 8. 退出代码 | 代码 | 含义 | 条件 | |---|---|---| | `0` | CLEAN — 未检测到违规 | 所有测试均产生 PASS 或 SKIP | | `1` | FAIL — 至少违反了一项安全保证 | `ResultSet` 中至少包含一个 `TestResult(status=FAIL)` | | `2` | ERROR — 至少有一项检查未完成 | 没有 FAIL，但至少包含一个 `TestResult(status=ERROR)` | | `10` | INFRA — 基础设施错误 | `ConfigurationError`、`OpenAPILoadError`、`DAGCycleError` | 优先级为：**FAIL (1) > ERROR (2) > CLEAN (0)**。单个 FAIL 会覆盖任何数量的 ERROR。退出代码 10 表示评估未开始，且 `ResultSet` 不能作为任何安全判断的可靠依据。 ## 9. 仓库结构 ``` apiguard-assurance/ |-- config.yaml # Template di configurazione (versionabile) |-- .env.example # Template variabili d'ambiente (non versionare .env) |-- pyproject.toml # Metadati progetto, dipendenze, configurazione tool | |-- src/ | |-- cli.py # Entry point CLI (Typer) | |-- engine.py # Orchestratore pipeline — 7 fasi sequenziali | | | |-- config/ # Fase 1: caricamento e validazione configurazione | |-- core/ # Layer fondamentale — vocabolario e infrastruttura condivisa | |-- discovery/ # Fase 2: parsing OpenAPI e costruzione AttackSurface | |-- tests/ # Fase 5: implementazioni dei test per dominio | `-- report/ # Fase 7: generazione HTML, JSON e aggregazione statistiche | |-- test-environments/ | `-- forgejo-kong/ # Docker Compose per l'ambiente di test locale | |-- tests_e2e/ # Suite E2E contro il target reale (richiede Docker stack) `-- tests_integration/ # Suite di integrazione per i layer interni ``` *APIGuard Assurance v1.0.0 — MIT License*

标签：APIGuard, API安全网关, API网关, API网关绕过, CISA项目, DAST, JWT安全, OpenAPI, Python安全工具, REST API安全, Swagger, Web安全, 交互式HTML报告, 动态应用安全测试, 安全合规, 恶意软件分析, 毕业设计, 灰盒测试, 白盒测试, 网络代理, 自动化安全评估, 蓝队分析, 证据归档, 请求拦截, 软件开发, 逆向工具, 黑盒测试