From ebd168ae338295aaf3bb20585111120a3c115468 Mon Sep 17 00:00:00 2001 From: Peter Bittner Date: Thu, 11 Aug 2022 18:13:20 +0200 Subject: [PATCH] [docs] Mention `exclude_dirs` option available in TOML and YAML (#876) * [docs] Use code-blocks for syntax highighting, un-inline hyperlinks * [docs] Mention `exclude_dirs` option available in TOML and YAML Make configuration examples easier to understand and use Explain how to install TOML support As discovered in #488 and reported in #528. --- doc/source/config.rst | 133 +++++++++++++++++++++++++++++++----------- doc/source/start.rst | 86 +++++++++++++++++++-------- 2 files changed, 161 insertions(+), 58 deletions(-) diff --git a/doc/source/config.rst b/doc/source/config.rst index 24f1f0c40..96f5e975a 100644 --- a/doc/source/config.rst +++ b/doc/source/config.rst @@ -5,45 +5,85 @@ Configuration Bandit Settings --------------- -Projects may include an INI file named `.bandit` that specifies command line -arguments that should be supplied for that project. The currently supported -arguments are: - - - 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 +Projects may include an INI file named `.bandit`, which specifies +command line arguments that should be supplied for that project. +In addition or alternatively, you can use a YAML or TOML file, which +however needs to be explicitly specified using the `-c` option. +The currently supported arguments are: + +``targets`` + comma separated list of target dirs/files to run bandit on +``exclude`` + comma separated list of excluded paths -- *INI only* +``exclude_dirs`` + comma separated list of excluded paths (directories or files) -- *YAML and TOML only* +``skips`` + comma separated list of tests to skip +``tests`` + comma separated list of tests to run To use this, put an INI file named `.bandit` in your project's directory. Command line arguments must be in `[bandit]` section. For example: -:: +.. code-block:: ini + + # FILE: .bandit + [bandit] + exclude = tests,path/to/file + tests = B201,B301 + skips = B101,B601 + +Alternatively, put a YAML or TOML file anywhere, and use the `-c` option. +For example: + +.. code-block:: yaml + + # FILE: bandit.yaml + exclude_dirs: ['tests', 'path/to/file'] + tests: ['B201', 'B301'] + skips: ['B101', 'B601'] + +.. code-block:: toml + + # FILE: pyproject.toml + [tool.bandit] + exclude_dirs = ["tests", "path/to/file"] + tests = ["B201", "B301"] + skips = ["B101", "B601"] - [bandit] - exclude: /test +Then run bandit like this: -:: +.. code-block:: console - [bandit] - tests = B101,B102,B301 + bandit -c bandit.yaml -r . +.. code-block:: console + + bandit -c pyproject.toml -r . Note that Bandit will look for `.bandit` file only if it is invoked with `-r` option. If you do not use `-r` or the INI file's name is not `.bandit`, you can specify -the file's path explicitly with `--ini` option. +the file's path explicitly with `--ini` option, e.g. + +.. code-block:: console + + bandit --ini tox.ini Exclusions ---------- + In the event that a line of code triggers a Bandit issue, but that the line has been reviewed and the issue is a false positive or acceptable for some other reason, the line can be marked with a ``# nosec`` and any results associated with it will not be reported. For example, although this line may cause Bandit to report a potential -security issue, it will not be reported:: +security issue, it will not be reported: - self.process = subprocess.Popen('/bin/echo', shell=True) # nosec +.. code-block:: python + + self.process = subprocess.Popen('/bin/echo', shell=True) # nosec Because multiple issues can be reported for the same line, specific tests may be provided to suppress those reports. This will cause other issues not @@ -51,16 +91,20 @@ included to be reported. This can be useful in preventing situations where a nosec comment is used, but a separate vulnerability may be added to the line later causing the new vulnerability to be ignored. -For example, this will suppress the report of B602 and B607:: +For example, this will suppress the report of B602 and B607: + +.. code-block:: python - self.process = subprocess.Popen('/bin/ls *', shell=True) #nosec B602, B607 + self.process = subprocess.Popen('/bin/ls *', shell=True) # nosec B602, B607 Full test names rather than the test ID may also be used. For example, this will suppress the report of B101 and continue to report B506 -as an issue.:: +as an issue. + +.. code-block:: python - assert yaml.load("{}") == [] # nosec assert_used + assert yaml.load("{}") == [] # nosec assert_used ----------------- Scanning Behavior @@ -69,8 +113,8 @@ Scanning Behavior Bandit is designed to be configurable and cover a wide range of needs, it may be used as either a local developer utility or as part of a full CI/CD pipeline. To provide for these various usage scenarios bandit can be configured -via a `YAML `_ file. This file is completely optional and in -many cases not needed, it may be specified on the command line by using `-c`. +via a `YAML file`_. This file is completely optional and in many cases not +needed, it may be specified on the command line by using `-c`. A bandit configuration file may choose the specific test plugins to run and override the default configurations of those tests. An example config might @@ -80,6 +124,8 @@ look like the following: ### profile may optionally select or skip tests + exclude_dirs: ['tests', 'path/to/file'] + # (optional) list included tests here: tests: ['B201', 'B301'] @@ -98,19 +144,24 @@ look like the following: subprocess: [subprocess.Popen, subprocess.call, subprocess.check_call, subprocess.check_output] +Run with: + +.. code-block:: console + + bandit -c bandit.yaml -r . + If you require several sets of tests for specific tasks, then you should create several config files and pick from them using `-c`. If you only wish to control the specific tests that are to be run (and not their parameters) then using `-s` or `-t` on the command line may be more appropriate. -Also you can configure bandit via -`pyproject.toml `_ file. In this -case you would explicitly specify the path to configuration via `-c` too. -For example: +Also, you can configure bandit via a `pyproject.toml file`_. In this case you +would explicitly specify the path to configuration via `-c`, too. For example: -.. code-block:: TOML +.. code-block:: toml [tool.bandit] + exclude_dirs = ["tests", "path/to/file"] tests = ["B201", "B301"] skips = ["B101", "B601"] @@ -155,9 +206,18 @@ For example: "subprocess.check_output" ] +Run with: + +.. code-block:: console + + bandit -c pyproject.toml -r . + +.. _YAML file: https://yaml.org/ +.. _pyproject.toml file: https://www.python.org/dev/peps/pep-0518/ Skipping Tests -------------- + The bandit config may contain optional lists of test IDs to either include (`tests`) or exclude (`skips`). These lists are equivalent to using `-t` and `-s` on the command line. If only `tests` is given then bandit will include @@ -176,19 +236,21 @@ Suppressing Individual Lines If you have lines in your code triggering vulnerability errors and you are certain that this is acceptable, they can be individually silenced by appending -``# nosec`` to the line:: +``# nosec`` to the line: + +.. code-block:: python # The following hash is not used in any security context. It is only used # to generate unique values, collisions are acceptable and "data" is not # coming from user-generated input the_hash = md5(data).hexdigest() # nosec - In such cases, it is good practice to add a comment explaining *why* a given line was excluded from security checks. Generating a Config ------------------- + Bandit ships the tool `bandit-config-generator` designed to take the leg work out of configuration. This tool can generate a configuration file automatically. The generated configuration will include default config blocks @@ -201,7 +263,8 @@ a complete list of all test IDs for reference when editing). Configuring Test Plugins ------------------------ -Bandit's configuration file is written in `YAML `_ and options + +Bandit's configuration file is written in `YAML`_ and options for each plugin test are provided under a section named to match the test method. For example, given a test plugin called 'try_except_pass' its configuration section might look like the following: @@ -212,5 +275,9 @@ configuration section might look like the following: check_typed_exception: True The specific content of the configuration block is determined by the plugin -test itself. See the `plugin test list `_ for complete -information on configuring each one. +test itself. See the `plugin test list`_ for complete information on +configuring each one. + + +.. _YAML: https://yaml.org/ +.. _plugin test list: plugins/index.html diff --git a/doc/source/start.rst b/doc/source/start.rst index ca78d74d1..06a2206a3 100644 --- a/doc/source/start.rst +++ b/doc/source/start.rst @@ -3,85 +3,121 @@ Getting Started Installation ------------ -Bandit is distributed on PyPI. The best way to install it is with pip: +Bandit is distributed on PyPI. The best way to install it is with pip. -Create a virtual environment (optional):: +Create a virtual environment (optional): + +.. code-block:: console virtualenv bandit-env python3 -m venv bandit-env - # And activate it: + +And activate it: + +.. code-block:: console + source bandit-env/bin/activate -Install Bandit:: +Install Bandit: + +.. code-block:: console pip install bandit -Run Bandit:: +If you want to include TOML support, install it with the `toml` extras: + +.. code-block:: console + + pip install bandit[toml] + +Run Bandit: + +.. code-block:: console bandit -r path/to/your/code +Bandit can also be installed from source. To do so, either clone the +repository or download the source tarball from PyPI, then install it: -Bandit can also be installed from source. To do so, download the source tarball -from PyPI, then install it:: +.. code-block:: console python setup.py install +Alternatively, let pip do the downloading for you, like this: + +.. code-block:: console + + pip install git+https://github.com/PyCQA/bandit#egg=bandit Usage ----- -Example usage across a code tree:: + +Example usage across a code tree: + +.. code-block:: console bandit -r ~/your_repos/project Example usage across the ``examples/`` directory, showing three lines of -context and only reporting on the high-severity issues:: +context and only reporting on the high-severity issues: + +.. code-block:: console bandit examples/*.py -n 3 -lll Bandit can be run with profiles. To run Bandit against the examples directory -using only the plugins listed in the ``ShellInjection`` profile:: +using only the plugins listed in the ``ShellInjection`` profile: + +.. code-block:: console bandit examples/*.py -p ShellInjection Bandit also supports passing lines of code to scan using standard input. To -run Bandit with standard input:: +run Bandit with standard input: + +.. code-block:: console cat examples/imports.py | bandit - -For more usage information:: +For more usage information: - bandit -h +.. code-block:: console + bandit -h Baseline -------- + Bandit allows specifying the path of a baseline report to compare against using the base line argument (i.e. ``-b BASELINE`` or ``--baseline BASELINE``). -:: +.. code-block:: console bandit -b BASELINE This is useful for ignoring known vulnerabilities that you believe are non-issues (e.g. a cleartext password in a unit test). To generate a baseline report simply run Bandit with the output format set to ``json`` (only JSON-formatted files are accepted as a baseline) and output file path specified: -:: +.. code-block:: console bandit -f json -o PATH_TO_OUTPUT_FILE - Version control integration --------------------------- -Use `pre-commit `_. Once you `have it -installed `_, add this to the -`.pre-commit-config.yaml` in your repository -(be sure to update `rev` to point to a `real git tag/revision `_!):: +Use `pre-commit`_. Once you `have it installed`_, add this to the +``.pre-commit-config.yaml`` in your repository +(be sure to update `rev` to point to a `real git tag/revision`_!): + +.. code-block:: yaml repos: - - repo: https://github.com/PyCQA/bandit - rev: '' # Update me! - hooks: - - id: bandit + - repo: https://github.com/PyCQA/bandit + rev: '' # Update me! + hooks: + - id: bandit +Then run ``pre-commit install`` and you're ready to go. -Then run `pre-commit install` and you're ready to go. +.. _pre-commit: https://pre-commit.com/ +.. _have it installed: https://pre-commit.com/#install +.. _`real git tag/revision`: https://github.com/PyCQA/bandit/releases