[Advanced]: Add Bandit security scanning (CI + pre-commit hook)

[exploreriii]

🧠 Advanced Contributors — Prerequisites & Expectations

🐞 Problem Description

We can benefit from python-specific security checks at the pre-commit level and in workflows, that supplement the codacy/existing bandit checks in .codacy.yml.

Read about bandit https://bandit.readthedocs.io/en/1.9.4/start.html

Introduce Python security linting using Bandit in both CI (GitHub Actions) and as a local pre-commit hook. This ensures early detection of insecure patterns during development and consistent enforcement in pull requests.

We would like to:

• Provide fast feedback locally via pre-commit
• Enforce checks centrally via CI, present results in a thoughtful way
• Align with existing security tooling (e.g. CodeQL, dependency scanning)
• Be achieved in a maintainable way that can scale if we add more hooks or change workflows
• Test to see if it keeps good developer experience, what happens if there are existing issues. Do we need documentation? What kind of issues could this cause?

Double check how much codacy already is checking, and double check the above is reasonable. Research is important as the plan is not fully defined.

Caution

This advanced issue requires extensive independent research and testing.

🏁 Concrete Prerequisites

• Proven History: Successfully merged ≥ 5 non-trivial intermediate issues in this repo, including at least 2 relating to github actions.
• Expertise: Deep architectural understanding of creating high-quality, well tested workflows

⚠️ AI Usage Policy

Using AI to generate code for Advanced issues is strictly discouraged. AI may be used only to help explain file relationships. We require this workflow to work and follow best principles.

⏱️ Timeline & Workflow

• Typical time: ~2 weeks / ~20 hours.
• 🔴 Completing an advanced issue in 1–3 days is a red flag and will likely be rejected.
• Advised: Post your proposed architectural approach as a comment and wait for feedback before writing any code.

🛠️ Implementation Notes

Technical domains involved in this issue:

• CI/CD Integration
  GitHub Actions workflow setup, triggers (push, pull_request), permissions (security-events: write), and job configuration.
• Static Application Security Testing (SAST)
  Use of Bandit for Python AST-based security analysis, rule coverage, and handling false positives.
• Dependency & Tooling Management
  Installing and versioning Bandit in CI and pre-commit environments.
• Developer Experience (DX) / Pre-commit Hooks
  Local enforcement via pre-commit, ensuring fast feedback loops and consistent developer setup.
• Configuration & Noise Reduction
  Optional Bandit configuration (bandit.yaml), excluding directories (e.g. tests/), and tuning rules to reduce false positives.
• Security Workflow Integration
  Ensuring Bandit complements existing tools (e.g. CodeQL, dependency scanning) without redundant coverage.

🛡️ Quality & Review Standards

The bar for advanced PRs is "safe, maintainable, architecturally sound, and production-ready."

• CI Reliability. Workflow must run consistently on appropriate trigger
• Proper lowest permissions set to limited scope files
• Bandit findings are meaningful and appropriate
• Suitably complements existing tools (e.g. CodeQL)
• Workflow file is simple, readable, and minimal. Uses stable, well-supported GitHub Actions with hashes.
• Pre-commit hook is appropriate with minimal friction

Notably: Developer architects the solution of how to best apply bandit to the repo

✅ PR Quality Checklist

Before opening your PR, the contributor must confirm:

• I understand the system-wide impact of these changes on affected modules and performance.
• The system design fits with current architectural approaches.
• I have tested my changes extensively against both local and network environments.
• Every line of code is personally understood and explainable and tested

📚 Resources & Support

Sample from github:
https://github.com/actions/starter-workflows/blob/main/code-scanning/bandit.yml

Project References:

• SDK Project Structure
• Transaction Lifecycle
• Hedera Protobufs (v0.72.0-rc.2)

🆘 Stuck?

• Office Hours (Wednesdays, 2pm UTC)
• Discord #hiero-python-sdk

[github-actions]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Centralize Bandit configuration in pyproject.toml alongside existing linting tools, with carefully chosen rule suppressions based on identified false-positive patterns in the codebase
• Add the official PyCQA Bandit pre-commit hook for fast local feedback during development
• Create a new GitHub Actions workflow that outputs SARIF and uploads to GitHub Code Scanning, following all existing workflow patterns (harden-runner, SHA-pinned actions, minimal permissions)
• Complement rather than replace existing Codacy Bandit checks, providing native GitHub Security integration

Design Choices

Design Choice 1: Where should Bandit configuration be stored?

Options Considered:

1. pyproject.toml under [tool.bandit] — single source of truth, aligns with existing Ruff/mypy config placement
2. Separate bandit.yaml file — dedicated security config file, more visible
3. Command-line arguments only — no config file, harder to maintain consistency

Chosen Option: 1

Rationale: pyproject.toml provides consistency with existing tooling patterns and is natively supported by Bandit with the bandit[toml] extra.

Design Choice 2: How should the new workflow relate to existing Codacy Bandit checks?

Options Considered:

