1. 项目概述：为什么我们需要Bandit？

在Python项目里，我们常常会听到“代码写完了，功能跑通了”，但很少有人会立刻追问一句：“你的代码安全吗？” 尤其是在团队协作、项目上线的关口，一个不起眼的eval()或者一个硬编码的密码，都可能成为安全漏洞的导火索。手动审查每一行代码？对于动辄上万行的项目来说，这无异于大海捞针，效率低下且容易遗漏。

这就是Bandit这类静态代码安全分析工具的价值所在。它不是一个复杂的、需要庞大知识库才能上手的重型武器，而更像一个经验丰富的“代码安检员”，能快速、自动化地扫描你的Python代码，识别出那些已知的、常见的安全隐患。我最初接触Bandit，是因为在一次内部代码审计中，它帮我揪出了一个因为图方便而直接拼接SQL语句的潜在注入风险，从那以后，它就成了我本地开发和CI/CD流水线里的一个固定环节。

“5分钟搞定”并非夸张。Bandit的核心设计理念就是轻量化和易用性。你不需要配置复杂的规则引擎，也不需要理解深奥的抽象语法树（AST）原理。对于大多数开发者而言，从安装到跑出第一份扫描报告，真的只需要喝杯咖啡的时间。它能帮你覆盖从基础语法误用到一些特定框架（如Django、Flask）的常见安全问题，是提升代码质量、培养安全开发意识的一个绝佳起点。

2. 核心需求与工具选型解析

2.1 我们到底在解决什么问题？

在引入任何工具之前，明确要解决的问题是关键。对于Python代码安全扫描，我们的核心需求可以归结为以下几点：

1. 自动化漏洞发现：替代人工肉眼审查，自动识别代码中潜在的安全缺陷，如命令注入、SQL注入、硬编码密钥、不安全的反序列化等。
2. 快速反馈：集成到开发流程中，在代码提交前或构建阶段快速给出结果，实现“左移”安全，避免问题流入生产环境。
3. 低学习成本：工具应该易于安装、配置和使用，不需要安全专家才能操作，普通开发人员能快速上手并理解报告内容。
4. 可定制化：能够根据项目实际情况，忽略某些误报（False Positive），或自定义需要重点关注的规则。
5. 良好的生态集成：能方便地与常用的开发工具（如VS Code、PyCharm）、版本控制系统（Git Hooks）和持续集成/持续部署（CI/CD）平台（如Jenkins, GitLab CI, GitHub Actions）集成。

2.2 为什么是Bandit？

市面上Python静态分析工具不少，比如Pylint（侧重代码风格和质量）、Flake8（风格和复杂度）、SonarQube（功能全面但较重）。Bandit的定位非常清晰：专攻安全。

• 精准的定位：Bandit只关心安全问题。它基于Python的AST进行解析，这意味着它能理解代码的结构，而不仅仅是文本模式匹配，因此检测更准确。
• 丰富的内置规则集：它预置了数十条安全检查规则（plugins），覆盖了OWASP Top 10等常见安全威胁。你可以通过bandit -l查看所有可用的测试项。
• 极简的使用方式：基本命令就是bandit -r .（扫描当前目录），报告格式清晰（文本、JSON、HTML等）。
• 高度的可配置性：通过.bandit配置文件或命令行参数，可以轻松地禁用特定规则、指定扫描文件、设置严重等级阈值等。
• 由OpenStack社区维护：背靠大厂和活跃社区，质量有保障，更新及时。

对于大多数Python项目，尤其是Web应用、API服务和数据处理脚本，Bandit提供了一个在效率、准确性和易用性之间取得很好平衡的解决方案。它不是银弹，无法发现所有逻辑漏洞，但对于消除“低级错误”类安全风险，它绝对是性价比最高的选择之一。

3. 5分钟极速上手：安装与基础扫描

我们现在就来实践一下，如何在5分钟内完成从零开始到获得第一份安全扫描报告。

3.1 环境准备与安装

Bandit需要Python环境。假设你已经有了Python（3.6+）和pip。

