From f11e9b8ace63a11cdc1c9e89857b9c77056fa558 Mon Sep 17 00:00:00 2001 From: Travis McPeak Date: Wed, 6 May 2015 13:23:57 -0400 Subject: [PATCH] Update the README file The readme file has been updated to: - Be more concise up front about the purpose of Bandit - Reflect new install methods (from PyPI) - Update configuration section - Convert to markdown format (we had this anyway, it was just called .rst for some reason) Change-Id: Ibb39e9fe64760323240c1180d4df8c8e21349ecb --- README.rst => README.md | 94 ++++++++++++++++++++++++++--------------- setup.cfg | 2 +- 2 files changed, 61 insertions(+), 35 deletions(-) rename README.rst => README.md (65%) diff --git a/README.rst b/README.md similarity index 65% rename from README.rst rename to README.md index be77dec4..839f7ec7 100644 --- a/README.rst +++ b/README.md @@ -1,60 +1,59 @@ Bandit ====== -A Python AST-based static analyzer from OpenStack Security Group. +A security linter from OpenStack Security Overview -------- -Bandit provides a framework for performing analysis against Python source code, -utilizing the ast module from the Python standard library. - -The ast module is used to convert source code into a parsed tree of Python -syntax nodes. Bandit allows users to define custom tests that are performed -against those nodes. At the completion of testing, a report is generated that -lists security issues identified within the target source code. - +Bandit is a tool designed to find common security issues in Python code. To do +this Bandit processes each file, builds an AST from it, and runs appropriate +plugins against the AST nodes. Once Bandit has finished scanning all the files +it generates a report. Installation ------------ -Bandit is distributed as an installable package. To clone and install in a -Python virtual environment:: +Bandit is distributed on PyPI. The best way to install it is with pip: - $ git clone https://git.openstack.org/stackforge/bandit.git - $ cd bandit - $ virtualenv venv - $ source venv/bin/activate - $ python setup.py install -To test the new installation:: +***Create a virtual environment (optional):*** - $ pip install tox - $ tox -epy27 + virtualenv bandit-env -To run PEP8 tests on diffs:: +***Install Bandit:*** - $ tox -v -epep8 + pip install bandit + +***Run Bandit:*** + + bandit -r path/to/your/code + + +Bandit can also be installed from source. To do so, download the source +tarball from PyPI, then install it: + + python setup.py install Usage ----- -Example usage across a code tree, showing one line of context for each issue:: +Example usage across a code tree: - $ bandit -r -n 1 ~/openstack-repo/keystone + bandit -r ~/openstack-repo/keystone Example usage across the examples/ directory, showing three lines of context -and only reporting on the high-severity issues:: +and only reporting on the high-severity issues: - $ bandit examples/*.py -n 3 -lll + bandit examples/*.py -n 3 -lll -Example usage across the examples/ directory, showing one line of context and -running only tests in the ShellInjection profile:: +Bandit can be run with profiles. To run Bandit against the examples directory +using only the plugins listed in the ShellInjection profile: - $ bandit examples/*.py -n 1 -p ShellInjection + bandit examples/*.py -p ShellInjection Usage:: - $ bandit -h + bandit -h usage: bandit [-h] [-a AGG_TYPE] [-n CONTEXT_LINES] [-c CONFIG_FILE] [-p PROFILE] [-l] [-o OUTPUT_FILE] [-d] file [file ...] @@ -87,12 +86,22 @@ Usage:: Configuration ------------- -The default configuration file is bandit.yaml. This specifies a number of -global options, and allows the creation of separate test profiles to include -or exclude specific tests when Bandit is run. +The Bandit config file is used to set several things, including: + - profiles - defines group of tests which should or shouldn't be run + - exclude_dirs - sections of the path, that if matched, will be excluded from + scanning + - plugin configs - used to tune plugins, for example: by tuning + blacklist_imports, you can set which imports should be flagged + - other - plugins directory, included file types, shell display + colors, etc. -Additional configuration files can be created and passed to Bandit as a -command line argument. +Bandit requires a config file. Bandit will use bandit.yaml in the following +preference order: + + - Bandit config file specified with -c command line option + - bandit.yaml file from current working directory + - bandit.yaml file from ~/.config/bandit/ + - bandit.yaml file in config/ directory of the Bandit package Exclusions @@ -147,6 +156,23 @@ To write a test: function accordingly. +Contributing +------------ +Contributions to Bandit are always welcome! We can be found on #openstack-security +on Freenode IRC. + +The best way to get started with Bandit is to grab the source: + + git clone https://git.openstack.org/stackforge/bandit.git + +You can test any changes with tox: + + pip install tox + tox -e pep8 + tox -e py27 + tox -e cover + + References ========== diff --git a/setup.cfg b/setup.cfg index dca403f5..c16fc894 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,7 +2,7 @@ name = bandit summary = Security oriented static analyser for python code. description-file = - README.rst + README.md author = OpenStack Security Group author-email = openstack-dev@lists.openstack.org home-page = https://wiki.openstack.org/wiki/Security/Projects/Bandit