1. Remove Codacy Bandit, use only GitHub workflow — single source of security scanning
2. Keep both as complementary tools — Codacy for their dashboard/metrics, GitHub for native Code Scanning integration

Chosen Option: 2

Rationale: Keep both. The GitHub workflow adds native Code Scanning integration (results appear in GitHub Security tab, PR annotations), while Codacy may serve other team workflows. The configurations should be aligned to avoid discrepancies.

Design Choice 3: Which directories should be scanned?

Options Considered:

1. Scan everything including tests — comprehensive but extremely noisy (B101 on every pytest assert)
2. Scan src/ only — production code only
3. Scan src/ and tck/, exclude tests/ and examples/ — mirrors Codacy exclusions, covers all non-test code

Chosen Option: 3

Rationale: Aligns with Codacy's existing exclusions, covers production SDK code and the TCK server (which handles network requests), and avoids massive B101 noise from test assertions.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Bandit Configuration and Pre-commit Integration

Establish the Bandit configuration foundation and enable local developer feedback via pre-commit hook. This phase creates a single source of truth for Bandit settings that both the pre-commit hook and CI workflow will reference.

Task 1: Configure Bandit Settings in pyproject.toml

Define Bandit scan targets, exclusions, and rule suppressions based on the false-positive patterns identified in the codebase.

• Add [tool.bandit] section to pyproject.toml specifying targets (src/hiero_sdk_python, tck/) and excluded paths (tests/, examples/)
• Configure skipped rules: B101 (assert_used, aligns with Codacy), B311 (random for non-crypto jitter in timestamp.py), B501 (ssl cert verification in node.py uses hash pinning), B106 (password=None is not a hardcoded secret), B110 (try/except/pass for format probing)
• Set appropriate severity and confidence thresholds to reduce noise while catching meaningful issues
• Document the rationale for each suppression as inline comments

Task 2: Add Bandit Pre-commit Hook

Integrate the official PyCQA Bandit hook into the existing pre-commit configuration for local enforcement.

• Add the official PyCQA/bandit repository to .pre-commit-config.yaml with a SHA-pinned version
• Configure the hook to use pyproject.toml as the config source via args (-c pyproject.toml)
• Add additional_dependencies: ["bandit[toml]"] to enable pyproject.toml parsing
• Position the hook logically alongside existing security hooks (after Gitleaks)

🤖 Prompt for AI agents

This phase establishes Bandit's configuration foundation and wires it into the
local pre-commit workflow. The goal is to create a single source of truth for
Bandit settings in `pyproject.toml` and expose it to developers via a pre-commit
hook.

**Task 1: Add `[tool.bandit]` section to `pyproject.toml`**
- Set scan targets to `src/hiero_sdk_python` and `tck/`
- Exclude `tests/` and `examples/` from scanning
- Skip the following rules, each with an inline comment documenting the
rationale:
  - B101 — assert_used (aligns with Codacy suppression)
  - B311 — random used for non-crypto jitter in `timestamp.py`
  - B501 — SSL cert verification in `node.py` uses hash pinning
  - B106 — `password=None` is not a hardcoded secret
  - B110 — try/except/pass used for format probing
- Set severity and confidence thresholds appropriate to reduce noise while
catching meaningful issues

**Task 2: Update `.pre-commit-config.yaml`**
- Add a new entry for the official `PyCQA/bandit` pre-commit repository using a
SHA-pinned version
- Set hook args to include `-c pyproject.toml` so it reads configuration from
the centralized file
- Add `additional_dependencies: ["bandit[toml]"]` to support TOML config parsing
- Place the new hook after the existing Gitleaks entry to group security-related
hooks together

Phase 2: GitHub Actions CI Integration

Create a workflow that runs Bandit on every push and pull request, uploads results to GitHub Code Scanning via SARIF, and follows all existing repository workflow patterns.

Task 1: Create Bandit Security Scanning Workflow

Implement a new GitHub Actions workflow that enforces Bandit checks in CI with SARIF output for GitHub Code Scanning integration.

• Create new workflow file in .github/workflows/ (e.g., pr-check-bandit.yml) following existing naming conventions
• Configure triggers for push (main branch) and pull_request events, plus workflow_dispatch for manual runs
• Add step-security/harden-runner as the first step with egress-policy: audit (existing pattern)
• Set up Python environment and install Bandit with TOML support
• Run Bandit with --format sarif --output bandit-results.sarif using the pyproject.toml configuration
• Use github/codeql-action/upload-sarif (SHA-pinned) to upload results to GitHub Code Scanning
• Set workflow permissions to contents: read and security-events: write (minimum required for SARIF upload)
• Ensure all third-party actions are SHA-pinned per repository conventions

Task 2: Validate Workflow Integration and Developer Experience

Ensure the implementation works correctly and provides good developer experience without breaking existing workflows.

• Verify the workflow runs successfully on both push and pull_request triggers
• Confirm SARIF results appear correctly in the GitHub Security tab and as PR annotations
• Test that pre-commit hook runs correctly locally and catches the same issues as CI
• Validate that existing Codacy checks continue to function without conflict
• Ensure no existing passing builds are broken by the new checks (suppressions are correctly applied)

