Bandit Baseline Maintenance Guide

This document explains how to maintain the scripts/lint/bandit_baseline.json file.

Overview

The Bandit baseline is used to exempt known low-severity security findings so that they do not block PRs. This file follows the severity + confidence tiering policy:

Severity	Confidence	Handling
HIGH	HIGH/MEDIUM/LOW	Blocks the PR (cannot be exempted)
MEDIUM	Any	Warns but does not block
LOW	Any	Can be exempted into the baseline

Baseline File Structure

{
  "generated_at": "2026-07-19",
  "version": "1.0.0",
  "description": "Bandit baseline for known low-severity findings.",
  "findings": [
    {
      "test_id": "B101",
      "severity": "LOW",
      "confidence": "HIGH",
      "file": "tests/test_example.py",
      "line": 42,
      "reason": "assert usage in test file is expected",
      "approved_by": "security-team",
      "approved_at": "2026-07-19"
    }
  ]
}

Field Reference

Field	Required	Description
test_id	✅	Bandit test ID (e.g., B101)
severity	✅	Finding severity (only LOW can be exempted)
confidence	✅	Bandit confidence
file	✅	File path (relative to the repository root)
line	✅	Line number
reason	✅	Explanation of the exemption
approved_by	✅	Approver (security-team or admin)
approved_at	✅	Approval date

Process for Adding a New Baseline Finding

1. Evaluate the Finding

First confirm that the finding should not be fixed:

• Must be exempted: only LOW severity findings
• Must not be exempted: HIGH severity findings; the code must be fixed

2. Explain in the PR

In the PR that adds the baseline finding:

1. Explain why the finding can be exempted
2. Reference related issues (if any)
3. State whether a fix is planned

3. Obtain Approval

• The PR can be merged only after approval by the Security Team or an Admin
• The approver is recorded in the approved_by field

4. Update the Baseline File

# Manually add the finding to the baseline
# Or generate it with a script (to be implemented)

Review & Bypass

Quarterly review of baseline findings and emergency bypass via the skip-security-check PR label follow the shared exception lifecycle defined in API_EXCEPTIONS.md.

Common LOW Severity Findings

Test ID	Name	Common Scenario
B101	assert_used	assert statements in test files
B311	random_module	Randomness for non-cryptographic purposes

References

• Bandit documentation
• Bandit Test IDs
• Issue #1856 - CI quality gate improvements