PythonBandit自定义插件开发指南

本文深入解析了Python安全扫描工具Bandit自定义插件开发的核心机制与实战陷阱：插件必须严格继承`TestContext`类（否则会被硬编码逻辑静默忽略），`run`方法需手动实现AST遍历并精准识别`ast.Call`节点（如检测`subprocess.Popen`带`shell=True`的危险调用），模块加载依赖正确Python路径和导入结构（`-x`指定的是模块路径而非文件路径），且每个`add_issue`调用必须显式传入字符串形式的`severity`和`confidence`（大小写敏感，不可设为类属性）。文中直击开发者常踩的“插件不触发”“无报告输出”“等级失效”等痛点，用可复现的错误现象与正确代码片段揭示Bandit底层设计逻辑，助你避开隐性坑、写出稳定可靠的自定义安全检查规则。

bandit 插件为什么必须继承 TestContext 类

因为 bandit 的扫描器在运行时只识别继承自 TestContext 的类作为合法插件入口，其他类名或函数定义会被直接忽略——哪怕路径正确、文件可导入。这不是配置问题，是硬编码的类型检查逻辑。

常见错误现象：bandit -r . -x my_plugin 完全没触发你的代码，bandit --list-plugins 里也看不到；但把类名改成 MyPlugin 并继承 TestContext 后立刻生效。

• 必须显式写 class MyCustomTest(bandit.TestContext):，不能只写 def run(...)
• 类名不需要匹配文件名，但必须唯一，否则后续插件会覆盖前一个
• 不继承 TestContext 的模块即使被 -x 指定，bandit 也会静默跳过

如何让 run 方法真正捕获到危险函数调用

bandit 不是靠字符串匹配，而是基于 AST 遍历。你写的 run 方法必须手动遍历节点，并对 ast.Call 做判断——它不会自动帮你“检测所有 eval 调用”。

使用场景：比如你想拦截所有带 subprocess.Popen 且含 shell=True 的调用。

• 必须在 run 中调用 self.visit(node)（通常放在 __init__ 或顶层逻辑里），否则 AST 遍历根本不会启动
• 重写 visit_Call 方法时，要检查 node.func 是否为 ast.Attribute 或 ast.Name，再逐层取属性名，不能只看 node.func.id
• 示例片段：

  if (isinstance(node.func, ast.Attribute) and
      isinstance(node.func.value, ast.Name) and
      node.func.value.id == 'subprocess' and
      node.func.attr == 'Popen'):

  然后继续检查 node.keywords 里有没有 shell=True

bandit.register 和插件路径加载的隐性规则

bandit 不支持任意路径导入插件。它只从 PYTHONPATH 或当前工作目录下的 bandit/plugins/ 子目录自动发现，或者靠 -x 显式指定模块路径（如 myproject.plugins.mytest），但该模块必须能被 Python 正常 import。

容易踩的坑：把插件文件放在 ./plugins/xxx.py，却没加 __init__.py，导致 import plugins.xxx 失败，bandit 报错 ImportError: No module named 'plugins'。

• -x 后跟的是 Python 模块路径，不是文件路径，例如 -x mypkg.bandit_plugins.unsafe_eval
• 模块中必须有且仅有一个继承 TestContext 的类，bandit 会自动实例化它
• 如果插件依赖其他本地模块，确保它们也在 PYTHONPATH 中，否则 run 方法里 import 会失败，但错误可能被吞掉，只表现为“无报告”

为什么 confidence 和 severity 设置不生效

这两个字段不是在类定义里设的，而是在每次调用 self.add_issue(...) 时传进去的。bandit 插件里没有全局配置项，每个 issue 必须单独声明等级。

性能影响：设成 HIGH 不会变慢，但设错会导致报告被过滤——比如 CI 脚本用了 --severity-level medium，而你只打了 LOW，那条 issue 就不会出现在输出里。

• 正确写法：self.add_issue(node, severity="HIGH", confidence="MEDIUM", text="unsafe shell=True")
• 值只能是字符串 "LOW"/"MEDIUM"/"HIGH"，大小写敏感，写成小写或数字会静默失败
• 别试图在类属性里写 severity = "HIGH"——bandit 完全不读这个

插件里 AST 节点的 parent 关系不可靠，node.parent 在 bandit 里默认为空；需要自己维护上下文栈，否则判断嵌套调用（比如 eval(compile(...))）很容易漏判。

今天关于《PythonBandit自定义插件开发指南》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！