E-Gregorio/qasl-test-security

## 📸 可视化预览

Executive PDF Report 3 pages · INGRID corporate style	Dictamen Forense CFQI 1 page · AFQI forensic style
Grafana — Executive Overview Severity KPIs, donut, CFQI per project, 30-day trend	Grafana — CFQI Forensic Analysis 4 gauges (overall + D1/D2/D3) + per-project audit table
Grafana — OWASP Top 10 & Compliance Coverage by category, top criticals, MTTR SLA	Grafana — Folder view Three dashboards under "QASL Test Security"
FastAPI Swagger UI Normalizer service — interactive API docs	OpenAPI JSON Machine-readable contract for client generation

## 📑 目录 1. [QASL 生态系统](#1-qasl-生态系统) 2. [与众不同之处](#2-与众不同之处) 3. [架构](#3-架构) 4. [前置条件](#4-前置条件) 5. [安装步骤（按顺序执行）](#5-安装步骤按顺序执行) 6. [首次运行验证](#6-首次运行验证) 7. [日常操作](#7-日常操作) - [7.1 Grafana 仪表板](#71-grafana-仪表板) - [7.2 FastAPI 规范化器](#72-fastapi-规范化器) - [7.3 取证 PDF 报告](#73-取证-pdf-报告) 8. [CFQI 算法](#8-cfqi-算法) 9. [标准与合规](#9-标准与合规) 10. [仓库结构](#10-仓库结构) 11. [故障排除](#11-故障排除) 12. [路线图](#12-路线图) 13. [作者、许可证与免责声明](#13-作者许可证与免责声明) ## 🧬 1. QASL 生态系统 此模块是 **QASL** *(质量保证安全实验室)* 生态系统的一部分： ``` QASL Ecosystem ├── MATHCORE ← mathematical & statistical engine ├── INGRID ← AI/LLM Security Testing (AFQI algorithm) └── QASL Test Security ← Application Security Testing (CFQI algorithm) ← you are here ``` **INGRID** 使用 **AFQI** 算法对 AI 系统进行取证审计。**QASL 测试安全** 则使用 **CFQI** 算法对传统应用进行同样的测试 — 这是自然延伸的兄弟项目，应用于代码领域。 | 模块 | 领域 | 算法 | 状态 | |---|---|---|---| | **MATHCORE** | 数学/统计引擎 | — | 共享核心 | | **INGRID** | AI / LLM 安全测试 | **AFQI** v1.0 | 生产环境 | | **QASL 测试安全** ← *本项目* | 应用安全测试 | **CFQI** v1.0 | 生产环境 | ## 🎯 2. 与众不同之处 ### 2.1 CFQI 算法 — 代码取证质量指数 一款专有评分算法，仿照 AFQI 设计，从三个取证维度计算产生单一的 **0-100 分及等级 A/B/C/D/F**： ``` CFQI = 100 · [α·S(c) + β·D(d) + γ·R(r)] − Λ(C) · μ(R) S(c) = Static layer (SAST + Secrets + IaC) α = 0.35 D(d) = Dependencies layer (SCA + SBOM + Container) β = 0.30 R(r) = Runtime layer (DAST + API + Fuzzing) γ = 0.35 Λ(C) = Compliance penalty (uncovered OWASP Top 10 categories) μ(R) = VCR risk multiplier (Value · Cost · Risk profile) ``` 完整的数学论证见 [`docs/cfqi-algorithm.md`](`lsof -i :3003,:8001,:5433`（macOS/Linux） | ## 🚀 5. 安装步骤（按顺序执行） ### 5.1 — 克隆仓库 ``` git clone https://github.com/E-Gregorio/qasl-test-security.git cd qasl-test-security ``` ### 5.2 — 创建环境文件 ``` # Windows (PowerShell) Copy-Item .env.example .env ``` ``` # macOS / Linux cp .env.example .env ``` ### 5.3 — 启动 Docker 栈 ``` docker compose up -d ``` 这将： 1. 拉取 `postgres:16-alpine`、`grafana/grafana:10.4.2`（首次共约 200 MB） 2. 构建本地 `normalizer` 镜像（Python 3.12-slim，约 150 MB） 3. 启动所有 3 个服务并配置健康检查 4. 自动配置 Grafana 数据源和 3 个仪表板 **首次启动请等待 60–90 秒**，然后验证： ``` docker compose ps ``` 预期结果：3 个容器 `qasl-test-postgres`、`qasl-test-normalizer`、`qasl-test-grafana` — 全部 `running`，postgres 和 normalizer 状态为 `healthy`。 ### 5.4 — 安装种子依赖 ``` # Windows pip install psycopg2-binary ``` ``` # macOS / Linux pip3 install psycopg2-binary ``` ### 5.5 — 填充合成演示数据（4 个项目，约 96 个发现） ``` # Windows — PYTHONIOENCODING required because Python 3.13 stdout uses cp1252 $env:PYTHONIOENCODING = "utf-8" python seed\seed_demo.py ``` ``` # macOS / Linux python3 seed/seed_demo.py ``` 预期输出（最后几行）： ``` ✅ Seed completed: 4 projects, 96 findings 📊 Open Grafana at http://localhost:3003 ``` ### 5.6 — 安装 PDF 生成器依赖 ``` cd pdf-generator npm install cd .. ``` ### 5.7 — 生成两份取证 PDF（来自 Postgres 的真实数据） ``` # Windows $env:DATABASE_URL = "postgresql://qasl_admin:changeme_dev_only@localhost:5433/qasl_security" cd pdf-generator node generate-cfqi-report.mjs --project=PaymentService-API cd .. ``` ``` # macOS / Linux export DATABASE_URL="postgresql://qasl_admin:changeme_dev_only@localhost:5433/qasl_security" cd pdf-generator node generate-cfqi-report.mjs --project=PaymentService-API cd .. ``` 输出到 `pdf-generator/reports/`： - `QASL-Executive-Report-PaymentService-API-{date}.pdf`（3 页） - `QASL-CFQI-Dictamen-Forense-PaymentService-API-{date}.pdf`（1 页） ### 5.8 — 打开仪表板 | URL | 凭据 | |---|---| | http://localhost:3003 | `admin / q_admin` | | http://localhost:8001/docs | —（开放） | | http://localhost:8001/redoc | —（开放） | ### 🆚 一键式替代方案（Windows） 使用捆绑的启动器跳过步骤 5.3–5.8： ``` .\launch-demo.ps1 -Pdf ``` 一次性执行启动/填充/验证/PDF/浏览器步骤。详见 [`launch-demo.ps1`](

