test: add hardening acceptance gates and deployment docs

Author: bx33661

.github/workflows/ci.yml

@@ -1,74 +1,65 @@
 name: CI
 
 on:
-  push:
-    branches:
-      - main
   pull_request:
-  workflow_dispatch:
+  push:
+    branches: [main]
 
 permissions:
   contents: read
+  security-events: write
 
 jobs:
-  python:
-    name: Python checks
+  quality:
     runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_DB: pure_codeql
+          POSTGRES_USER: pure_codeql
+          POSTGRES_PASSWORD: pure_codeql
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U pure_codeql"
+          --health-interval 5s --health-timeout 3s --health-retries 20
+      redis:
+        image: redis:8-alpine
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s --health-timeout 3s --health-retries 20
+    env:
+      DATABASE_URL: postgresql+asyncpg://pure_codeql:pure_codeql@127.0.0.1:5432/pure_codeql
+      REDIS_URL: redis://127.0.0.1:6379/0
     steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
+      - uses: actions/setup-python@v5
         with:
-          python-version-file: .python-version
-
-      - name: Verify lockfile
-        run: uv lock --check
-
-      - name: Install dependencies
-        run: uv sync --locked
-
-      - name: Lint (ruff)
-        run: uvx ruff check pure_auto_codeql Analyze.py config.py test
-
-      - name: Run tests
-        run: uv run pytest -q
-
-      - name: Compile Python modules
-        run: uv run python -m compileall -q Analyze.py pure_auto_codeql
-
-
-      - name: Check diff whitespace
-        run: git diff --check
+          python-version: "3.13"
+      - run: uv sync --frozen --dev
+      - run: uv run ruff check pure_auto_codeql test migrations
+      - run: uv run pyright
+      - run: uv run python -m compileall -q Analyze.py pure_auto_codeql migrations
+      - run: uv run alembic upgrade head
+      - run: uv run pytest -m "not real_codeql and not real_llm" --cov --cov-report=xml
+      - run: uv run pip-audit
+      - run: npm ci && npm run build && npm test && npm audit --audit-level=moderate
+        working-directory: tools/mcp_ripgrep
 
-  mcp-ripgrep:
-    name: MCP ripgrep checks
+  codeql-golden:
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: tools/mcp_ripgrep
     steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v6
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
         with:
-          node-version: "22"
-          cache: npm
-          cache-dependency-path: tools/mcp_ripgrep/package-lock.json
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Audit dependencies
-        run: npm audit --audit-level=high
-
-      - name: Build
-        run: npm run build
+          python-version: "3.13"
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: java-kotlin, python, c-cpp
+      - run: uv sync --frozen --dev
+      - run: uv run pytest -m real_codeql -q

.github/workflows/real-llm.yml

