pycqa/bandit

1. Bandit is a Python security linter packaged as a library plus CLI. Its core runtime is the bandit package, and the primary execution path starts from bandit/__main__.py or bandit/cli/main.py when invoked as a command-line tool.

2. The main scan pipeline is: load configuration, discover test plugins, walk Python source files, build an AST, run security checks against AST nodes, collect issues, then format/report results. This is the central data flow that an architecture diagram should show.

3. bandit/core is the engine layer. It contains the AST traversal and orchestration pieces (manager, node_visitor, tester, context, issue, metrics, config, extension_loader). This layer owns file scanning, plugin invocation, issue aggregation, and run metadata.

4. The AST-based analysis boundary is important: Bandit reads Python source, parses it into AST, and evaluates nodes rather than executing code. meta_ast.py and node_visitor.py support this traversal, while context.py carries node-specific information into tests.

5. Security rules live mostly in bandit/plugins. These are the pluggable detectors for patterns like shell injection, SQL injection, hardcoded secrets, unsafe deserialization, insecure SSL/TLS, template/XSS issues, and unsafe model downloads. Each plugin is a focused rule module that emits findings when it matches an AST pattern.

6. bandit/blacklists provides a second rule mechanism for banned calls and imports. These are more table-driven checks, complementing the plugin system with explicit forbidden APIs and modules.

7. bandit/cli is the user-facing command layer. It handles argument parsing, baseline comparison, and config generation. The baseline feature is an architectural boundary for suppressing previously accepted findings so that only new issues are reported.

8. Reporting is separated into bandit/formatters. The same issue set can be rendered as screen text, plain text, JSON, YAML, CSV, XML, HTML, or SARIF. This formatter layer is the output boundary and is important for integrations with CI, code scanning tools, and human review.

9. The repository includes a large examples/ corpus and tests/ suite that validate detection behavior. The examples act as fixture-like inputs for many vulnerability patterns, while unit and functional tests cover CLI behavior, engine logic, and formatter output.

10. Packaging and distribution are handled through standard Python tooling: setup.py, setup.cfg, requirements.txt, and tox/pre-commit configs. The repo is released to PyPI and also built into a container image via GitHub Actions, which makes Bandit usable both as an installed CLI and as a Dockerized scanner.

11. Documentation is a first-class subsystem under doc/, built with Sphinx and published to Read the Docs. The docs mirror the internal architecture: configuration, blacklists, plugins, formatters, and CI/CD usage.

12. For an architecture diagram, the key boundaries are: source files in, AST analysis in the middle, plugins/blacklists as rule providers, formatter outputs on the other side, and CLI/config/baseline as orchestration around the engine. The external surfaces are Python source repositories, CI pipelines, PyPI, Read the Docs, and the published container image.