安装Bandit：打开你的终端（命令行），执行以下命令。建议使用虚拟环境，但为了演示快速，我们直接全局安装。

pip install bandit

注意：在生产或团队环境中，强烈建议将bandit写入项目的requirements-dev.txt或pyproject.toml的dev-dependencies中，以便统一环境。

安装完成后，验证一下：

bandit --version

如果输出版本号（如bandit 1.7.5），说明安装成功。

3.2 编写一个“问题”示例代码

为了看到Bandit的效果，我们创建一个有安全问题的Python脚本。在你喜欢的位置新建一个文件，命名为demo_scan.py，内容如下：

#!/usr/bin/env python3 """ 这是一个包含多种常见安全问题的示例脚本，用于Bandit演示。 """ import os import pickle import subprocess import sqlite3 # 问题1: 命令注入风险 (B602) def run_command(user_input): # 危险：直接拼接用户输入到系统命令中 os.system(f"echo {user_input}") # 问题2: SQL注入风险 (B608) def query_user(db_path, user_id): conn = sqlite3.connect(db_path) cursor = conn.cursor() # 危险：直接拼接用户输入到SQL语句中 query = f"SELECT * FROM users WHERE id = {user_id}" cursor.execute(query) # Bandit会在这里告警 return cursor.fetchall() # 问题3: 硬编码密码/密钥 (B105) SECRET_KEY = "my_super_secret_key_12345" # 这不应该出现在代码里！ # 问题4: 使用pickle反序列化不受信数据 (B301) def load_data(file_path): with open(file_path, 'rb') as f: data = pickle.load(f) # 危险：可能执行任意代码 return data # 问题5: 使用assert语句用于业务逻辑 (B101) def validate_positive(number): assert number > 0, "Number must be positive" # Assert可能在生产环境被禁用 return number * 2 if __name__ == "__main__": print("演示脚本已加载。") # 调用有问题的函数（实际不会执行，仅用于静态分析） # run_command("hello; rm -rf /") # query_user("test.db", "1 OR 1=1")

这个脚本集中展示了Bandit能发现的几类典型问题。

3.3 执行你的第一次扫描

在终端中，切换到存放demo_scan.py的目录，执行：

bandit demo_scan.py

几秒钟后，你会在终端看到一份详细的扫描报告。报告会列出每个问题的位置（文件名和行号）、问题类型（ID和标题）、严重程度（HIGH， MEDIUM， LOW）以及置信度（HIGH， MEDIUM， LOW）。

报告解读示例：你会看到类似这样的输出：

>> Issue: [B602:subprocess_popen_with_shell_equals_true] subprocess call with shell=True identified, security issue. Severity: High Confidence: High Location: demo_scan.py:10 More Info: https://bandit.readthedocs.io/en/latest/plugins/b602_subprocess_popen_with_shell_equals_true.html 9 def run_command(user_input): 10 os.system(f"echo {user_input}") # 这行被标记 11

报告清晰地告诉我们，第10行使用了os.system且拼接了用户输入user_input，这是一个高严重性、高置信度的命令注入风险（B602）。它还提供了一个链接，可以查看该规则的详细说明和修复建议。

扫描整个项目目录：如果你想扫描整个项目，使用-r参数：

bandit -r .

这将会递归扫描当前目录下所有的.py文件。

4. 核心功能详解与高级配置

掌握了基础扫描，我们来看看如何让Bandit更贴合你的项目需求。

4.1 理解扫描报告与问题等级

Bandit的输出信息非常结构化：

• Issue ID (如 B602)：唯一标识符，对应特定的安全检查规则。
• Severity (严重程度)：
  • HIGH: 高风险漏洞，通常可导致远程代码执行、严重信息泄露等（如命令注入、反序列化）。
  • MEDIUM: 中等风险，可能被利用但条件更苛刻（如某些路径遍历）。
  • LOW: 低风险或代码质量问题（如使用assert、md5等）。