@@ -0,0 +1,31 @@
+name: Real LLM contract
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "23 3 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    env:
+      RUN_REAL_LLM: "1"
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      REAL_LLM_MODEL: ${{ vars.REAL_LLM_MODEL || 'gpt-5-mini' }}
+      REAL_LLM_MAX_USD: ${{ vars.REAL_LLM_MAX_USD || '0.05' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --frozen --dev
+      - run: uv run pytest -m real_llm -q
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: real-llm-contract
+          path: outputs/evals/real-llm-contract.json

README.md

@@ -241,6 +241,11 @@ output/
 ## API 服务
 
 ```bash
+# 推荐：完整持久化 API/Worker 环境
+export API_AUTH_TOKEN="change-me"
+docker compose up --build
+
+# 单进程兼容模式
 uv run uvicorn pure_auto_codeql.api.server:app --host 127.0.0.1 --port 8000
 
 # 或
@@ -253,14 +258,15 @@ uv run pure-auto-codeql serve --host 127.0.0.1 --port 8000
 | 监听地址 | 仅 `127.0.0.1` |
 | 导入范围 | `API_IMPORT_SOURCES_DIR`（默认仓库内 `imports/`） |
 | 构建命令 | 请求体中默认禁用 |
-| 鉴权 | 设置 `API_AUTH_TOKEN` 后需 Bearer Token |
+| 鉴权 | 非回环监听强制 `API_AUTH_TOKEN`；支持哈希与轮换 |
+| 持久化 | PostgreSQL 权威状态，Redis Streams 任务与事件 |
 
 ```bash
 export API_AUTH_TOKEN="change-me"
 curl -H "Authorization: Bearer change-me" http://127.0.0.1:8000/api/projects
 ```
 
-更多： [API README](pure_auto_codeql/api/README.md) · [SSE 参考](pure_auto_codeql/api/SSE_REFERENCE.md)
+更多： [API README](pure_auto_codeql/api/README.md) · [SSE 参考](pure_auto_codeql/api/SSE_REFERENCE.md) · [部署](docs/deployment.md)
 
 ---
 
@@ -273,6 +279,7 @@ PureAutoCodeQL/
 │   ├── agents/                 # CVE · Sink · Source · CodeQL 多智能体
 │   ├── application/            # CLI 与 API 共享工作流
 │   ├── api/                    # FastAPI + SSE
+│   ├── platform/ · worker.py   # PostgreSQL/Redis 持久化任务平台
 │   ├── cli/ · core/ · services/ · tools/
 │   ├── information/ · prompts/ · utils/
 │   ├── config/                 # LLM 配置实现
@@ -310,6 +317,9 @@ from pure_auto_codeql.configuration import get_llm_config, LLMRole
 | [docs/cpp/CPP_TWO_STEP_BUILD_GUIDE.md](docs/cpp/CPP_TWO_STEP_BUILD_GUIDE.md) | C/C++ 建库 |
 | [docs/codeql_lsp_troubleshooting.md](docs/codeql_lsp_troubleshooting.md) | CodeQL LSP 排查 |
 | [docs/package_architecture.md](docs/package_architecture.md) | 包结构 |
+| [docs/deployment.md](docs/deployment.md) | Compose 与 Kubernetes 部署 |
+| [docs/language_capabilities.md](docs/language_capabilities.md) | 三语言能力矩阵 |
+| [docs/api_v1_migration.md](docs/api_v1_migration.md) | API v1 迁移 |
 
 ---
 
@@ -318,6 +328,8 @@ from pure_auto_codeql.configuration import get_llm_config, LLMRole
 ```bash
 uv run pytest -q
 uv lock --check
+uv run ruff check pure_auto_codeql test migrations
+uv run pyright
 uv run python -m compileall -q Analyze.py pure_auto_codeql
 ```
 

docs/api_v1_migration.md

@@ -0,0 +1,13 @@
+# API v1 migration
+
+- 基础路径从 `/api` 改为 `/api/v1`；旧路径暂时兼容。
+- 创建响应新增 `run_id`、`effective_config`、`event_url`，初始状态为 `queued`。
+- `completed` 拆为 `completed_with_findings` 和 `completed_no_findings`；另有
+  `partial`、`cancelled`、`timed_out`。
+- 结果改为结构化步骤、错误、manifest、Artifact 清单和精选路径。
+- 被关闭或不支持的步骤为 `skipped`。
+- SSE 新增 `id:` 行和统一事件对象；重连传 `Last-Event-ID`。
+- `requirement`、`max_rounds`、所有步骤开关、超时与恢复选项现在都会进入有效
+  配置并改变实际执行。
+- 多副本部署必须配置 PostgreSQL 与 Redis，并独立启动 Worker。
+- `Analyze.py` 仍转发新 CLI，不在 v1 移除。

docs/codeql_breakpoint_detection_README.md

@@ -121,7 +121,7 @@ python demo_breakpoint_detection.py
 1. 断点检测功能在查询结果为空时自动触发
 2. 分析结果会保存到`breakpoint_analysis.md`文件中
 3. 生成的`isAdditionalFlowStep`条件需要根据具体场景进行调整
-4. 系统支持多种编程语言，但目前主要针对Java和Python进行了优化
+4. Java、Python 与 C/C++ 均通过语言能力注册表选择模板、LSP、断流恢复和回退策略
 
 ## 贡献
 
@@ -135,4 +135,4 @@ python demo_breakpoint_detection.py
 
 ## 许可证
 
-本项目采用MIT许可证。详情请参阅LICENSE文件。
+本项目采用MIT许可证。详情请参阅LICENSE文件。

docs/deployment.md

@@ -0,0 +1,44 @@
+# Deployment
+
+## Docker Compose
+
+```bash
+export API_AUTH_TOKEN='replace-with-a-long-random-token'
+docker compose up --build
+curl http://127.0.0.1:8000/health
+```
+
+服务包括 API、Worker、PostgreSQL、Redis，以及 `--profile s3` 可启用的 MinIO。
+`migrate` 在 API/Worker 前执行 Alembic。PostgreSQL 是权威状态源；Redis 只承载
+至少一次任务投递和有保留上限的事件历史。
+`/health` 同时验证 PostgreSQL、Alembic 版本、Redis、consumer group 和活跃
+Worker 心跳；Worker 自身健康检查使用相同的迁移与队列消费者条件。
+
+API/Worker 镜像以 UID 10001、只读根文件系统、`no-new-privileges`、全部
+capability 删除、PID/CPU/内存限制运行。CodeQL C/C++ Docker 构建默认禁网、
+非 root、只读根文件系统、只读源码挂载，并限制 PID、内存、CPU 和临时磁盘。
+情报获取如需网络，应作为独立受控阶段部署。
+
+常用变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `DATABASE_URL` | `postgresql+asyncpg://...` |
+| `REDIS_URL` | Redis Streams 地址 |
+| `API_AUTH_TOKEN` | 逗号分隔轮换 Token，或 `sha256:<hex>` |
+| `API_RATE_LIMIT_PER_MINUTE` | 单客户端每分钟请求上限 |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP HTTP Collector |
+
+## Kubernetes 迁移
+
+API 与 Worker 使用相同镜像、不同 command；API Deployment 可横向扩展，Worker
+按队列压力扩展。把 PostgreSQL、Redis 和 S3 替换为托管服务，使用同一环境变量
+契约。运行 `alembic upgrade head` 的 Job 必须先于新版本 rollout。Worker 的
+termination grace period 应大于进程组清理时间；任务租约到期后会由其他 Worker
+通过 `XAUTOCLAIM` 恢复。
+
+ArtifactStore 的数据库记录只包含哈希、大小、媒体类型和定位信息。生产使用
+S3-compatible store，本地开发使用运行目录文件系统。
+
+模板优化默认关闭；启用后只在 `temp/template_refinement_candidates/` 生成候选
+unified diff，不会修改生产提示模板。

docs/language_capabilities.md

@@ -0,0 +1,15 @@
+# Language capability matrix
+
+| 能力 | Java | Python | C/C++ |
+| --- | --- | --- | --- |
+| Source/Sink 定位 | 完整 | 完整 | 完整 |
+| Source→Sink 路径结构 | 完整 | 完整 | 完整 |
+| CodeQL 模块化 DataFlow API | 支持 | 支持 | 支持 |
+| LSP | CodeQL LSP | CodeQL LSP | CodeQL LSP |
+| 断流恢复 | 可配置 | 可配置 | 可配置 |
+| Source/Sink 回退 | 可配置 | 可配置 | 可配置 |
+| PR 真实黄金案例 | 路径穿越 | 命令注入 | 缓冲区问题 |
+
+能力由 `pure_auto_codeql.services.language_capabilities` 注册。未知语言必须显式
+跳过或失败；不得返回伪成功空结果。Source/Sink 候选统一包含文件、行号、符号、
+证据、置信度和验证状态。文件不存在、行号或证据缺失时只能是 `unverified`。

pyrightconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": [
+    "pure_auto_codeql/analysis_models.py",
+    "pure_auto_codeql/analysis_schemas.py",
+    "pure_auto_codeql/platform",
+    "pure_auto_codeql/api/security.py",
+    "pure_auto_codeql/api/durable_task_manager.py",
+    "pure_auto_codeql/services/artifacts.py",
+    "pure_auto_codeql/services/codeql_composition",
+    "pure_auto_codeql/services/process_control.py",
+    "pure_auto_codeql/worker.py"
+  ],
+  "pythonVersion": "3.13",
+  "typeCheckingMode": "basic"
+}