| 仪表板 | URL | 受众 | |---|---|---| | **Executive Overview** | http://localhost:3003/d/qasl-executive-overview | CISO、管理层 | | **CFQI Forensic Analysis** | http://localhost:3003/d/qasl-cfqi-forensic | 安全工程师 | | **OWASP Top 10 & Compliance** | http://localhost:3003/d/qasl-owasp-compliance | 审计员、合规人员 | #### 执行概要

4 个严重性 KPI、按扫描类型分布的环形图、各项目 CFQI 表格、30 天漏洞趋势。 #### CFQI Forensic Analysis

4 个仪表 — 总体 CFQI 及各维度得分（D1 静态 / D2 依赖 / D3 运行时）— 以及每个项目的取证审计表。 #### OWASP Top 10 和合规性

OWASP 类别分布、关键/高危发现前几名、各严重性的 MTTR（用于 SLA 跟踪）。 ### 7.2 FastAPI 规范化器 规范化器接收扫描器原始输出，将发现结果规范化为统一模式，通过 SHA256 指纹去重，并持久化到 PostgreSQL。

| 方法 | 路径 | 标签 | 用途 | |---|---|---|---| | `GET` | `/health` | meta | 存活性和数据库连接检查 | | `GET` | `/` | meta | 服务标识和端点目录 | | `POST` | `/ingest` | ingestion | 提交扫描器输出（SARIF/JSON） | | `GET` | `/findings/{project_name}` | query | 活跃发现，按严重性排序 | | `GET` | `/cfqi/{project_name}` | query | 最新 CFQI 细分 | | `GET` | `/projects` | query | 项目组合视图，每个项目含 CFQI | 三个文档端点： - **Swagger UI** — http://localhost:8001/docs（交互式 *try-it-out*） - **ReDoc** — http://localhost:8001/redoc（整洁阅读布局） - **OpenAPI JSON** — http://localhost:8001/openapi.json（机器可读）

