bandit-python

Overview

Per bandit.readthedocs.io/en/latest/start.html:

Bandit is the Python-specific SAST originally from OpenStack Security. Each finding has two dimensions:

• Severity (LOW / MEDIUM / HIGH) - how dangerous if exploited
• Confidence (LOW / MEDIUM / HIGH) - how certain Bandit is the finding is real

The two-dimensional scoring lets you tune false-positive vs false-negative tradeoff per project.

When to use

• Repo has Python source (Bandit is Python-only).
• The team needs a focused Python SAST integrated with pre-commit
  • standard CI.
• Quick triage of low-effort security wins (hardcoded passwords, shell=True in subprocess, weak crypto).
• Pair with semgrep-rules (broader, cross-language) for layered coverage.

Step 1 - Install

Per bd-start:

pip install bandit[toml]

The [toml] extra enables pyproject.toml config support.

Step 2 - Basic recursive scan

Per bd-start:

bandit -r path/to/your/code

Common usage:

bandit -r .                              # current dir, recursive
bandit -r src/ tests/                    # multiple paths
bandit -r . -x tests,vendor              # exclude dirs
bandit -r . -ll                           # minimum LOW confidence + LOW severity

Step 3 - Severity + confidence filtering

Per bd-start verbatim CLI usage:

bandit examples/*.py -n 3 --severity-level=high

Combined two-dimensional filtering:

# Only HIGH severity findings with HIGH confidence
bandit -r . --severity-level=high --confidence-level=high

# All MEDIUM+ severity, any confidence
bandit -r . --severity-level=medium

The two flags compose; neither is a strict subset of the other.

Step 4 - pyproject.toml config

# pyproject.toml
[tool.bandit]
exclude_dirs = ["tests", "vendor", "build"]
skips = ["B101"]                       # skip "assert used" rule globally
tests = ["B201", "B301"]                # only run flask + pickle checks (whitelist mode)

[tool.bandit.assert_used]
skips = ["**/test_*.py", "**/*_test.py"]

tests = [...] activates whitelist mode (run ONLY listed checks); skips = [...] activates blacklist mode (run all checks except listed). They're mutually exclusive.

Step 5 - Rule ID catalog

Bandit rules are organized by category prefix:

Full catalog: bandit.readthedocs.io/en/latest/plugins/.

Step 6 - False-positive triage (MANDATORY)

Per the canonical Bandit workflow, three suppression layers:

Justification template (mandatory in code):

import subprocess
# nosec B602 - Reason: command is statically defined, no user input
# Reviewer: alice@example.com (2026-05-15)
# Expires: 2026-12-15
result = subprocess.run("ls -la /tmp", shell=True, check=True)

For rules that can never apply (e.g., B311 random is fine outside crypto contexts), prefer per-rule disable in pyproject.toml over per-line suppressions - fewer comments to maintain, easier to audit at the project level.

Cadence: every quarter, grep for # nosec patterns lacking # Reason: lines; flag for review.

Step 7 - Output formats

bandit -r . -f txt                      # default human-readable
bandit -r . -f json -o bandit.json      # JSON for sast-finding-triager
bandit -r . -f sarif -o bandit.sarif    # SARIF for GitHub Code Scanning
bandit -r . -f xml -o bandit.xml        # JUnit XML
bandit -r . -f html -o bandit.html      # standalone HTML report
bandit -r . -f csv -o bandit.csv        # CSV
bandit -r . -f screen                    # colorized terminal

Step 8 - Pre-commit integration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/PyCQA/bandit
    rev: 1.7.10
    hooks:
      - id: bandit
        args: ["--severity-level=medium", "--confidence-level=medium"]
        files: \.py$
        exclude: ^(tests/|venv/|.venv/)

Step 9 - CI integration

jobs:
  bandit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with: { python-version: '3.13' }
      - run: pip install bandit[toml]
      - run: bandit -r . -f sarif -o bandit.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: bandit.sarif }

For PR-blocking: pipe through --severity-level high to limit noise.

Anti-patterns

Limitations

• Python-only; for Go use gosec-go, for JS use Semgrep.
• Plugin-based detection misses some patterns that Semgrep custom rules can catch.
• No native cross-file taint analysis (use codeql-queries for that).
• Rule depth varies - well-maintained for OpenStack-era patterns; newer Python ecosystem (FastAPI, async patterns) coverage thinner.

References

• bd-start - install + basic scan reference
• bandit.readthedocs.io - full documentation
• bandit.readthedocs.io/en/latest/plugins/ - rule catalog
• github.com/PyCQA/bandit - repository
• semgrep-rules, sonarqube-rules, codeql-queries, gosec-go - sister scanners
• sast-finding-triager - unifier agent