项目定位与核心能力

Bandit 是一款面向 Python 源码的静态安全分析工具（Static Analysis Security Testing, SAST），由 PyCQA 维护，最新发布版本为 1.9.4。项目以安全审计为目标，对每个待扫描文件调用 AST 节点级插件，输出按严重程度（severity）与置信度（confidence）分级的缺陷列表。在仓库组织层面，Bandit 把 CLI 拆分为若干独立入口，分别承担主扫描、基线对比与配置生成三类职责。资料来源：bandit/cli/main.py:1-15

CLI 框架通过 stevedore 实现插件式扩展，使得新增检查项（B 系列 ID，例如 B101 assert_used）或新的报告格式（formatter）只需注册 entry-point 即可热加载。资料来源：README.rst:1-30、bandit/cli/main.py:80-110]() 中的 _init_extensions() 调用。

命令行工具矩阵

项目提供三个可执行入口，每个入口职责清晰、独立运行：

资料来源：bandit/cli/main.py:130-160、bandit/cli/baseline.py:60-95、bandit/cli/config_generator.py:60-90。setup.cfg 中通过 entry_points 把上述入口挂到 console_scripts，从而允许用户 pip install bandit` 后直接调用。资料来源：setup.cfg:25-50

快速开始

基本扫描

最小化命令对单文件或目录执行一次性扫描，并在终端输出结果：

bandit -r ./examples/

-r 表示递归扫描子目录；-f 指定输出格式，可选 txt、html、json、xml、screen、custom；-o 把结果写入文件。资料来源：bandit/cli/main.py:200-225

与基线对比

当存在已有 JSON 报告时，可通过 -b 仅报告新增缺陷，常用于 CI 流水线：

bandit -r ./src/ -b previous_report.json -f txt

也可使用 bandit-baseline 自动完成「检出父提交 → 扫描 → 切回当前提交 → 对比」流程。资料来源：bandit/cli/baseline.py:100-140、bandit/cli/baseline.py:160-195`。

生成配置文件

通过配置生成器可得到一份带注释的 YAML 模板，便于版本化管理：

bandit-config-generator -o bandit.yaml

若仅查看插件默认参数而不落盘，可使用 --show-defaults。资料来源：bandit/cli/config_generator.py:95-130、bandit/cli/config_generator.py:140-175`。

内联抑制

在源码行末追加 # nosec 注释即可让 Bandit 跳过该条告警；若需禁用此机制，使用 --ignore-nosec。资料来源：bandit/cli/main.py:170-195

配置加载与排除路径

Bandit 支持通过项目级 .bandit 文件提供默认参数。加载顺序如下：CLI 参数 → INI 文件 → 内置默认值，最终通过 _log_option_source() 标注每个选项的来源。资料来源：bandit/cli/main.py:240-275、bandit/cli/main.py:280-310`。

常见字段包括 exclude（glob 模式）、tests/skips（插件 ID 列表）、recursive、level、confidence、format 等。需要注意的是，社区反馈显示 -x ./mymodule/tests/ 与 .bandit 中的 exclude 在 1.6.x 系列中存在失效问题，需升级或显式使用 -x 兼容路径。该行为在后续版本中已修复。资料来源：bandit/cli/main.py:315-340`，相关讨论见 Issue #488 与 #657。

排除路径既支持 glob 通配符（如 ./.tox,./tests），也支持与 CLI 参数合并——CLI 提供的排除会被附加到配置文件的排除列表之后。资料来源：bandit/cli/main.py:195-215、[bandit/core/constants.py] 中的默认 EXCLUDE` 常量。

下一步

• 阅读 架构与插件机制，理解插件如何基于 AST 节点工作。
• 阅读 报告与基线流程，掌握 JSON 报告字段含义与基线对比细节。
• 阅读 配置文件参考，查阅全部 INI / YAML 字段及其默认值。

See Also

• 架构与插件机制
• 报告格式与输出定制
• 配置文件参考（INI / YAML）
• 持续集成（CI）集成指南

架构概览

Bandit 由三层松耦合模块组成：CLI 层（bandit/cli/）、核心调度层（bandit/core/）以及由 extension_loader 托管的插件层。CLI 命令在解析完参数后，会构造 BanditManager 实例（b_manager），由后者负责遍历目标、调用 AST 测试插件、收集 Issue、并交给 Formatter 输出。资料来源：bandit/cli/main.py:1-9。