#### 通过辅助脚本上传扫描结果（bash / WSL） ``` ./scripts/upload_to_normalizer.sh PaymentService-API semgrep SAST semgrep-output.sarif ``` #### 或通过 curl 上传 ``` curl -X POST http://localhost:8001/ingest \ -H "Content-Type: application/json" \ -d @payload.json ``` ### 7.3 取证 PDF 报告 每次运行生成两份 PDF，有意分开。

QASL-Executive-Report (3 pp) INGRID corporate · CISO/management	QASL-CFQI-Dictamen-Forense (1 p) AFQI pericial · auditor/compliance

#### 生成（演示模式 — 合成发现） ``` cd pdf-generator node generate-cfqi-report.mjs --demo ``` #### 生成（来自 Postgres 的真实数据） ``` # Windows $env:DATABASE_URL = "postgresql://qasl_admin:changeme_dev_only@localhost:5433/qasl_security" node generate-cfqi-report.mjs --project=PaymentService-API ``` ``` # macOS / Linux DATABASE_URL="postgresql://qasl_admin:changeme_dev_only@localhost:5433/qasl_security" \ node generate-cfqi-report.mjs --project=PaymentService-API ``` 两份 PDF 都是 **确定性** 的：相同的输入发现 → 相同的分数、相同的描述、相同的等级。这种可重现性使 CFQI 能够经受监管机构的审查。 ## 📐 8. CFQI 算法 ``` CFQI = 100 · [α·S(c) + β·D(d) + γ·R(r)] − Λ(C) · μ(R) ``` 三个加权维度，减去合规惩罚，除以风险乘数。 | 符号 | 含义 | 默认值 | |---|---|---| | `S(c)` | **D1 静态**层（SAST + 密钥泄露 + IaC） | 权重 α = 0.35 | | `D(d)` | **D2 依赖**层（SCA + 容器） | 权重 β = 0.30 | | `R(r)` | **D3 运行时**层（DAST + API + 模糊测试） | 权重 γ = 0.35 | | `Λ(C)` | 合规惩罚（未覆盖的 OWASP 类别） | 0–10 分 | | `μ(R)` | VCR 风险乘数（价值 · 成本 · 风险） | 1.0 标准 · 1.5 高 · 2.0 严重 | #### 严重性权重（每个发现扣除的分数） | 严重性 | 惩罚 | |---|---| | `critical` | 25 | | `high` | 10 | | `medium` | 3 | | `low` | 1 | | `info` | 0 | #### 等级映射 | 分数 | 等级 | 判定 | 行动 | |---|---|---|---| | ≥ 90 | **A** | 安全 | 保持控制措施。季度审查。 | | 75–89 | **B** | 可运行 | 计划在下个迭代修复高危问题。 | | 60–74 | **C** | 有保留意见 | 重新评估最弱维度。 | | 40–59 | **D** | 高风险 | 暂停部署。进行威胁建模。 | | < 40 | **F** | 不可接受 | 不得部署。需外部审计。 | 参考实现：[`pdf-generator/lib/cfqi-calculator.mjs`]( **QASL 生态系统** · MATHCORE + INGRID + QASL 测试安全 *OWASP Top 10 2021 · OWASP ASVS 4.0 · NIST SP 800-218 (SSDF) · ISO/IEC 27001*