• Confidence (置信度)：工具认为这个问题是真实漏洞的把握程度。高置信度意味着误报可能性低。
• Location (位置)：精确到文件和行号，方便定位。
• More Info (更多信息)：链接到官方文档，里面有详细的解释、示例和修复方案。

在初次扫描一个大型项目时，你可能会被大量的LOW级别告警淹没（比如很多B101assert语句）。这时，你需要根据项目情况决定处理策略。

4.2 使用配置文件进行精细控制

在项目根目录创建一个名为.bandit（或bandit.yaml）的配置文件，可以让你免去每次输入长串命令行参数的麻烦。

一个典型的.bandit配置文件示例：

# .bandit exclude_dirs: - ./tests # 排除测试目录，测试代码可能包含用于测试的“不安全”代码 - ./venv # 排除虚拟环境目录 - ./.git # 排除版本控制目录 skips: # 全局跳过的检查ID - B101 # 跳过所有assert语句检查（如果项目决定在生产环境使用assert） - B311 # 跳过`random`模块的检查（如果确认使用场景安全） tests: # 也可以选择只运行特定的检查 # - B102 # 例如，只检查exec相关 # 目标文件或目录 targets: - ./src - ./app # 输出格式和文件 output_format: json output_file: bandit_report.json # 设置严重程度阈值，只报告高于此级别的问题 severity_threshold: MEDIUM # 只显示MEDIUM和HIGH级别的问题 confidence_threshold: MEDIUM # 只显示置信度为MEDIUM和HIGH的问题

使用配置文件后，扫描命令简化为：

bandit -c .bandit

4.3 多种输出格式与集成

Bandit支持多种报告格式，便于集成到不同工作流。

• 文本格式（默认）：适合在终端快速查看。

  bandit -r . -f txt -o bandit_results.txt

• JSON格式：非常适合被其他程序（如CI/CD脚本）解析和处理。

  bandit -r . -f json -o bandit_results.json

• HTML格式：生成可视化的网页报告，更易于阅读和分享。

  bandit -r . -f html -o bandit_report.html

• 自定义格式：可以通过插件支持其他格式（如CSV， XML）。

集成到CI/CD：在GitLab CI的.gitlab-ci.yml中，可以添加这样一个阶段：

bandit-scan: stage: test image: python:3.9-slim script: - pip install bandit - bandit -r ./src -f json -o bandit-report.json || true # 即使发现漏洞，也继续执行以生成报告 artifacts: when: always paths: - bandit-report.json reports: sast: bandit-report.json # 将报告标记为SAST（静态应用安全测试）结果，在GitLab界面有专门展示

在GitHub Actions中，也有类似的配置方式，或者直接使用社区维护的Action，如reviewdog/action-bandit。

4.4 针对特定行或文件的忽略

有时，某个告警在特定上下文中是误报，或者是一个已知但暂时无法修复的问题。Bandit提供了几种忽略方式：

1. 行内注释忽略（推荐用于精确忽略）： 在代码行上方添加# nosec注释，Bandit会跳过该行的检查。

   import subprocess # 我们知道这里的命令是固定的，没有注入风险 result = subprocess.run(['ls', '-la'], capture_output=True) # nosec B603, B607

   你可以在# nosec后面指定具体的测试ID（如B603），也可以不指定，表示忽略该行所有检查。

2. 在配置文件中使用skips：如上节所示，用于全局跳过某一类检查。

3. 使用基线文件（Baseline）：如果你在已有项目中首次引入Bandit，可能会发现大量历史遗留问题。你可以先生成一份报告作为“基线”，然后让Bandit只报告相对于基线的新问题。这在对存量项目进行安全改进时非常有用。

   # 首次扫描，生成基线文件 bandit -r . -f json -o bandit_baseline.json # 后续扫描，对比基线 bandit -r . --baseline bandit_baseline.json

5. 常见安全问题模式与Bandit解决方案实录

Bandit发现的多数问题都有固定的模式。了解这些模式，不仅能帮你快速修复，更能从编码习惯上避免它们。

5.1 注入类问题（B60X系列）

这是最高危的问题类型。