test/golden/cpp_buffer_overflow/qlpack.yml

@@ -0,0 +1,4 @@
+name: pure-auto-codeql/golden-cpp
+version: 0.0.0
+dependencies:
+  codeql/cpp-all: "*"

test/golden/cpp_buffer_overflow/query.ql

@@ -0,0 +1,33 @@
+/**
+ * @name Golden C buffer overflow
+ * @description Environment-controlled data indexes a fixed-size buffer.
+ * @kind path-problem
+ * @problem.severity warning
+ * @security-severity 9.8
+ * @precision high
+ * @id pure-auto-codeql/golden-cpp-buffer-overflow
+ * @tags security external/cwe/cwe-120
+ */
+
+import cpp
+import semmle.code.cpp.dataflow.new.DataFlow
+import semmle.code.cpp.dataflow.new.TaintTracking
+
+module Config implements DataFlow::ConfigSig {
+  predicate isSource(DataFlow::Node source) {
+    source.asExpr().(FunctionCall).getTarget().hasGlobalName("atoi")
+  }
+
+  predicate isSink(DataFlow::Node sink) {
+    exists(ArrayExpr access |
+      sink.asExpr() = access.getArrayOffset()
+    )
+  }
+}
+
+module Flow = TaintTracking::Global<Config>;
+import Flow::PathGraph
+
+from Flow::PathNode source, Flow::PathNode sink
+where Flow::flowPath(source, sink)
+select sink.getNode(), source, sink, "Environment-controlled index may access outside the buffer."