How to Catch Vulnerable Python Code Before It’s Committed With Bandit

By the time a pull request is open, a security bug in your code has already been committed, already sits in your git history, and is already visible to every branch that gets created from it. Code review can still catch it there, but review happens after the fact and depends on a human noticing a specific line among dozens of changes. This tutorial builds a check that runs earlier: a git pre-commit hook that reads your changed Python files the moment you type git commit, using a tool called Bandit to look for known-dangerous code patterns, and refuses to let the commit go through if it finds one.

Bandit is a static application security testing (SAST) tool for Python. It does not run your code. Instead, it parses your source into an abstract syntax tree and pattern-matches that tree against a library of known-risky constructs: hashing a password with a broken algorithm, building a shell command out of a string instead of a list, deserializing untrusted data with pickle, and dozens more. Every finding it produces links back to a specific CWE (Common Weakness Enumeration) entry describing the underlying class of bug.

This is a different job from a secret scanner. A tool like Gitleaks looks at the literal text of your files for things that look like a real credential (an AWS key, a Stripe token, high-entropy strings assigned to a variable named secret). Bandit does not care what your strings say; it cares what your code does. You genuinely want both checks in a real project, and they compose cleanly in the same pre-commit configuration, but they are separate tools solving separate problems. If leaked credentials are what you are trying to catch, sxz.io already has a dedicated, fully worked walkthrough: How to Catch Leaked Secrets Before They Hit GitHub With Gitleaks. This tutorial is the code half of that picture: catching vulnerable code patterns, not vulnerable strings.

By the end, you will have a real, working demo repository where committing code with a weak password hash or a shell-injectable subprocess call fails loudly and immediately, where you have fixed those issues the right way (not just silenced the warning), where you understand exactly which parts of your repository a hook does and does not see, and where the same check also runs in CI so a bypass on one machine cannot quietly become the final word.

Prerequisites

• Python 3.9 or newer with pip. Everything here was run and verified against Python 3.13.14.
• git installed and configured with a user name and email. These steps were verified against git 2.55.0, but any reasonably recent git works identically for this tutorial.
• Comfort with basic git commands (git init, git add, git commit) and basic Python.
• Everything in this tutorial is pure Python and runs identically on Windows, macOS, and Linux. Commands are shown as run on Windows; the only platform-specific detail called out below is which tar binary gets resolved on each OS.
• No third-party account or sign-up is required. Bandit and pre-commit both run entirely on your own machine.

Step 1: Create a Demo Project

Start with an empty repository and a minimal Python package so there is something for a hook to eventually scan:

# Context: an empty directory where you want the demo project to live.
# Purpose: initialize git and lay down a minimal Python package skeleton.
git init
git config user.email "[email protected]"
git config user.name "Your Name"
mkdir app
type nul > app\__init__.py   # macOS/Linux: touch app/__init__.py

Add a requirements.txt and a short README.md, then make an initial commit so you have a clean baseline before any hooks exist:

git add -A
git commit -m "Initial commit: empty project skeleton"

Expected output: a single commit with your skeleton files and no hook output at all, because you have not installed any hooks yet.

Step 2: Install pre-commit and Bandit

pre-commit is a framework for managing git hooks written in many different languages. You describe what you want to run in a YAML file, and pre-commit takes care of downloading each tool, building it an isolated environment, and invoking it correctly every time you commit. Install both pre-commit and Bandit from PyPI:

pip install pre-commit bandit
pre-commit --version
bandit --version

Expected output (versions will vary slightly, but both commands should print a version number, not an error):

pre-commit 4.6.2
bandit 1.9.4

Installing bandit directly via pip here is only so you can run it by hand while you are learning. Once the pre-commit hook is wired up in the next step, pre-commit manages its own separate copy of Bandit automatically, pinned to whatever version you specify in the config file.

Step 3: Configure Bandit as a Pre-Commit Hook

Create a file named .pre-commit-config.yaml at the root of your repository:

# Context: repository root, new file.
# Purpose: register Bandit as a pre-commit hook, pinned to a specific release.
repos:
  - repo: https://github.com/PyCQA/bandit
    rev: "1.9.4"
    hooks:
      - id: bandit

The rev field pins the exact tag of the PyCQA/bandit repository pre-commit will clone and use, which is how bandit’s own official .pre-commit-hooks.yaml file gets picked up. That file is what actually defines the bandit hook id, its default file-type filter (Python files only), and its entry point; you are not writing that wiring yourself, you are just pinning a version of it.