• 命令注入 (B602, B603, B607)：

  • 问题代码：使用os.system(),subprocess.call(shell=True),subprocess.Popen(shell=True)并拼接用户输入。
  • Bandit告警：[B602:subprocess_popen_with_shell_equals_true]
  • 修复方案：
    1. 避免使用shell：使用subprocess.run()并传递参数列表。
    2. 严格过滤输入：如果必须用shell，使用shlex.quote()对用户输入进行转义。

    # 错误示例 user_input = input("Enter filename: ") os.system(f"cat {user_input}") # 危险！用户输入`/etc/passwd; rm -rf /`就完了 # 正确示例 import subprocess user_input = input("Enter filename: ") # 方案1：使用参数列表，避免shell try: subprocess.run(['cat', user_input], check=True, capture_output=True) except FileNotFoundError: print("File not found.") # 方案2：如果必须用shell（极不推荐），进行转义 # import shlex # safe_input = shlex.quote(user_input) # os.system(f"cat {safe_input}")

• SQL注入 (B608)：

  • 问题代码：使用字符串拼接或格式化来构建SQL语句。
  • Bandit告警：[B608:hardcoded_sql_expressions]（对简单拼接）或检查到execute()方法使用字符串参数。
  • 修复方案：永远使用参数化查询。

    # 错误示例 cursor.execute(f"SELECT * FROM users WHERE name = '{username}'") # 正确示例（使用sqlite3，其他库如psycopg2、PyMySQL同理） cursor.execute("SELECT * FROM users WHERE name = ?", (username,)) # 或者使用命名参数 cursor.execute("SELECT * FROM users WHERE name = :name", {'name': username})

5.2 敏感信息硬编码（B105, B106）

• 问题：将API密钥、数据库密码、加密密钥等直接写在源代码中。
• Bandit告警：[B105:hardcoded_password_string]，它会匹配常见的密码模式。
• 修复方案：
  1. 使用环境变量：这是最通用和推荐的做法。

     import os SECRET_KEY = os.environ.get('MYAPP_SECRET_KEY') if not SECRET_KEY: raise ValueError("MYAPP_SECRET_KEY environment variable not set")

  2. 使用配置文件：将配置信息放在单独的配置文件（如.env,config.yaml,config.json）中，并确保该文件被添加到.gitignore中，不提交到版本库。
  3. 使用密钥管理服务：在生产环境中，考虑使用Vault、AWS Secrets Manager、Azure Key Vault等专业服务。

5.3 不安全的反序列化（B301, B403）

• 问题：使用pickle、marshal或yaml.load()（没有指定Loader）来加载不受信任的数据源。
• Bandit告警：[B301:pickle],[B403:blacklist]
• 风险：攻击者可以构造恶意数据，在反序列化时执行任意代码。
• 修复方案：
  • 避免使用pickle处理不受信数据。如果需要在不同Python进程间传输数据，考虑使用json。
  • 如果必须使用pickle，确保数据来源绝对可信（例如，来自同一受控系统的序列化数据）。
  • 对于YAML，使用安全的加载器：yaml.safe_load()。

  # 错误示例 import pickle data = pickle.loads(request.data) # 来自网络请求的数据绝对不可信！ # 正确示例（使用JSON） import json data = json.loads(request.data)

5.4 其他常见告警与处理

• B101: assert语句：assert在Python中使用-O（优化）选项运行时会被全局禁用。如果用于数据验证，验证失败时程序会静默继续，导致未定义行为。

  • 修复：用明确的if判断和抛出合适的异常（如ValueError,AssertionError）替代。

  # 错误示例 def process_value(x): assert x > 0, "x must be positive" return x * 2 # 正确示例 def process_value(x): if x <= 0: raise ValueError("x must be positive") return x * 2

• B104: 绑定到所有接口：在开发Web服务时，使用app.run(host='0.0.0.0')。这在生产环境可能是必要的，但在开发中可能无意中向局域网暴露了调试服务。

  • 处理：Bandit会标记此为LOW风险。确保你理解这样做的含义。开发时可以使用host='127.0.0.1'。