flowchart TD
    A[CLI 入口<br/>main.py] --> B[argparse 解析参数]
    B --> C[加载 .bandit INI]
    C --> D[初始化扩展<br/>extension_loader]
    D --> E[_log_option_source 仲裁优先级]
    E --> F[BanditManager]
    F --> G[遍历目标文件]
    G --> H[NodeVisitor 访问 AST]
    H --> I[Tester 调用测试插件]
    I --> J[Issue 收集]
    J --> K[Formatter 输出报告]
    L[bandit-baseline] --> A
    M[bandit-config-generator] --> D

CLI 入口与初始化流程

main() 在最早阶段建立日志记录，并根据 -d/--debug 是否出现切换日志级别（logging.DEBUG/logging.INFO），随后调用 _init_extensions() 加载所有检查器、格式化器和黑名单，填充 extension_mgr。资料来源：bandit/cli/main.py:407-413、bandit/cli/main.py:1-9。

argparse.ArgumentParser 注册的关键参数包括：targets、-r/--recursive、-t/--tests、-s/--skips、--profile、严重级别（-l/--severity，-ll，-lll）、置信度（-i/--confidence，-ii，-iii）、-f/--format、-o/--output、--msg-template、-x/--exclude、-b/--baseline、--ini、--ignore-nosec、--exit-zero 等。资料来源：bandit/cli/main.py:430-540。

默认输出格式依据环境动态决定：当 sys.stdout.isatty() 为真、NO_COLOR 未设置、TERM 不等于 dumb 时使用 screen，否则使用 txt。资料来源：bandit/cli/main.py:496-505。

配置加载与优先级仲裁

Bandit 支持通过 .bandit INI 文件提供默认参数。_get_options_from_ini() 在未显式传入 --ini 时会递归遍历 target 寻找 .bandit 文件；若发现多个则发出警告。资料来源：bandit/cli/main.py:60-83。

CLI 解析完成后，_log_option_source() 按"命令行 → ini → 默认值"的优先级解析最终值，并通过日志标注每项设置的来源。例如 args.severity = _log_option_source(default, cli_val, ini_val, "severity level")。资料来源：bandit/cli/main.py:150-180。

.bandit 配置文件支持的常用键：

资料来源：bandit/cli/main.py:150-220。

社区反馈 #488 与 #657 都指向 1.6.x 时代 .bandit 中 exclude 不被尊重的问题：当用户在命令行显式提供 -x 时，旧实现会忽略 ini 段的同名键。该缺陷正是 _log_option_source 优先级逻辑需要正确处理的场景。资料来源：bandit/cli/main.py:90-110。

测试插件与配置文件生成

bandit-config-generator 通过遍历 extension_loader.MANAGER.plugins，对每个声明了 _takes_config 的插件调用其模块的 gen_config() 函数收集默认值，最终以 YAML 输出。资料来源：bandit/cli/config_generator.py:124-134。

输出模板（template）由三段组成：可用测试 ID 列表（注释形式 # ID : 名称）、tests/skips 列表占位符、以及插件设置块。get_config_settings() 仅当插件函数带 _takes_config 且模块中存在 gen_config 时才会收集，避免无效配置。资料来源：bandit/cli/config_generator.py:38-58。

基准扫描 (Bandit Baseline)

bandit-baseline 通过 GitPython（git）切换到父提交并运行 Bandit 生成 JSON 报告，再切换回当前提交并以该报告作为 -b 参数重新运行，从而只显示新增问题。资料来源：bandit/cli/baseline.py:1-8、bandit/cli/baseline.py:185-210。

运行前置条件校验：必须位于 git 项目根目录、当前工作区不能 dirty、临时文件 _bandit_baseline_run.json_ 不能已存在、不可与 -o 同时使用、输出格式受 valid_baseline_formats = ["txt", "html", "json"] 限制。资料来源：bandit/cli/baseline.py:107-130、bandit/cli/baseline.py:152-170。

baseline_setup() 上下文管理器负责建立临时目录并在退出时清理、还原仓库 HEAD，确保 baseline 子进程失败不会污染工作区。资料来源：bandit/cli/baseline.py:230-240。

已知问题与社区反馈

