diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af06c036..84176ddf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,6 +9,10 @@ on: permissions: contents: read +concurrency: + group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: checks: uses: ./.github/workflows/release-checks.yml diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 00000000..95625ebd --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,58 @@ +name: CodeQL + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-22.04 + timeout-minutes: 30 + permissions: + contents: read + actions: read + security-events: write + strategy: + fail-fast: false + matrix: + language: [python, javascript-typescript] + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0 + with: + persist-credentials: false + - name: Initialize CodeQL / 初始化安全扫描 + uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + languages: ${{ matrix.language }} + build-mode: none + queries: security-extended + - name: Analyze and upload results / 扫描并上传结果 + uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + category: /language:${{ matrix.language }} + wait-for-processing: true + + # Stable required-check candidate, independent of docs-only release skips. + checks: + name: CodeQL / checks + if: always() + needs: analyze + runs-on: ubuntu-22.04 + timeout-minutes: 5 + steps: + - name: Require all analyses / 要求全部语言扫描成功 + env: + ANALYSIS_RESULT: ${{ needs.analyze.result }} + run: >- + python -c 'import os, sys; result = os.environ.get("ANALYSIS_RESULT", "missing"); + print("CodeQL analysis / 安全扫描: " + result); sys.exit(0 if result == "success" else 1)' diff --git a/.github/workflows/dsh-plugin.yml b/.github/workflows/dsh-plugin.yml index 08387570..1724e280 100644 --- a/.github/workflows/dsh-plugin.yml +++ b/.github/workflows/dsh-plugin.yml @@ -16,6 +16,10 @@ on: permissions: contents: read +concurrency: + group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: tests: runs-on: ubuntu-22.04 diff --git a/docs/development/validation.md b/docs/development/validation.md index 641691a8..bd3938cd 100644 --- a/docs/development/validation.md +++ b/docs/development/validation.md @@ -53,9 +53,9 @@ Budgets measure stage wall time, not the sum of parallel job limits, and never j ### 过渡与必需检查 / Transition and required checks -当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁;纯文档 PR 按下方白名单跳过重检查,其余仍跑全量 Python。[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,但机型轴、安全扫描、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;PR 和队列各 30 分钟是阶段目标,不代表已强制端到端总上限。 +当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁;纯文档 PR 按下方白名单跳过重检查,其余仍跑全量 Python。[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,安全扫描见下方独立工作流;机型轴、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;PR 和队列各 30 分钟是阶段目标,不代表已强制端到端总上限。 -Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes. Documentation-only PRs use the allowlist below to skip heavy checks; other changes retain full Python selection. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered; hardware tagging, security scanning, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; 30 minutes each for PR and queue are stage targets, not enforced end-to-end deadlines. +Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes. Documentation-only PRs use the allowlist below to skip heavy checks; other changes retain full Python selection. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered. Security scanning uses the independent workflow below; hardware tagging, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; 30 minutes each for PR and queue are stage targets, not enforced end-to-end deadlines. - 本地 hook 可未安装或被绕过,不能在 GitHub 上普遍阻止 PR 创建。必需 CI 必须复核同一配置;静态失败阻止启动重测试,并使稳定汇总检查失败。/ Local hooks can be absent or bypassed and cannot universally prevent PR creation. Required CI repeats the same configuration; static failure blocks heavy jobs and fails the stable aggregate. - 纯文档变更可跳过重 Python/浏览器任务,但必须保留稳定的必需检查,报告跳过依据并成功结束。合并队列按整个 merge-group 差异判断,不能只看最后一个 PR;无法确定范围时执行完整门禁。/ Documentation-only changes may skip heavy Python/browser jobs, but a stable required check must report the reason and succeed. Queue filtering covers the whole merge-group diff, not only its last PR; uncertain scope runs the full gate. @@ -118,6 +118,39 @@ The final `checks` aggregate preserves its required-check name and always runs. The reusable workflow's `static-checks` defaults to false and is enabled by `ci.yml`; nightly does not duplicate static checks. CI never commits automatic fixes; hook edits remain failures. The PR stage budget is 30 minutes for now. Static has 10 minutes, Python/frontend/each browser job 30 minutes, and the aggregate 5 minutes. These remain per-job limits, not a summed or enforced workflow-wide deadline; improve end-to-end time using actual measurements. +## PR 安全扫描 / PR security scanning + +CodeQL、Release checks 和 DSH plugin checks 在入口工作流按“工作流名称 + 事件 + PR 编号”设置并发组;同一 PR 更新会取消该工作流的旧运行,不同 PR 和工作流互不取消。非 PR 事件按 `run_id` 独立分组且不启用取消,保留每次 main push 的检查和扫描基线。DSH 的路径筛选保持不变。参见 [GitHub 并发控制](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency)。 + +CodeQL, Release checks and DSH plugin checks group entry workflows by workflow name, event and PR number. Updates cancel outdated runs of the same workflow for that PR; different PRs and workflows do not cancel each other. Non-PR events use a unique `run_id` group with cancellation disabled, retaining checks and scan baselines for every main push. DSH path filters remain unchanged. See [GitHub concurrency control](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency). + +[`codeql.yml`](../../.github/workflows/codeql.yml) 对每个 PR(包含 draft 和纯文档变更)独立执行 Python 与 JavaScript/TypeScript CodeQL `security-extended` 分析;不等待 Release checks 的范围筛选。main push 建立合并版本基线,另提供手动运行。两条语言任务并行且互不取消,每条上限 30 分钟,汇总上限 5 分钟;这些不是阶段总墙钟上限。 + +[`codeql.yml`](../../.github/workflows/codeql.yml) independently runs CodeQL `security-extended` analysis for Python and JavaScript/TypeScript on every PR, including drafts and documentation-only changes. It does not depend on Release checks scope selection. Main pushes establish the merged baseline; manual dispatch is also available. Language jobs run in parallel without fail-fast cancellation, with a 30-minute limit each and a 5-minute aggregate limit, not a workflow-wide deadline. + +扫描使用固定提交的官方 Actions、`build-mode: none` 和不保留 Git 凭证的 checkout,不安装应用依赖、不构建应用、不调用模型。默认 token 只读内容,上传分析结果的任务额外拥有 `actions: read` 和 `security-events: write`。使用 `pull_request` 而非 `pull_request_target`,不读取仓库 secrets;fork PR 仍受 GitHub 的首次贡献者审批策略约束。这是源码安全分析,不替代依赖漏洞或容器镜像扫描,也不能证明不存在漏洞。 + +Scanning uses pinned official Actions, `build-mode: none` and checkout without persisted Git credentials. It does not install application dependencies, build the application or call models. The default token reads contents; analysis upload jobs additionally receive `actions: read` and `security-events: write`. It uses `pull_request`, not `pull_request_target`, with no repository secrets; GitHub contributor approval policies still apply to fork PRs. Source analysis does not replace dependency or container-image scanning and cannot prove the absence of vulnerabilities. + +稳定汇总 job `CodeQL / checks` 只接受全部语言分析成功,失败、取消、跳过和缺失结果均失败。它证明扫描执行及上传完成,不根据告警等级自行判断是否允许合并。GitHub 的独立 **Code scanning results / CodeQL** 检查负责 PR 新增行的告警门禁;默认失败阈值包含 error 及 high/critical 安全告警,仓库设置可能覆盖阈值。参见 [PR 告警检查语义](https://docs.github.com/en/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests)。 + +The stable aggregate job `CodeQL / checks` accepts only successful analyses for every language; failed, cancelled, skipped and missing results fail. It proves analysis and upload completion, without deciding merge eligibility from alert severity. GitHub's separate **Code scanning results / CodeQL** check gates alerts on added PR lines; default failure thresholds include error-level and high/critical security alerts, subject to repository overrides. See [PR alert check semantics](https://docs.github.com/en/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests). + +管理员需确认仓库使用 advanced setup、没有冲突的 default setup,并验证首次扫描、fork PR 上传及告警阈值;之后将执行汇总和告警结果检查一并设为 required。仅合入 YAML 不会自动配置仓库保护规则。合并队列支持在后续 PR6 添加 `merge_group`,规则强制在 PR7 处理;完成这些配置前,不宣称安全门禁不可绕过。配置方式见 [CodeQL advanced setup](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning)。 + +An administrator must confirm advanced setup without conflicting default setup, verify the first analysis, fork uploads and alert thresholds, then require both the execution aggregate and alert-result checks. Merging YAML does not configure repository protection rules. PR6 adds `merge_group` support and PR7 handles enforcement; security gates are not claimed to be non-bypassable before those settings are complete. See [CodeQL advanced setup](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning). + +本地契约验证 / Local contract verification: + +```sh +python -m pytest tests/test_ci_security.py -q +python -m pre_commit run --files .github/workflows/codeql.yml tests/test_ci_security.py docs/development/validation.md +``` + +本地检查验证工作流语法、触发与权限边界,以及实际汇总命令对异常状态的拒绝;CodeQL 建库、分析和上传必须以 GitHub Actions 的真实运行结果验收。 + +Local checks verify workflow syntax, trigger/permission boundaries and rejection of unsuccessful states by the actual aggregate command. CodeQL database creation, analysis and upload require a real GitHub Actions run for acceptance. + ## Python 分层与迁移 / Python layers and transition ### 耗时证据 / Timing evidence diff --git a/tests/test_ci_security.py b/tests/test_ci_security.py new file mode 100644 index 00000000..6aa12bce --- /dev/null +++ b/tests/test_ci_security.py @@ -0,0 +1,75 @@ +"""Keep every PR scanned, and execute the stable security aggregate command.""" +import os +from pathlib import Path +import re +import shlex +import subprocess +import sys + +import pytest +import yaml + + +pytestmark = pytest.mark.ready +ROOT = Path(__file__).resolve().parents[1] + + +@pytest.fixture +def workflow(): + return yaml.safe_load((ROOT / '.github/workflows/codeql.yml').read_text(encoding='utf-8')) + + +def test_every_pr_including_docs_and_forks_has_security_checks(workflow): + # PyYAML's YAML 1.1 loader parses GitHub's `on` key as boolean True. + events = workflow[True] + assert events['pull_request'] is None + assert events['push'] == {'branches': ['main']} + assert 'workflow_dispatch' in events + assert 'pull_request_target' not in events + assert workflow['name'] == 'CodeQL' + assert workflow['permissions'] == {'contents': 'read'} + analyze = workflow['jobs']['analyze'] + assert 'if' not in analyze and 'needs' not in analyze + assert {'python', 'javascript-typescript'} <= set(analyze['strategy']['matrix']['language']) + assert analyze['strategy']['fail-fast'] is False + assert analyze['timeout-minutes'] == 30 + + +def test_source_analysis_uses_pinned_actions_and_limited_permissions(workflow): + job = workflow['jobs']['analyze'] + assert job['permissions'] == {'contents': 'read', 'actions': 'read', 'security-events': 'write'} + steps = job['steps'] + assert len(steps) == 3 + assert steps[0]['with']['persist-credentials'] is False + assert all(re.fullmatch(r'[^@]+@[0-9a-f]{40}', step['uses']) for step in steps) + initialize, analyze = steps[1:] + assert initialize['uses'].startswith('github/codeql-action/init@') + assert analyze['uses'].startswith('github/codeql-action/analyze@') + assert initialize['uses'].split('@')[1] == analyze['uses'].split('@')[1] + assert initialize['with'] == { + 'languages': '${{ matrix.language }}', 'build-mode': 'none', 'queries': 'security-extended', + } + assert analyze['with'] == {'category': '/language:${{ matrix.language }}', 'wait-for-processing': True} + assert not any('run' in step or 'continue-on-error' in step or 'if' in step for step in steps) + assert 'secrets.' not in str(job) + + +@pytest.mark.parametrize('status', ['success', 'failure', 'cancelled', 'skipped', 'timed_out', '', 'unknown', None]) +def test_actual_aggregate_command_rejects_every_unsettled_result(workflow, status): + job = workflow['jobs']['checks'] + assert job['name'] == 'CodeQL / checks' + assert job['if'] == 'always()' and job['needs'] == 'analyze' + assert 'continue-on-error' not in job + step = job['steps'][0] + assert step['env'] == {'ANALYSIS_RESULT': '${{ needs.analyze.result }}'} + assert 'if' not in step and 'continue-on-error' not in step + args = shlex.split(step['run']) + assert args[:2] == ['python', '-c'] + env = {**os.environ, 'PYTHONIOENCODING': 'utf-8'} + env.pop('ANALYSIS_RESULT', None) + if status is not None: + env['ANALYSIS_RESULT'] = status + result = subprocess.run([sys.executable, *args[1:]], env=env, + capture_output=True, text=True, encoding='utf-8', timeout=10) + assert (result.returncode == 0) == (status == 'success'), result.stderr + assert 'CodeQL analysis' in result.stdout