跳到主要内容

Bandit Baseline 维护指南

本文档说明如何维护 scripts/lint/bandit_baseline.json 文件。

概述​

Bandit baseline 用于豁免已知的低严重性安全 findings，避免它们阻断 PR。本文件遵循 severity + confidence 分层策略：

严重性置信度处理方式
HIGHHIGH/MEDIUM/LOW阻断 PR（不可豁免）
MEDIUM任意警告但不阻断
LOW任意可豁免到 baseline

Baseline 文件结构​

{
  "generated_at": "2026-07-19",
  "version": "1.0.0",
  "description": "Bandit baseline for known low-severity findings.",
  "findings": [
    {
      "test_id": "B101",
      "severity": "LOW",
      "confidence": "HIGH",
      "file": "tests/test_example.py",
      "line": 42,
      "reason": "assert usage in test file is expected",
      "approved_by": "security-team",
      "approved_at": "2026-07-19"
    }
  ]
}

字段说明​

字段必填说明
test_id✅Bandit test ID（如 B101）
severity✅Finding 严重性（仅 LOW 可豁免）
confidence✅Bandit 置信度
file✅文件路径（相对于仓库根目录）
line✅行号
reason✅豁免原因说明
approved_by✅审批人（security-team 或 admin）
approved_at✅审批日期

添加新 Baseline Finding 的流程​

1. 评估 Finding​

首先确认 finding 不应修复：

  • 必须豁免：仅 LOW severity findings
  • 禁止豁免：HIGH severity findings，必须修复代码

2. 在 PR 中说明​

在添加 baseline finding 的 PR 中：

  1. 说明为什么该 finding 可以豁免
  2. 引用相关 Issue（如有）
  3. 说明是否有计划修复

3. 获取审批​

  • Security Team 或 Admin 审批后方可合并
  • 审批人在 approved_by 字段记录

4. 更新 Baseline 文件​

# 手动添加 finding 到 baseline
# 或运行脚本生成（待实现）

审查与绕过​

baseline findings 的季度审查与通过 skip-security-check 标签紧急绕过 PR 检查，统一遵循 API_EXCEPTIONS.md 中的例外生命周期。

常见 LOW Severity Findings​

Test ID名称常见场景
B101assert_used测试文件中的 assert 语句
B311random_module非加密用途的随机数

参考资料​