6. 实战集成与进阶技巧

6.1 集成到开发工作流（Pre-commit Hook）

让安全扫描在代码提交前自动进行，是防止“坏代码”入库的有效手段。我们可以使用pre-commit框架。

1. 安装pre-commit:

   pip install pre-commit

2. 在项目根目录创建.pre-commit-config.yaml文件：

   repos: - repo: https://github.com/PyCQA/bandit rev: '1.7.5' # 使用固定的Bandit版本 hooks: - id: bandit # 可以在这里添加Bandit的参数 args: ['-c', '.bandit', '-f', 'txt'] # 可以指定扫描的文件类型 files: \.py$

3. 安装git钩子：

   pre-commit install

   现在，每次执行git commit时，pre-commit会自动运行Bandit扫描你暂存区（staged）的.py文件。如果发现中高风险问题，提交会被阻止。

6.2 在VS Code中实时扫描

对于开发者而言，能在编码时实时看到潜在问题，体验更佳。

1. 在VS Code中安装官方扩展Bandit。
2. 安装后，打开一个Python文件，Bandit会自动在后台扫描。
3. 发现问题时，它会在“问题”（Problems）面板列出，并在代码编辑器中用波浪线标出。
4. 你可以配置扩展的设置（Ctrl+,搜索bandit），例如指定参数文件、排除路径等。

这个扩展将Bandit从“事后检查”工具变成了“实时助手”，能极大地提升开发过程中的安全意识。

6.3 处理误报与调整规则

没有工具是完美的，Bandit也会有误报。关键在于如何高效管理。

• 识别误报：仔细阅读Bandit报告中的“More Info”链接，理解规则检测的逻辑。判断在你的上下文中，这个检测是否合理。例如，一个固定的、非用户输入的字符串用于系统命令，可能被误报为命令注入。
• 使用# nosec注释：如上所述，这是最精确的忽略方式。务必在注释中写明忽略的理由，方便日后自己和他人审查。

  # 这是一个内部工具，执行的命令是固定的，无用户输入。忽略命令注入检查。 subprocess.run(['/usr/bin/internal_tool', '--mode', 'safe'], check=True) # nosec B603 B607

• 调整配置文件：如果某个规则在整个项目中都不适用（例如，项目大量使用assert进行契约式设计，且确保不会用-O运行），可以在.bandit配置文件的skips中全局跳过。
• 自定义插件（高级）：如果Bandit的内置规则无法满足你的特定需求（例如，检查是否使用了公司内部禁用的某个库），你可以编写自己的Bandit插件。这需要一定的Python AST知识，官方文档提供了详细指南。

6.4 性能考量与扫描优化

对于大型项目，扫描所有文件可能需要一些时间。以下是一些优化建议：

1. 排除无关目录：在.bandit配置文件中，用exclude_dirs排除venv,.git,__pycache__,build,dist,tests（如果测试代码不需要安全扫描）等目录。
2. 设置严重性阈值：在CI/CD流水线中，可以设置severity_threshold: HIGH，只阻断高严重性问题，让中低级别问题在报告里呈现，但不阻塞流程。在本地深度扫描时，再使用更低的阈值。
3. 增量扫描：与pre-commit结合，只扫描即将提交的变更文件，速度最快。
4. 并行扫描：Bandit本身不支持并行，但对于大型项目，你可以手动将代码库分成多个部分，用脚本并行运行多个Bandit实例，最后合并报告（需处理重复文件）。

7. 常见问题与排查技巧实录

在实际使用Bandit的过程中，你可能会遇到一些典型问题。这里记录了我踩过的一些坑和解决方法。

7.1 问题：扫描速度慢，特别是大型项目

• 排查：使用bandit -r . -v（verbose模式）运行，观察它正在解析哪些文件。很可能是在扫描虚拟环境、构建产物或文档目录。
• 解决：
  1. 严格配置exclude_dirs：确保排除了所有非源码目录。一个高效的.bandit配置是提速的关键。
  2. 使用.bandit文件指定targets：只扫描你的源码目录，如./src，而不是整个项目根目录。
  3. 考虑升级Bandit：新版本通常有性能优化。

