|
| 1 | +# Bandit |
| 2 | + |
| 3 | +This README provides an introduction to using Bandit with the Hiero Python SDK. We use uv to manage the environment and Bandit to handle static security analysis and vulnerability scanning. |
| 4 | + |
| 5 | +## What Is Bandit? |
| 6 | + |
| 7 | +[Bandit](https://bandit.readthedocs.io/en/latest/) is a security-focused static analysis tool designed to find common security vulnerabilities and flaws in Python code. |
| 8 | + |
| 9 | +## 🎯 Why Use Bandit? |
| 10 | + |
| 11 | +**Vulnerability Detection:** Catches critical security flaws like hardcoded passwords, shell injections, weak cryptography, and unsafe serialization. |
| 12 | + |
| 13 | +**Fine-Grained Severity Rules:** Categorizes threats into Low, Medium, and High severities to establish structural pass/fail criteria. |
| 14 | + |
| 15 | + |
| 16 | +## ⚙️ Installation |
| 17 | + |
| 18 | +We use **uv** to manage the Hiero Python SDK environment. Bandit is included in the `lint` dependency group. |
| 19 | + |
| 20 | +### The Recommended Way (Using uv) |
| 21 | +The below command will simply pull down the latest dependencies and synchronize your local environment in one step: |
| 22 | +```bash |
| 23 | +uv sync |
| 24 | +``` |
| 25 | + |
| 26 | +### Alternative Installation Layouts |
| 27 | + |
| 28 | +If you need to install Bandit manually into an alternate isolated setup or are using a different environment manager, use the corresponding configuration below: |
| 29 | +```bash |
| 30 | +# Explicitly add to the development group via uv |
| 31 | +uv add --group lint bandit |
| 32 | + |
| 33 | +# Using classic pip inside an active virtualenv |
| 34 | +pip install bandit |
| 35 | + |
| 36 | +# Using Poetry |
| 37 | +poetry add --group lint bandit |
| 38 | + |
| 39 | +# Using Conda |
| 40 | +conda install -c conda-forge bandit |
| 41 | +``` |
| 42 | +> [!TIP] |
| 43 | +> Make sure `bandit` is available in the same virtual environment (`.venv`) you use to run the Hiero SDK. If using **uv**, simply running `uv sync` will set everything up for you automatically. |
| 44 | +
|
| 45 | +## ▶️ Usage |
| 46 | + |
| 47 | +### Manual Checking for vulnerabilities |
| 48 | + |
| 49 | +We run security checks against our package source paths and active development scripts. |
| 50 | + |
| 51 | +```bash |
| 52 | +# Check the entire source directory recursively |
| 53 | +uv run bandit -c bandit.yml -r src/ |
| 54 | + |
| 55 | +# Check multiple active development folders together |
| 56 | +uv run bandit -c bandit.yml -r src/ tck/ tests/ |
| 57 | + |
| 58 | +# Run with custom thresholds |
| 59 | +uv run bandit -c bandit.yml -l -r src/ |
| 60 | + |
| 61 | +# Run checks and generate a clean text log report file |
| 62 | +uv run bandit -c bandit.yml -r src/ --format txt --output bandit_report.txt |
| 63 | +``` |
| 64 | + |
| 65 | +### Run using Pre-Commit Hook |
| 66 | + |
| 67 | +If you want to run the Bandit using the `pre-commit` configuration, use: |
| 68 | + |
| 69 | +```bash |
| 70 | +uv run pre-commit run --all-files |
| 71 | +``` |
| 72 | + |
| 73 | +## 🛠️ Handling Security Issues |
| 74 | + |
| 75 | +### How Severity Levels Affect Commits |
| 76 | +Unlike code formatters, Bandit will never modify your code automatically. Security risks must be reviewed and patched manually based on their tier: |
| 77 | + |
| 78 | +- **Low Severity (Warnings):** Issues like public parameter keywords triggering hardcoded credential filters (`B106`) or standard pseudo-random generators (`B311`) or any other low severity issue will print out to your logging metrics for context but will not block your commit. |
| 79 | + |
| 80 | + An example of a passing run containing a low-severity warning: |
| 81 | + ``` |
| 82 | + Test results: |
| 83 | + No issues identified. |
| 84 | +
|
| 85 | + Code scanned: |
| 86 | + Total lines of code: 24726 |
| 87 | + Total lines skipped (#nosec): 0 |
| 88 | +
|
| 89 | + Run metrics: |
| 90 | + Total issues (by severity): |
| 91 | + Undefined: 0 |
| 92 | + Low: 1 |
| 93 | + Medium: 0 |
| 94 | + High: 0 |
| 95 | + ``` |
| 96 | + |
| 97 | +- **Medium & High Severity (Blockers):** High-risk flaws like deprecated cryptographic libraries (`B413`), exposed keys, or command injections throw a failure execution code and instantly halt your commit. |
| 98 | + |
| 99 | +### Inline Suppressions (`# nosec`) |
| 100 | + |
| 101 | +Sometimes an abstract pattern triggers a false positive that has been reviewed and verified as safe. You can silence individual lines using the inline `# nosec` statement followed by the specific issue ID. |
| 102 | + |
| 103 | +```python |
| 104 | +# Suppress alerts for executing a fixed, safe system command |
| 105 | +import subprocess |
| 106 | +subprocess.Popen(["/bin/ls", "-l"], shell=False) # nosec B602, B607 |
| 107 | + |
| 108 | +# Tell Bandit this specific assert statement is intentional and safe |
| 109 | +assert user_role == "admin" # nosec B101 |
| 110 | +``` |
| 111 | + |
| 112 | +### Targeted Rule Suppressions |
| 113 | +Instead of disabling a rule globally or littering your files with `# nosec` comments, you can use Bandit's plugin-specific configuration blocks to skip rules for matching file patterns. |
| 114 | + |
| 115 | +```yml |
| 116 | +# bandit.yml |
| 117 | + |
| 118 | +# Global directory exclusions |
| 119 | +exclude_dirs: ['.clusterfuzzlite/**'] |
| 120 | + |
| 121 | +# Targeted plugin rule overrides |
| 122 | +assert_used: |
| 123 | + skips: |
| 124 | + - '**/tests/**/*.py' |
| 125 | + |
| 126 | +exec_used: |
| 127 | + skips: |
| 128 | + - '**/tests/mocks/**/*.py' |
| 129 | +``` |
| 130 | +
|
| 131 | +**Global Suppressions:** If a specific rule is completely irrelevant to entire codebase, do not add `# nosec` everywhere. Instead, permanently drop it by adding the error code to the `skips` list inside `bandit.yml` file. |
| 132 | + |
| 133 | +```yml |
| 134 | +skips: ["B101", "B601", "B413"] |
| 135 | +``` |
| 136 | + |
| 137 | +## 📝 Example Output |
| 138 | + |
| 139 | +### When structural vulnerabilities are found: |
| 140 | + |
| 141 | +If Bandit discovers a violation that meets or exceeds your active severity threshold (Medium or High), it halts execution, rejects the commit, and provides a detailed breakdown including the issue ID, line numbers, and its Common Weakness Enumeration (CWE) classification: |
| 142 | + |
| 143 | +```text |
| 144 | +Run started: 2026-05-31 18:00:20.408359+00:00 |
| 145 | +
|
| 146 | +Test results: |
| 147 | +>> Issue: [B602:subprocess_popen_with_shell_equals_true] subprocess call with shell=True identified, possible injection. |
| 148 | + Severity: High Confidence: High |
| 149 | + CWE: CWE-78 (https://cwe.mitre.org/data/definitions/78.html) |
| 150 | + Location: src/example_module/utils.py:12:4 |
| 151 | +11 def execute_user_query(user_input): |
| 152 | +12 subprocess.Popen(user_input, shell=True) |
| 153 | +13 |
| 154 | +
|
| 155 | +-------------------------------------------------- |
| 156 | +Code scanned: |
| 157 | + Total lines of code: 23318 |
| 158 | +Run metrics: |
| 159 | + Total issues (by severity): Low: 3, Medium: 0, High: 1 |
| 160 | +``` |
| 161 | + |
| 162 | +### When security scans clear successfully: |
| 163 | + |
| 164 | +If project satisfies active gating baseline, it finishes with a clean summary report: |
| 165 | +```text |
| 166 | +bandit...................................................................Passed |
| 167 | +
|
| 168 | +Test results: |
| 169 | + No issues identified. |
| 170 | +
|
| 171 | +Code scanned: |
| 172 | + Total lines of code: 23318 |
| 173 | + Total lines skipped (#nosec): 2 |
| 174 | +
|
| 175 | +Run metrics: |
| 176 | + Total issues (by severity): |
| 177 | + Undefined: 0 |
| 178 | + Low: 0 |
| 179 | + Medium: 0 |
| 180 | + High: 0 |
| 181 | +``` |
| 182 | + |
| 183 | +Happy scanning! 🛡️ |
0 commit comments