Now install the actual git hook that will invoke this configuration automatically:

pre-commit install

pre-commit installed at .git\hooks\pre-commit

What This Command Actually Does

Git itself has a built-in hook mechanism with no dependency on pre-commit at all. According to git’s own documentation, the pre-commit hook “is invoked by git-commit, and can be bypassed with the --no-verify option… Exiting with a non-zero status from this script causes the git commit command to abort before creating a commit.” All pre-commit install does is write a small shell script to .git/hooks/pre-commit that git will already run automatically; that script’s only job is to hand control to the pre-commit Python framework, which then reads your YAML file and runs whichever hooks apply. You can open the generated file yourself:

cat .git/hooks/pre-commit

#!/usr/bin/env bash
# File generated by pre-commit: https://pre-commit.com
# ID: 138fd403232d2ddd5efb44317e38bf03

# start templated
INSTALL_PYTHON='...\venv\Scripts\python.exe'
ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
# end templated

HERE="$(cd "$(dirname "$0")" && pwd)"
ARGS+=(--hook-dir "$HERE" -- "$@")

if [ -x "$INSTALL_PYTHON" ]; then
    exec "$INSTALL_PYTHON" -mpre_commit "${ARGS[@]}"
elif command -v pre-commit > /dev/null; then
    exec pre-commit "${ARGS[@]}"
else
    echo '`pre-commit` not found.  Did you forget to activate your virtualenv?' 1>&2
    exit 1
fi

This matters because .git/hooks/ is never committed to your repository (it lives outside version control, per-clone). A teammate who clones your repository gets your .pre-commit-config.yaml automatically, but they still have to run pre-commit install themselves once before the hook is active on their machine. Step 9 covers how to make sure the check runs even when that step gets skipped.

Step 4: Watch Bandit Block a Real Vulnerability

Create app/auth.py with two genuinely bad patterns: a password hash built on MD5, and a subprocess call built from a formatted shell string.

import hashlib
import subprocess


def hash_password(password: str) -> str:
    return hashlib.md5(password.encode()).hexdigest()


def run_backup(filename: str) -> None:
    subprocess.run(f"tar -czf backup.tar.gz {filename}", shell=True)

Stage it and try to commit:

git add .pre-commit-config.yaml app/auth.py
git commit -m "Add auth helpers"

Real captured output (trimmed to the three findings; the first run also downloads and builds Bandit’s isolated environment, which takes a little longer than subsequent runs):

bandit...................................................................Failed
- hook id: bandit
- exit code: 1