🤖 Prompt for AI agents

This phase creates the GitHub Actions workflow file that runs Bandit in CI,
outputs SARIF, and uploads results to GitHub Code Scanning. The workflow must
strictly follow the repository's existing conventions.

**Task 1: Create `.github/workflows/pr-check-bandit.yml`**
- Follow the existing naming convention for workflow files in the repository
- Configure the following triggers:
  - `push` targeting the main branch
  - `pull_request`
  - `workflow_dispatch` for manual runs
- Set minimum required permissions:
  - `contents: read`
  - `security-events: write`
- Steps to include (in order):
1. `step-security/harden-runner` as the first step with `egress-policy: audit` —
SHA-pinned, matching the existing pattern
  2. Checkout the repository
  3. Set up Python environment
  4. Install Bandit with TOML support (`bandit[toml]`)
5. Run Bandit using the `pyproject.toml` configuration, outputting results in
SARIF format: `--format sarif --output bandit-results.sarif`
6. Upload SARIF results using `github/codeql-action/upload-sarif` (SHA-pinned)
to integrate with GitHub Code Scanning
- All third-party actions must be SHA-pinned per repository conventions

**Task 2: Validate integration (no code changes — verification steps)**
- Confirm the workflow triggers correctly on push and pull_request events
- Confirm SARIF results surface in the GitHub Security tab and appear as PR
annotations
- Confirm the pre-commit hook and CI produce consistent results
- Confirm existing Codacy Bandit checks are unaffected
- Confirm no previously passing builds are broken (all suppressions correctly
applied)

Research

This is a Python SDK repository with source code in src/hiero_sdk_python/, tests in tests/, a Test Compatibility Kit server in tck/, and example scripts in examples/. The project already has Bandit configured via Codacy (.codacy.yml) which excludes tests/** and suppresses B101. All GitHub Actions workflows follow consistent patterns: SHA-pinned actions, step-security/harden-runner with audit mode, and minimal permissions. Pre-commit hooks are configured in .pre-commit-config.yaml (currently includes Gitleaks, Pylint, and whitespace fixers). Development tooling configuration is centralized in pyproject.toml (Ruff, mypy).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase establishes Bandit's configuration foundation and wires it into the
local pre-commit workflow. The goal is to create a single source of truth for
Bandit settings in `pyproject.toml` and expose it to developers via a pre-commit
hook.

**Task 1: Add `[tool.bandit]` section to `pyproject.toml`**
- Set scan targets to `src/hiero_sdk_python` and `tck/`
- Exclude `tests/` and `examples/` from scanning
- Skip the following rules, each with an inline comment documenting the
rationale:
  - B101 — assert_used (aligns with Codacy suppression)
  - B311 — random used for non-crypto jitter in `timestamp.py`
  - B501 — SSL cert verification in `node.py` uses hash pinning
  - B106 — `password=None` is not a hardcoded secret
  - B110 — try/except/pass used for format probing
- Set severity and confidence thresholds appropriate to reduce noise while
catching meaningful issues

**Task 2: Update `.pre-commit-config.yaml`**
- Add a new entry for the official `PyCQA/bandit` pre-commit repository using a
SHA-pinned version
- Set hook args to include `-c pyproject.toml` so it reads configuration from
the centralized file
- Add `additional_dependencies: ["bandit[toml]"]` to support TOML config parsing
- Place the new hook after the existing Gitleaks entry to group security-related
hooks together
===============================================================================

Task: 2

This phase creates the GitHub Actions workflow file that runs Bandit in CI,
outputs SARIF, and uploads results to GitHub Code Scanning. The workflow must
strictly follow the repository's existing conventions.

**Task 1: Create `.github/workflows/pr-check-bandit.yml`**
- Follow the existing naming convention for workflow files in the repository
- Configure the following triggers:
  - `push` targeting the main branch
  - `pull_request`
  - `workflow_dispatch` for manual runs
- Set minimum required permissions:
  - `contents: read`
  - `security-events: write`
- Steps to include (in order):
1. `step-security/harden-runner` as the first step with `egress-policy: audit` —
SHA-pinned, matching the existing pattern
  2. Checkout the repository
  3. Set up Python environment
  4. Install Bandit with TOML support (`bandit[toml]`)
5. Run Bandit using the `pyproject.toml` configuration, outputting results in
SARIF format: `--format sarif --output bandit-results.sarif`
6. Upload SARIF results using `github/codeql-action/upload-sarif` (SHA-pinned)
to integrate with GitHub Code Scanning
- All third-party actions must be SHA-pinned per repository conventions

**Task 2: Validate integration (no code changes — verification steps)**
- Confirm the workflow triggers correctly on push and pull_request events
- Confirm SARIF results surface in the GitHub Security tab and appear as PR
annotations
- Confirm the pre-commit hook and CI produce consistent results
- Confirm existing Codacy Bandit checks are unaffected
- Confirm no previously passing builds are broken (all suppressions correctly
applied)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!