• 路径排除优先级（#488、#657）：1.6.x 中命令行显式提供 -x 时会忽略 .bandit 中 exclude，现已通过 _log_option_source 修复。资料来源：bandit/cli/main.py:90-180。
• 配置格式扩展（#212、#550）：社区请求支持 setup.cfg 与 pyproject.toml（PEP 518），目前仍以 .bandit INI 为主流。资料来源：bandit/cli/main.py:60-83。
• 精细化跳过（#346）：希望按文件名 glob 跳过 B101 assert_used 等规则，目前只能在 .bandit 中全局 skips。资料来源：bandit/cli/config_generator.py:38-58。

See Also

• Bandit 官方仓库：PyCQA/bandit
• 测试插件列表与 ID：可通过 bandit-config-generator --show-defaults 查看（资料来源：bandit/cli/config_generator.py:38-58）
• baseline 工具：bandit-baseline（资料来源：bandit/cli/baseline.py:1-8）

概述

Bandit 通过三层机制实现灵活的项目级安全扫描配置：YAML/INI 配置文件 用于声明插件开关与插件级参数，路径/插件排除规则 用于在文件级别和检查器级别裁剪扫描范围，插件/扩展加载器 则负责发现并注册所有可用的检查器与格式化器。本页基于仓库内 CLI 入口与核心模块源码,说明这三层机制如何协同工作,以及社区反馈中常见的兼容性与功能缺口。

配置文件与发现流程

Bandit 支持两类配置文件:基于 YAML 的 bandit.yaml(由 BASE_CONFIG = "bandit.yaml" 常量定义)用于插件级参数,以及基于 INI 语法的 .bandit 文件用于整体运行参数。CLI 通过 --ini 参数显式指定 INI 路径,或在未提供时通过 os.walk 在所有 targets 目录中递归查找名为 .bandit 的文件 资料来源：bandit/cli/main.py:73-95。

INI 文件被解析后,_log_option_source() 会按"命令行 > INI > 默认值"的优先级决定每个选项的最终值,并在日志中标注来源(Using command line arg for ... 或 Using ini file for ...) 资料来源：bandit/cli/main.py:165-210。目前 INI 支持的键包括 tests、skips、targets、recursive、aggregate、number、profile、level、confidence、format、msg-template、output、verbose、debug、quiet、ignore-nosec 等 资料来源：bandit/cli/main.py:210-250。

flowchart TD
    A[bandit CLI 启动] --> B{提供 --ini?}
    B -- 是 --> C[读取指定 .bandit]
    B -- 否 --> D[在 targets 中 os.walk 查找 .bandit]
    C --> E[解析 INI 为字典]
    D --> E
    E --> F[加载 bandit.yaml<br/>BASE_CONFIG]
    F --> G[_log_option_source 合并]
    G --> H[命令行参数覆盖]
    H --> I[BanditManager.discover_files]
    I --> J[b_mgr.run_tests]

