[docs] Mention exclude_dirs option available in TOML and YAML

doc/source/config.rst

@@ -5,62 +5,106 @@ 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
 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 <http://yaml.org/>`_ 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 <https://www.python.org/dev/peps/pep-0518/>`_ 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 <http://yaml.org/>`_ 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 <plugins/index.html>`_ 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

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 <https://pre-commit.com/>`_. Once you `have it
-installed <https://pre-commit.com/#install>`_, add this to the
-`.pre-commit-config.yaml` in your repository
-(be sure to update `rev` to point to a `real git tag/revision <https://github.com/PyCQA/bandit/releases>`_!)::
+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