7.2 问题：报告中有大量我不关心的“低风险”告警（如B101, B413）

• 现象：报告被刷屏，真正的高风险问题被淹没。
• 解决：
  1. 首次扫描建立基线：使用--baseline生成一份包含所有历史问题的报告。后续扫描使用--baseline参数，Bandit就只报告新引入的问题。这是处理存量代码库的最佳实践。
  2. 提高报告阈值：在命令行或配置中设置-l（低）、-ll（中）、-lll（高）来过滤置信度，或直接设置severity_threshold: MEDIUM。
  3. 针对性跳过：在.bandit的skips列表中添加那些对你项目来说是“噪音”的检查ID。

7.3 问题：Bandit没有报告我已知的安全问题

• 排查：
  1. 检查规则是否启用：运行bandit -l，确认对应的插件（Test ID）是否存在且为[Enabled]状态。
  2. 检查代码语法：Bandit基于AST工作，如果代码存在语法错误，它可能无法正确解析该文件，从而跳过扫描。确保你的代码能通过Python解释器。
  3. 检查文件是否被排除：确认你的文件不在exclude_dirs或.banditignore（如果使用）列表中。
  4. 问题是否太复杂：Bandit主要检测模式化、已知的漏洞。对于复杂的业务逻辑漏洞、权限控制问题等，它无能为力。这时需要依赖代码审查、动态测试（DAST）和人工审计。

7.4 问题：在CI/CD中，Bandit发现了问题，但构建未失败

• 现象：流水线日志显示有HIGH级别问题，但作业状态仍是“成功”。
• 原因：Bandit默认以退出码0（成功）结束，无论是否发现问题。只有发生内部错误（如文件无法读取）时，退出码才为非零。
• 解决：在CI脚本中，需要根据Bandit的输出内容来判断是否失败。通常有两种方式：
  1. 使用-f txt并解析输出：检查输出中是否包含HIGH等关键词。但更推荐方式2。
  2. 使用-f json并配合脚本：解析JSON报告，检查metrics中的SEVERITY.HIGH等计数是否大于0。或者，直接使用Bandit的--exit-zero参数的反向逻辑（但Bandit没有直接的--non-zero-on-find参数）。 一个简单的Shell脚本示例：

  #!/bin/bash bandit -r . -f json -o bandit-report.json # 使用jq解析JSON，检查是否有HIGH级别问题 if jq '.metrics | ."SEVERITY.HIGH" > 0' bandit-report.json; then echo "发现高危安全问题，构建失败！" exit 1 fi

  你需要先在CI环境中安装jq工具。

7.5 问题：# nosec注释不生效

• 排查：
  1. 注释位置：# nosec必须放在要忽略的代码行之前或同一行末尾。放在行后可能不生效。
  2. 作用域：# nosec只忽略它所在的那一行代码。如果想忽略一个代码块，需要在每一行都添加（或使用配置全局跳过）。
  3. 特定ID：如果你写了# nosec B101，但该行触发的是B102，则B102不会被忽略。使用# nosec（不指定ID）来忽略该行所有检查。
  4. Bandit版本：确保你使用的Bandit版本支持nosec特性。

7.6 一个实用的排查清单

当你遇到Bandit相关问题时，可以按以下顺序排查：

我个人最深刻的体会是，Bandit这类工具的价值，一半在于它找出的问题，另一半在于它促使团队形成的“安全编码”肌肉记忆。刚开始集成时，可能会因为各种误报和“历史债务”而感到烦躁。但坚持把它作为开发流程的必过环节，几个月后，你会发现团队成员在写subprocess或拼接SQL时会自然而然地停顿一下，思考是否有更安全的写法。这种潜移默化的改变，才是将安全真正“左移”并内化的关键。最后一个小技巧：可以把Bandit的HTML报告定期（比如每周）生成并归档，作为项目安全状态的一个可视化历史记录，在复盘或审计时非常有用。