From 3cf28d7a4ce3536f5c97e074cc4c9848412832fb Mon Sep 17 00:00:00 2001 From: rookiestar28 Date: Wed, 8 Apr 2026 03:36:21 +0800 Subject: [PATCH] docs: mirror residual security planning references --- ...ql_and_secret_scanning_policy_reference.md | 74 +++++++++++++++ .../github_codeql_baseline_reference.md | 37 ++++++++ ...github_security_residual_wave_reference.md | 94 +++++++++++++++++++ .../residual_security_execution_chain.md | 49 ++++++++++ 4 files changed, 254 insertions(+) create mode 100644 docs/release/codeql_and_secret_scanning_policy_reference.md create mode 100644 docs/release/github_codeql_baseline_reference.md create mode 100644 docs/release/github_security_residual_wave_reference.md create mode 100644 docs/release/residual_security_execution_chain.md diff --git a/docs/release/codeql_and_secret_scanning_policy_reference.md b/docs/release/codeql_and_secret_scanning_policy_reference.md new file mode 100644 index 0000000..bb56c8f --- /dev/null +++ b/docs/release/codeql_and_secret_scanning_policy_reference.md @@ -0,0 +1,74 @@ +# CodeQL and Secret Scanning Policy Reference + +Date: 2026-04-08 +Scope: Repository planning guidance for GitHub-native security scanning policy during and after the residual alert wave. + +## 1. Why CodeQL Belongs in GitHub Actions + +This repository has a large security surface: + +- Python backend services +- JavaScript frontend and test helpers +- GitHub Actions workflows +- connector ingress paths +- filesystem and model-management flows + +The residual GitHub findings demonstrate that static security analysis is catching issues that ordinary local happy-path tests do not reliably surface. + +The correct home for CodeQL in this repository is the GitHub Actions security-validation layer, not the mandatory local development loop. + +## 2. Local vs Remote Validation Boundary + +Local validation should focus on: + +- targeted regressions for the changed bug surface +- repo-local contract tests +- the smallest credible transaction seam for each fix + +GitHub-hosted validation should own: + +- CodeQL scans +- code-scanning alert lifecycle +- long-running static dataflow analysis +- alert triage over the default branch + +## 3. Recommended CodeQL Rollout Model + +Recommended rollout order: + +1. enable repository-native CodeQL in GitHub Actions +2. start in visibility/baseline mode +3. review new findings against changed files first +4. graduate to stricter gating only after the backlog is reduced + +Recommended initial policy: + +- languages: Python, JavaScript/TypeScript, GitHub Actions +- query suite: begin with standard security queries; expand only if runtime/cost remains acceptable +- gating: report-only at first, then fail on new high-severity findings after baseline stabilization + +## 4. Secret Scanning Policy + +Secret-scanning findings must be handled differently from CodeQL findings: + +- removing or editing repository content does not automatically guarantee closure +- historical example values can continue to alert +- closure requires provenance review + +Before closing a secret-scanning alert: + +1. determine whether the value was ever real or was always an example / placeholder +2. confirm whether any rotation or revocation is required +3. avoid copying raw secret material into planning docs, issue text, or commit messages +4. record the closure rationale in planning and implementation evidence + +## 5. Residual-Wave Review Checklist + +For each remaining GitHub Security family: + +- identify whether the finding is a true vulnerability, a scanner-visible dangerous pattern, or a probable false positive +- prefer code changes that make the safe boundary obvious to both humans and scanners +- add a hot-spot comment at the fix point when regression risk is high +- add targeted regression coverage if a local seam exists +- verify GitHub rescans after push +- dismiss only as a last resort, with recorded rationale diff --git a/docs/release/github_codeql_baseline_reference.md b/docs/release/github_codeql_baseline_reference.md new file mode 100644 index 0000000..d146e21 --- /dev/null +++ b/docs/release/github_codeql_baseline_reference.md @@ -0,0 +1,37 @@ +# GitHub CodeQL Baseline Reference + +Date: 2026-04-08 + +## Purpose + +This note records the repository decision for GitHub CodeQL rollout and the specific operational assumptions used in `S82`. + +## Official GitHub References Reviewed + +- GitHub Docs: `Configuring default setup for code scanning` + - Default setup is recommended when first enabling code scanning because it chooses the simplest working analysis method automatically. + - Default setup can be edited for languages/query-suite choices, but it remains UI-managed. +- GitHub Docs: `Configuring advanced setup for code scanning` + - Advanced setup is the path for repository-owned workflow configuration. + - Advanced setup uses a committed workflow file and standard GitHub Actions syntax. + - The generated workflow normally scans on `push`, `pull_request`, and schedule. +- GitHub Docs: `CodeQL code scanning for compiled languages` + - `build-mode: none` is valid for interpreted languages and is acceptable for Python and JavaScript/TypeScript in this repository. + +## Repository Decision + +- Keep CodeQL in the GitHub Actions security-validation layer, not as a new local mandatory SOP command. +- Use an in-repo workflow (`.github/workflows/codeql.yml`) so security scanning policy is reviewable in git. +- Start visibility-first: + - no immediate merge-blocking policy based solely on CodeQL + - use findings as triage input while the backlog is still being reduced +- Cover the repository languages that matter for the current risk surface: + - `python` + - `javascript-typescript` + - `actions` + +## Operational Notes + +- The repository currently shows CodeQL alerts generated by GitHub's dynamic/default setup pipeline. +- Committing `codeql.yml` creates the repository-owned advanced-setup baseline, but the repository owner may still need to switch GitHub Security settings from default setup to advanced setup if the UI-managed default remains authoritative. +- Local acceptance for CodeQL workflow changes must use repo-local seam tests against the workflow contract; do not require a full local CodeQL run unless a future task explicitly asks for it. diff --git a/docs/release/github_security_residual_wave_reference.md b/docs/release/github_security_residual_wave_reference.md new file mode 100644 index 0000000..b94578f --- /dev/null +++ b/docs/release/github_security_residual_wave_reference.md @@ -0,0 +1,94 @@ +# GitHub Security Residual Wave Reference + +Date: 2026-04-08 +Scope: Residual GitHub Security findings that remained open after the first `S73-S81` remediation wave. + +## 1. Purpose + +This reference captures the follow-up repair strategy for the residual GitHub Security findings that still point at the current `main` branch after the initial CodeQL / Dependabot cleanup wave. + +This document is planning-only guidance. It is not itself an implementation record. + +## 2. Current Residual Findings Baseline + +Authenticated GitHub Security review showed this residual baseline at intake: + +- Dependabot: `0` open alerts +- Code scanning: `19` open alerts +- Secret scanning: `1` open alert + +Residual CodeQL families at intake: + +1. `py/path-injection` + - current concentration: `services/model_manager_transfer.py` + - count at intake: `9` +2. `py/weak-sensitive-data-hashing` + - current concentration: `services/redaction.py`, `services/audit.py`, `services/bridge_token_lifecycle.py` + - count at intake: `3` +3. `py/stack-trace-exposure` + - current concentration: `connector/platforms/slack_webhook.py`, `connector/platforms/feishu_webhook.py` + - count at intake: `2` +4. `py/clear-text-logging-sensitive-data` + - current concentration: `api/bridge.py`, `services/audit.py` + - count at intake: `2` +5. `py/clear-text-storage-sensitive-data` + - current concentration: `services/audit.py` + - count at intake: `1` +6. `py/xml-bomb` + - current concentration: `connector/platforms/wechat_webhook.py` + - count at intake: `1` +7. `js/incomplete-sanitization` + - current concentration: `tests/e2e/specs/notifications.spec.js` + - count at intake: `1` + +Residual secret-scanning family: + +- `Tencent WeChat API App ID` + - count at intake: `1` + - observed as a historical docs/example-style finding pending confirmation and closure workflow + +## 3. Repair Principles + +- Prefer real code fixes over dismissals. +- Keep the repair chain scoped to the exact residual findings. +- Add focused guard comments at high-risk fix points. +- Add or extend the smallest credible local regression seam for each repaired family. +- Do not run local CodeQL; GitHub remains the source of truth for scanner retirement. +- For this bug-fixing chain only, do not force unrelated full local test sweeps when no direct seam exists. + +## 4. Proposed Execution Order + +1. Residual logging / storage / identity-tag cleanup +2. Residual model-transfer path-boundary cleanup +3. Secret-scanning provenance review and closure handling +4. GitHub Security rescan verification and dismiss/close workflow +5. Repository-native CodeQL GitHub Actions baseline activation + +## 5. Acceptance Model + +Each implementation item in the chain should follow: + +1. plan file +2. targeted implementation +3. targeted verification +4. implementation record +5. acceptance commit + +The chain-wide source of truth for test procedure remains: + +- `tests/TEST_SOP.md` +- `tests/E2E_TESTING_NOTICE.md` +- `tests/E2E_TESTING_SOP.md` + +For this residual GitHub Security chain, the explicit local validation strategy is: + +- reproduce and pin the exact local seam when possible +- run targeted regressions for the affected contract surface +- do not run local full CodeQL +- use GitHub rescans after push as the authoritative scanner-retirement check + +## 6. Closure Policy + +- Code scanning alerts should be fixed in code first and then re-checked after GitHub rescans the pushed `main` branch. +- Secret-scanning alerts require explicit provenance review before closure. +- False positives may be dismissed only after the code/test surface is demonstrably safe and the dismissal rationale is recorded. diff --git a/docs/release/residual_security_execution_chain.md b/docs/release/residual_security_execution_chain.md new file mode 100644 index 0000000..a198f08 --- /dev/null +++ b/docs/release/residual_security_execution_chain.md @@ -0,0 +1,49 @@ +# Residual Security Execution Chain + +Date: 2026-04-08 +Roadmap chain: `S88 -> S89 -> S90 -> S91` + +## 1. Purpose + +This document mirrors the active execution chain for the remaining GitHub Security findings after the first remediation wave and the initial residual follow-up fixes. + +It is intended as a repo-visible planning reference in `docs/` and should stay aligned with `.planning/roadmap.md` and `.planning/roadmap/open/SECURITY_OPEN.md`. + +## 2. Active Item Order + +1. `S88`: GitHub Security residual alert verification, dismissal, and closure execution wave +2. `S89`: Residual audit and bridge alert retirement sweep +3. `S90`: Residual model-manager path-boundary false-positive retirement wave +4. `S91`: GitHub code-scanning mode switch and final residual alert closure wave + +## 3. Current State + +- `S88` is the umbrella verification item and remains open until GitHub rescans, final dismissals, and the secret-scanning closure workflow are complete. +- `S89` is the active repair lane for the remaining audit-related scanner findings. +- `S90` covers the remaining `services/model_manager_transfer.py` `py/path-injection` findings after the earlier bounded-path hardening. +- `S91` is the final GitHub-side execution wave that requires authenticated repository administration and alert-write capability. + +## 4. Execution Rules + +- Add hotspot comments at every high-risk repair seam. +- Update or add the smallest credible regression seam for each fix. +- Use targeted local tests for the changed contract surface. +- Use GitHub rescans after push as the source of truth for code-scanning retirement. +- Do not dismiss unresolved true positives. +- Do not close the historical secret-scanning alert until provenance and placeholder status are fully confirmed. + +## 5. Current Remaining Risk Shape + +After the latest rescans, the remaining residual families are: + +- audit-related CodeQL alerts still attached to `services/audit.py` +- model-manager `py/path-injection` alerts in `services/model_manager_transfer.py` +- one historical secret-scanning alert tied to a WeChat App ID-shaped documentation example + +## 6. Expected End State + +This chain is complete only when: + +- the remaining code-scanning alerts are either fixed in code or dismissed with explicit false-positive rationale +- the secret-scanning alert is manually closed with recorded provenance evidence +- the repository uses the committed advanced CodeQL workflow as its authoritative scanner baseline