Document how to use Bandit

[bittner]

There are several issues open that suggest that it is unclear how Bandit is meant to be executed. In fact, there are no usage instructions at all in the Bandit docs.

Describe the solution you'd like

There should be simple, crisp, usage instructions in the Bandit docs, e.g.

Install Bandit:

pip install bandit

Run Bandit over your entire project:

bandit

(Obviously, the instructions above don't work for the current version 1.6.2.)

Apart from updating the docs, while this is likely the most important place to start, the problem domain may entail that the usage in general must be made simple:

• Sensible defaults should prevail
• Overriding defaults should be simple and intuitive
• Common patterns of use (aka "developer behavior") should be taken into account

Describe alternatives you've considered

Setting default options in tox.ini and/or .bandit, and wrap it with Tox. See #396 (comment).

Not nice, with limited success, and not universally usable for everyone.

Additional context

Bandit doesn't current traverse the entire project tree, and it doesn't ignore (common) hidden folders by default, e.g. .git, .tox. It also reports security issues in tests that make little sense to report (e.g. "Use of assert detected", "Possible hardcoded password", "Starting a process with a partial executable path", etc. – that's just the natural way you implement tests).

Codacy also uses Bandit and reports all issues related to test implementations. It's unclear how they use the tool, but it's likely a rather custom way.

Long story short: There are a lot of things unclear when it comes to using Bandit. A tool that is – I would guess – meant to be simple to use. Not to say, trying to get out of your way.

Possibly related issues

• Make 'target' arg optional and let it be defined in the ini file #274 (Make 'target' arg optional and let it be defined in the ini file)
• default config file name #318 (default config file)
• INI file format is not obviously documented anywhere #396 (INI file format is not obviously documented anywhere)
• Skip configuration for certain paths only #457 (Skip configuration for certain paths only)
• bandit -rf custom only shows up to 3 warnings #459 (bandit -rf custom only shows up to 3 warnings)
• Use current directory unless explicitly specified #467 (Use current directory unless explicitly specified)
• Bandit 1.6.0 no longer respects excluded directories #488 (Bandit 1.6.0 no longer respects excluded directories) -- still a bug in 1.6.2
• degraded performance in 1.6.0 release #490 (degraded performance in 1.6.0 release) -- likely related to Bandit 1.6.0 no longer respects excluded directories #488
• Exclude paths in config file ignored if passing specific files to Bandit CLI #499 (Exclude paths in config file ignored if passing specific files to Bandit CLI)
• Doc - Usage with Code Climate #519 (Doc - Usage with Code Climate) -- note the "minimal configuration" hint
• Documentation of configuration is confusing / misleading regarding exclude vs exclude_dirs #528 (Documentation of configuration is confusing / misleading regarding exclude vs exclude_dirs)
• cannot run bandit on codes in a folder using *.py #537 (cannot run bandit on codes in a folder using *.py)
• Ini file settings ignored #595 (Ini file settings ignored)

[diegovalenzuelaiturra]

Hi, I think this may be helpful here.

Here is my current approach to configure bandit to avoid raising B101 assert_used warnings on python tests.

• [optional] Use the Bandit Config Generator to generate an optional profile and save it to a YAML file

  bandit-config-generator --out bandit.yml

• Edit the profile configuration file

  • bandit.yml - based on the comment: Interpret wildcards in the file exclusion list #450 (comment)

    # https://github.com/PyCQA/bandit/pull/450#issuecomment-724777229
    assert_used:
        skips: ["*/test_*.py"]

  • .bandit config file example

    [bandit]
    # targets: comma separated list of target dirs/files to run bandit on
    # exclude: comma separated list of excluded paths
    # skips  : comma separated list of tests to skip
    # tests  : comma separated list of tests to run
    targets = .
    
    recursive = true

1. Run bandit

   # you may want to provide full paths instead
   bandit --configfile bandit.yml --ini .bandit

---

If you are using VSCode, you can include the following in your settings.json .

• It assumes your .bandit and bandit.yml configuration files are located on the workspace folder.
  • See https://code.visualstudio.com/docs/editor/variables-reference for other variable references you may find useful if you want to configure it to use configuration files that are located somewhere else.

// settings.json
{
    "python.linting.enabled": true,
    "python.linting.lintOnSave": true,
    "python.linting.banditEnabled": true,
    //  https://code.visualstudio.com/docs/editor/variables-reference
    "python.linting.banditArgs": [
        // "-ll",
        // "-ii",
        "--configfile=${workspaceFolder}/bandit.yml",
        "--ini=${workspaceFolder}/.bandit",
    ],
    "files.associations": {
        ".bandit": "ini",
    },
}