PyCQA / PyCQA/bandit

Documentation of configuration is confusing / misleading regarding `exclude` vs `exclude_dirs`

Open
#528 3 comments 12 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Python
Stars
8.3k
Forks
835
Avg merge
5d 3h
Merged PRs (30d)
1

Description

Reading the docs for the first time, I struggled to correctly formulate my desired .bandit.yaml.

The readme doc shows the use of exclude: /test , but the readthedocs site does not mention exclude or exclude_dirs.
I was writing a yaml doc with

exclude: ["/tests", "_build"]

and finding that files in my various _build/ directories (a project-specific packaging process) were still being scanned.

Essential

It should be obvious that I needed to write

exclude_dirs: ["/tests", "_build"]

based on the readme.

Ideal

I'd like to see:

  • the readme contains only a very simple example modern config file, i.e. yaml format
    (this is based on my understanding, after only a few minutes reading, that bandit is transitioning from "legacy" ini config to yaml?)
  • refers explicitly to the docs site for full config documentation
  • config documentation lists all available options and what they do
  • example usages for the most common options with explanations, noting particular nuances -- e.g. that exclude_dirs: ["foo"] will capture foo/, bar/foo/, etc.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the README configuration example and the ReadTheDocs configuration documentation. Compare their treatment of exclude and exclude_dirs, then document the available options, modern YAML usage, and common examples including nested directory matching; done means both sources clearly direct readers to complete, consistent configuration guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, yaml
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.