>> Issue: [B404:blacklist] Consider possible security implications associated with the subprocess module.
   Severity: Low   Confidence: High
   CWE: CWE-78 (https://cwe.mitre.org/data/definitions/78.html)
   Location: .\app/auth.py:2:0

>> Issue: [B324:hashlib] Use of weak MD5 hash for security. Consider usedforsecurity=False
   Severity: High   Confidence: High
   CWE: CWE-327 (https://cwe.mitre.org/data/definitions/327.html)
   Location: .\app/auth.py:6:11

>> Issue: [B602:subprocess_popen_with_shell_equals_true] subprocess call with shell=True identified, security issue.
   Severity: High   Confidence: High
   CWE: CWE-78 (https://cwe.mitre.org/data/definitions/78.html)
   Location: .\app/auth.py:10:4

Run metrics:
	Total issues (by severity):
		Low: 1
		High: 2

The commit did not happen. Git aborted it because the hook exited non-zero, exactly as the githooks documentation describes. Three distinct findings, each worth understanding on its own:

• B404 just means “this file imports subprocess at all.” It is Low severity and purely informational; importing the module is not itself a bug, it is a heads-up to look closely at how it gets used.
• B324 flags MD5 for a security purpose. MD5 is fast (attackers can try billions of guesses per second against it) and has known collision weaknesses; a password hash needs to be deliberately slow and salted.
• B602 is the serious one. subprocess.run(f"...{filename}", shell=True) hands a string straight to a shell. If filename ever contains something like report.txt; rm -rf /, the shell will happily run that as a second command. This is the same root cause (CWE-78, OS command injection) as B404’s blacklist note, which is why they share a CWE.

Step 5: Fix It Properly, Not Just to Silence the Warning

Replace the hash with PBKDF2 (a purpose-built, deliberately slow password-hashing construction), and replace the shell string with a list of arguments and shell=False:

import hashlib
import subprocess

_PBKDF2_ITERATIONS = 600_000


def hash_password(password: str, salt: bytes) -> str:
    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, _PBKDF2_ITERATIONS)
    return digest.hex()


def run_backup(filename: str) -> None:
    subprocess.run(["tar", "-czf", "backup.tar.gz", filename], shell=False)

Argon2id is OWASP’s first choice for password hashing today, with PBKDF2 positioned as the option for when FIPS-140 compliance is required. For that specific case, OWASP’s own cheat sheet currently calls for “PBKDF2 with a work factor of 600,000 or more” using HMAC-SHA-256, which is the figure used above. Commit again:

git add app/auth.py
git commit -m "Fix weak hash and shell injection"

Real captured output: it fails again, but with two different findings than before:

>> Issue: [B607:start_process_with_partial_path] Starting a process with a partial executable path
   Severity: Low   Confidence: High
   Location: .\app/auth.py:13:4

>> Issue: [B603:subprocess_without_shell_equals_true] subprocess call - check for execution of untrusted input.
   Severity: Low   Confidence: High
   Location: .\app/auth.py:13:4

This is the part most write-ups skip: switching away from shell=True did not make the subprocess call disappear from Bandit’s radar, it surfaced two more specific, lower-severity concerns that were always there underneath the injection risk. B607 is complaining that "tar" is a bare name, not a full path, so the operating system has to search PATH to resolve it, which means whatever program happens to be named tar first on that particular machine’s PATH is what actually runs. B603 is a blanket reminder that this subprocess call still accepts a caller-supplied argument (filename) with no validation, regardless of shell=False.

Fix B607 for real, by resolving a concrete path with shutil.which, and address B603 by actually validating the input, then document why the residual risk is accepted with an inline # nosec comment:

import hashlib
import shutil
import subprocess

_PBKDF2_ITERATIONS = 600_000
_TAR_PATH = shutil.which("tar") or "tar"


def hash_password(password: str, salt: bytes) -> str:
    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, _PBKDF2_ITERATIONS)
    return digest.hex()


def run_backup(filename: str) -> None:
    if "/" in filename or "\\" in filename or ".." in filename:
        raise ValueError(f"invalid filename: {filename!r}")
    # filename is validated above and shell=False avoids shell injection
    subprocess.run([_TAR_PATH, "-czf", "backup.tar.gz", filename], shell=False)  # nosec B603

A # nosec B603 comment on the offending line tells Bandit “a human looked at this specific finding and accepted it,” and Bandit will report it separately as skipped rather than silently. This is meaningfully different from just deleting the code that triggered the warning: the justification comment stays in the codebase for the next person to read, and the suppression is scoped to exactly one rule on exactly one line, not the whole file. Treat nosec as something you write only after you have actually reasoned through the residual risk, the same way you would leave a comment explaining any other non-obvious safety decision.

On this Windows machine, shutil.which("tar") resolved to Git for Windows’ bundled tar.exe; on Linux it typically resolves to GNU tar, and on macOS to the BSD tar that ships with the OS. All three accept the same -czf flags used here. Running run_backup("README.md") for real against this exact code produced a genuine 216-byte backup.tar.gz, confirming the fix did not just silence Bandit, it still does its job.

Step 6: Point Bandit at a Config File (and a Gotcha Around It)

B404 (the plain “you imported subprocess” note) is still outstanding, and for this project you have decided that using subprocess deliberately, with validated input and no shell, is fine, so the blanket import warning is just noise. Bandit reads project-wide settings from a [tool.bandit] table in pyproject.toml:

[tool.bandit]
skips = ["B404"]

Commit with just that file added, and B404 is still there:

>> Issue: [B404:blacklist] Consider possible security implications associated with the subprocess module.
   Location: .\app/auth.py:3:0

This is a genuinely easy trap. Many Python tools (pytest among them, as you will see in the next step) automatically discover and read a project’s pyproject.toml just by finding it in a parent directory. Bandit does not. Its own --configfile flag documentation is explicit that a config file is "optional" and has to be pointed to directly; nothing about pyproject.toml gives it special auto-discovered status. Confirm this yourself:

bandit app/auth.py            # ignores pyproject.toml entirely, B404 still fires
bandit -c pyproject.toml app/auth.py   # reads it, B404 is now skipped

Update the hook definition to pass that flag every time it runs:

repos:
  - repo: https://github.com/PyCQA/bandit
    rev: "1.9.4"
    hooks:
      - id: bandit
        args: ["-c", "pyproject.toml"]

Commit once more, and this time it passes cleanly:

git add .pre-commit-config.yaml pyproject.toml
git commit -m "Point bandit at pyproject.toml via -c"

bandit...................................................................Passed

Step 7: Handle a Legitimate False Positive: assert in Tests

Add a small pytest suite covering the functions above:

import pytest
from app.auth import hash_password, run_backup


def test_hash_password_is_deterministic_for_same_salt():
    salt = b"fixed-salt-for-test"
    assert hash_password("correct horse", salt) == hash_password("correct horse", salt)


def test_run_backup_rejects_path_traversal():
    with pytest.raises(ValueError):
        run_backup("../../etc/passwd")

Commit it, and Bandit fails again, this time on the tests themselves:

>> Issue: [B101:assert_used] Use of assert detected. The enclosed code will be removed when compiling to optimised byte code.
   Severity: Low   Confidence: High
   CWE: CWE-703 (https://cwe.mitre.org/data/definitions/703.html)
   Location: .\tests/test_auth.py:18:4

Bandit’s reasoning is sound in general: Python strips every assert statement out of your bytecode when it runs under the -O optimization flag, so an assert guarding something security-relevant in application code can silently vanish in production. But pytest’s entire design is built around plain assert statements (it rewrites them internally to produce readable failure messages), and nobody runs a test suite with -O. This finding is a textbook false positive for exactly one directory in the project: tests/.

The fix is a second Bandit-specific config option, exclude_dirs:

[tool.bandit]
skips = ["B404"]
exclude_dirs = ["tests"]

One detail worth confirming rather than assuming: exclude_dirs works even when a file inside that directory is passed to Bandit by its exact path, which is what pre-commit does (it hands bandit the list of staged filenames, it does not run a recursive -r scan). Verify it directly:

bandit -c pyproject.toml tests/test_auth.py

Total lines of code: 0
Total issues (by severity):
	Undefined: 0
	Low: 0

Zero lines scanned confirms the whole file was excluded, not just the specific assert lines. Commit the updated config and the test files pass cleanly.

Step 8: Catch a Second Bug and Understand What Hooks Actually See

Create two more files. app/health.py is fine on its own:

def ping() -> str:
    return "ok"

app/legacy.py has a real problem: it deserializes a file with pickle, which can execute arbitrary code if the file’s contents are ever attacker-controlled.

import pickle


def load_cached_result(path: str):
    with open(path, "rb") as f:
        return pickle.load(f)

Now stage only health.py, leaving legacy.py sitting in your working directory, completely untracked:

git add app/health.py
git commit -m "Add health check endpoint"

bandit...................................................................Passed

The commit succeeds cleanly, with a real, unfixed pickle vulnerability sitting right there on disk. This is not a bug in the setup, it is exactly how it is supposed to work: a pre-commit hook only inspects what you are about to commit, not your whole working tree. Running pre-commit run --all-files at this point produces the same clean pass, because --all-files means “every file git already tracks,” which it determines with git ls-files, and a fully untracked file is invisible to that command too until you git add it.

Stage legacy.py and both checks find it immediately:

git add app/legacy.py
pre-commit run --all-files

>> Issue: [B403:blacklist] Consider possible security implications associated with pickle module.
>> Issue: [B301:blacklist] Pickle and modules that wrap it can be unsafe when used to deserialize untrusted data, possible security issue.

Bypassing Hooks (and Why You Shouldn’t Make It a Habit)

Every git hook, including this one, can be skipped outright:

git commit --no-verify -m "Add legacy cache loader (bypassing hooks)"

This genuinely works: the commit with the unfixed pickle vulnerability goes through, exactly as git’s own documentation promises (--no-verify is listed as the explicit bypass for this hook type). Nothing about pre-commit changes that; it is git’s mechanism, not pre-commit’s. That is precisely why Step 9 adds the same check in CI: a flag any contributor can type on their own machine is not something you can rely on as your only line of defense. If you want the more surgical SKIP=<hook-id> alternative, which disables one named hook instead of every hook at once, the Gitleaks tutorial linked earlier in this post walks through it directly.

Undo the bypass and fix the real problem instead, by switching from pickle to json:

import json


def load_cached_result(path: str):
    with open(path, "r", encoding="utf-8") as f:
        return json.load(f)

git add app/legacy.py
git commit -m "Add legacy cache loader using json instead of pickle"

bandit...................................................................Passed

Step 9: Enforce the Same Check in CI

A local hook only protects commits made on a machine where pre-commit install has actually been run. Someone can clone the repository fresh and never run it, or reach for --no-verify exactly as demonstrated above. Add a GitHub Actions workflow that runs the identical .pre-commit-config.yaml on every push and pull request, using the official pre-commit/action:

# Context: repository root, new file at .github/workflows/pre-commit.yml
# Purpose: run every hook in .pre-commit-config.yaml on GitHub's servers.
name: pre-commit

on:
  pull_request:
  push:
    branches: [main]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - uses: pre-commit/[email protected]

By default this action runs pre-commit run --all-files, which the pre-commit documentation itself specifically recommends for CI use, since a fresh checkout has nothing “staged” to compare against. Whatever hooks live in your config file at the time all run here, unchanged; if you later add Gitleaks or another hook to the same file, this workflow picks it up automatically with no edits.

One thing worth knowing before you commit to this approach: the README for pre-commit/action currently states plainly that “this action is in maintenance-only mode and will not be accepting new features,” and that its maintainers now generally recommend pre-commit.ci, a hosted service that runs the same config without you needing to write or maintain this workflow file at all. The action shown above still works and is a fine way to see the mechanism directly, but for a real project it is worth deciding up front which of the two you actually want.

Step 10: Verify Everything End to End

Confirm the whole thing holds together from a clean state. First, the application logic itself, independent of any hook:

pytest tests/ -v

tests/test_auth.py::test_hash_password_is_deterministic_for_same_salt PASSED
tests/test_auth.py::test_hash_password_differs_for_different_passwords PASSED
tests/test_auth.py::test_hash_password_returns_64_char_hex_digest PASSED
tests/test_auth.py::test_run_backup_rejects_path_traversal PASSED
tests/test_auth.py::test_run_backup_rejects_embedded_separators PASSED
tests/test_legacy.py::test_load_cached_result_round_trips_json PASSED

============================== 6 passed in 0.68s ==============================

Then the security check itself, against every file in the repository at once:

pre-commit run --all-files

bandit...................................................................Passed

real	0m0.7s

Under a second for the whole repository once Bandit’s isolated environment is already built. That speed matters: a hook that takes ten seconds on every commit is a hook people start reaching for --no-verify to skip. Keeping the file-type filter narrow (Bandit’s default hook only ever looks at .py files) and letting pre-commit cache each tool’s environment after the first run are both what keeps this fast enough to run without thinking about it.

Common Mistakes and Gotchas

• Writing .pre-commit-config.yaml but never running pre-commit install. The YAML file by itself does nothing; it is only consulted once the actual git hook script exists in .git/hooks/, and that script is what install creates.
• Assuming a config file is picked up automatically. As shown in Step 6, Bandit needs an explicit -c pyproject.toml in its hook args. Adding the file alone changes nothing.
• Using # nosec to make a warning disappear instead of to document a reviewed decision. A bare # nosec with no reasoning is a promise to your future self and teammates that you looked closely and decided the risk was acceptable; if that promise is not true, it is worse than the original warning, since now the finding is hidden too.
• Forgetting that exclude_dirs is bandit-specific config, not a pre-commit concept. Pre-commit has its own, separate exclude pattern you can set per-hook in the YAML file; the one used in Step 7 is Bandit’s own setting, read from pyproject.toml, and only takes effect because of the -c flag from Step 6.
• Treating a clean Bandit run as proof the code is secure. Bandit only recognizes patterns someone already wrote a rule for. It has no idea whether your authorization logic is correct or your business rules make sense; it is one layer, not a replacement for code review or testing.
• Skipping the CI layer. As Step 8 demonstrated directly, a local hook can be bypassed by anyone with the flag or the willingness to type it. If the check matters, it needs to run somewhere a contributor cannot opt out of.

Next Steps

From here, a few natural directions to keep going:

• Add a secret scanner alongside Bandit in the same .pre-commit-config.yaml using How to Catch Leaked Secrets Before They Hit GitHub With Gitleaks, so one commit gets checked for both vulnerable code and leaked credentials.
• Bandit will also flag classic SQL string-formatting patterns; if you want the deeper picture of why those are dangerous and how to fix them properly, see How to Prevent SQL Injection in Python With Parameterized Queries.
• If a secret or vulnerable pattern has already been committed and pushed before you had this hook in place, deleting it in a new commit is not enough, since it still exists in your git history. How to Remove a Leaked API Key From Git History With git filter-repo covers rewriting history to actually remove it.
• Bandit’s own plugin listing documents every rule it ships with; skimming it once is a fast way to learn what an entire class of Python security bugs looks like before you accidentally write one.