值得注意的是,社区曾多次请求支持 setup.cfg(issue #212)与 pyproject.toml(issue #550)作为配置文件来源,但当前代码仅原生支持 .bandit 与 bandit.yaml。

路径与插件排除规则

路径排除

-x / --exclude 参数接受逗号分隔的 glob 模式列表,默认值为 constants.EXCLUDE 列表 资料来源：bandit/cli/main.py:148-156。CLI 会同时合并命令行提供的 excluded_paths 与 INI 中的 excluded_paths,最终交给 BanditManager.discover_files() 统一处理 资料来源：bandit/core/manager.py。

社区曾报告在 1.6.0 之后 -x 参数不再生效(issue #488,25 条评论),以及 1.6.3 中 .bandit 文件里的 exclude: 键未被尊重(issue #657,16 条评论)。这反映出路径排除在版本演进中曾出现回归,使用时建议通过 -v/--verbose 验证被排除的文件是否如预期,并优先在命令行显式传 -x 而非依赖 INI 间接配置。

插件排除

CLI 提供 -t/--tests 与 -s/--skips 配合 INI 中的 tests / skips 键,用于按检查器 ID(如 B101、B406)启用或停用特定插件 资料来源：bandit/cli/main.py:210-225。在配置生成器中,二者会同时序列化为 YAML 模板的 tests 与 skips 列表 资料来源：bandit/cli/config_generator.py:55-70。

插件机制

扩展加载器

bandit.core.extension_loader 通过 MANAGER 单例对外暴露已注册的检查器与黑名单。CLI 启动时调用 _init_extensions() 构建扩展管理器,随后通过 extension_mgr.plugins_by_id 与 extension_mgr.blacklist 收集插件信息并打印到 --help 输出中 资料来源：bandit/cli/main.py:127-140。

插件通过两个特殊属性声明其能力:

资料来源：bandit/cli/config_generator.py:108-130 与 bandit/cli/main.py:88-95。

配置生成器

bandit_conf_generator 工具(bandit/cli/config_generator.py)通过 --show-defaults 打印所有可配置插件的默认参数,或通过 -o/--out 写出完整 YAML 模板 资料来源：bandit/cli/config_generator.py:90-145。生成器会调用每个插件模块的 gen_config(function._takes_config) 函数,后者必须返回与 _takes_config 字段同构的字典 资料来源：bandit/cli/config_generator.py:108-130。

Baseline 工具与格式化器

bandit-baseline 子命令(由 bandit/cli/baseline.py 实现)在调用前会过滤 extension_mgr.formatters,仅保留带有 _accepts_baseline 标记的格式化器 资料来源：bandit/cli/main.py:88-95。Baseline 通过 git 检出父提交、运行 Bandit 写入临时 JSON(_bandit_baseline_run.json_),再在当前提交上以 -b bandit_tmpfile 比对差异 资料来源：bandit/cli/baseline.py:75-130。

常见问题与最佳实践

1. 路径排除失效:遇到类似 issue #488/#657 的场景时,使用 bandit -r . -x ./tests/ -v 显式验证排除集合。
2. per-file 检查器跳过:issue #346 提议在配置中按文件名模式跳过 B101 等检查器,当前代码未提供开箱即用支持,可通过在文件内添加 # nosec 注释(除非使用 --ignore-nosec)或维护多份 INI 文件间接实现。
3. 配置文件格式:若项目已统一使用 setup.cfg 或 pyproject.toml,需自行预处理或关注 issue #212/#550 的进展。
4. 插件参数调整:修改 bandit.yaml 后可用 bandit-config-generator --show-defaults 校验默认值,避免误改导致误报。

参见

• Bandit 官方文档:配置
• PEP 518 – pyproject.toml 规范

Bandit 项目在仓库根目录下通过三个独立的 CLI 入口协作完成扫描任务：主扫描器 bandit、变更对比工具 bandit-baseline，以及配置生成器 bandit-config-generator。三者均以 stevedore 插件管理器作为能力注册点，统一面向 extension_mgr 中的 formatter、check 与 blacklist 插件。本页聚焦其参数解析、配置加载顺序、Baseline 工作流与可插拔输出格式。

一、主命令行工具（bandit）

主入口在 bandit/cli/main.py 中，由 main() 函数负责参数解析、配置装载和调用 BanditManager。

参数分组与默认值

解析器使用 argparse.MutuallyExclusiveGroup 把日志控制拆分为 (-v|--verbose) 与 (-q|--quiet|--silent)，严重度与置信度同样以互斥组承载：-l/-ll/-lll 表示 LOW/MEDIUM/HIGH 严重度计数，-i/-ii/-iii 表示置信度计数；并提供语义化的 --confidence-level {all,low,medium,high} 备选。资料来源：main.py:235-258

输出格式 -f/--format 的默认值并非静态值：main() 在解析前会根据 sys.stdout.isatty()、os.getenv("NO_COLOR") 与 os.getenv("TERM") 动态选择 screen 或 txt。资料来源：main.py:260-275 这与社区对“颜色/无 TTY 环境”兼容性的关切直接相关。

`.bandit` 配置文件与选项优先级

_get_options_from_ini() 在未显式传入 --ini 时，会通过 os.walk + fnmatch.filter(filenames, ".bandit") 扫描 target 目录以发现项目级 .bandit 文件。每个 INI 选项随后经 _log_option_source() 与命令行解析结果比较，并以 cli value、ini value、default value 的顺序决定最终生效值。资料来源：main.py:90-180

这一行为是社区长期关注的痛点。Issue #488（25 条评论）报告 Bandit 1.6.0 不再尊重 -x 排除的目录；Issue #657（16 条评论）则进一步指出 .bandit 中的 exclude 在 1.6.3 中被命令行默认值覆盖——这两类问题都源于 _log_option_source() 链路上命令行/INI/默认值之间的合并顺序。社区在 Issue #212 与 #550 中也分别请求 setup.cfg 与 pyproject.toml 支持，目前主流仍为 .bandit + bandit.yaml（见 BASE_CONFIG = "bandit.yaml"）。

扫描与结果输出

main() 在装载配置后调用 b_mgr.discover_files(targets, recursive, excluded_paths)、b_mgr.run_tests() 与 b_mgr.output_results(...)。退出码规则为：若 b_mgr.results_count(sev_filter, conf_filter) > 0 且未传 --exit-zero，则 sys.exit(1)，否则 sys.exit(0)。资料来源：main.py:320-345

二、Baseline 工具（bandit-baseline）

入口在 bandit/cli/baseline.py，定位是“对比当前提交与父提交的安全发现增量”。运行时使用 GitPython 库，因此必须以 [baseline] extras 安装才能执行；否则 initialize() 会输出 Git not available, reinstall with baseline extra 并以退出码 2 失败。资料来源：baseline.py:80-95

校验前置条件

initialize() 中执行的硬性校验包括：仓库必须存在且 repo.is_dirty() 为 False；输出文件名 bandit_baseline_result.{fmt} 不得已存在；临时文件 _bandit_baseline_run.json_ 必须先清理；禁止传入 -o（会与 baseline 自身的输出逻辑冲突）。资料来源：baseline.py:95-130 任何一条校验失败都会让 main() 立即 sys.exit(2)。

两步扫描工作流

main() 在确定 current_commit 与 parent_commit 后，进入如下两步流程并最终使用 baseline_setup() 上下文清理临时目录与重置 HEAD：

flowchart TD
    A[reset HEAD -> parent_commit] --> B[bandit -f json -o bandit_tmpfile]
    B --> C[reset HEAD -> current_commit]
    C --> D[bandit -b bandit_tmpfile -f/-o]
    D --> E{exit_code ∈ {0,1}?}
    E -- 否 --> F[LOG.error 并退出]
    E -- 是 --> G[打印/写出报告]

资料来源：baseline.py:140-200 valid_baseline_formats = ["txt", "html", "json"] 决定可选输出格式；终端输出模式会直接把对比结果打印到 stdout，否则写入 bandit_baseline_result.<fmt>。

三、配置生成器（bandit-config-generator）

入口在 bandit/cli/config_generator.py。get_config_settings() 遍历 extension_loader.MANAGER.plugins，对所有带有 _takes_config 属性的插件 importlib.import_module() 其模块并调用 gen_config()，最终通过 yaml.safe_dump(config, default_flow_style=False) 写出 YAML。资料来源：config_generator.py:55-72

main() 支持 --show-defaults（打印默认 YAML 而不写文件）、-o/--out（写文件）、-t/--tests、-s/--skip。所有 -t/-s 中的 ID 都会经 MANAGER.check_id() 校验，避免把未注册的测试写到配置中。资料来源：config_generator.py:105-135

四、输出格式与报告流程

main.py 在收集 formatter 时使用 extension_mgr.formatter_names 动态生成 -f 的 choices；同时通过 hasattr(x.plugin, "_accepts_baseline") 过滤出兼容 baseline 的 formatter 子集。资料来源：main.py:60-72, main.py:215-235

最终由 BanditManager.output_results() 配合 --msg-template（仅在 format=custom 时合法）渲染。--msg-template 支持的标签包括 {abspath},{relpath},{line},{col},{test_id},{severity},{msg},{confidence},{range}，并兼容 Python str.format 的字段宽度语法。资料来源：main.py:155-200

资料来源：main.py:215-235, baseline.py:30-50, config_generator.py:1-40

See Also

• Bandit 主扫描与插件系统
• Bandit 测试插件列表（B101–B614）
• PEP 518 兼容的配置方案讨论（Issue #550）

Pitfall Log / 踩坑日志

项目：PyCQA/bandit

摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：False negative: narrow argument-shape checks in B508/B509。

1. 安全/权限坑 · 来源证据：False negative: narrow argument-shape checks in B508/B509

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：False negative: narrow argument-shape checks in B508/B509
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/PyCQA/bandit/issues/1397 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/PyCQA/bandit | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/PyCQA/bandit | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/PyCQA/bandit | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/PyCQA/bandit | no_demo; severity=medium

6. 安全/权限坑 · 来源证据：Feature request: Adding Canary Credentials to detect supply chain compromise

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: Adding Canary Credentials to detect supply chain compromise
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/PyCQA/bandit/issues/1432 | 来源类型 github_issue 暴露的待验证使用条件。

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/PyCQA/bandit | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/PyCQA/bandit | release_recency=unknown