From 0fabff579d7eb42326ab76aad7c96fe7a6578fb9 Mon Sep 17 00:00:00 2001 From: Jamie Finnigan Date: Wed, 23 Mar 2016 13:54:09 -0700 Subject: [PATCH] Normalizing & editing command-line help text This commit contains a number of relatively minor changes to the help text displayed by Bandit when 'bandit -h' is executed. It is an attempt to normalize (capitalization, formatting, and usage of certain terms) and edit for clarity. It also updates the README to include the new help text, and the test that checks the README is up-to-date. Change-Id: Ic583f891a295ac13339db1f65bcf38d66bd2abcd --- README.rst | 46 +++++++++++++++----------------- bandit/cli/main.py | 45 +++++++++++++++---------------- tests/functional/test_runtime.py | 6 +++-- 3 files changed, 46 insertions(+), 51 deletions(-) diff --git a/README.rst b/README.rst index c843fbc2..94773456 100644 --- a/README.rst +++ b/README.rst @@ -83,56 +83,52 @@ Usage:: [--ini INI_PATH] [--version] targets [targets ...] - Bandit - a Python source code analyzer. + Bandit - a Python source code security analyzer positional arguments: targets source file(s) or directory(s) to be tested optional arguments: -h, --help show this help message and exit - -r, --recursive process files in subdirectories + -r, --recursive find and process files in subdirectories -a {file,vuln}, --aggregate {file,vuln} - group results by vulnerability type or file it occurs - in + aggregate output by vulnerability (default) or by + filename -n CONTEXT_LINES, --number CONTEXT_LINES - max number of code lines to display for each issue - identified + maximum number of code lines to output for each issue -c CONFIG_FILE, --configfile CONFIG_FILE optional config file to use for selecting plugins and overriding defaults -p PROFILE, --profile PROFILE - test set profile in config to use (defaults to all - tests) + profile to use (defaults to executing all tests) -t TESTS, --tests TESTS - comma separated list of test IDs to run + comma-separated list of test IDs to run -s SKIPS, --skip SKIPS - comma separated list of test IDs to skip - -l, --level results severity filter. Show only issues of a given - severity level or higher. -l for LOW, -ll for MEDIUM, - -lll for HIGH - -i, --confidence confidence results filter, show only issues of this - level or higher. -i for LOW, -ii for MEDIUM, -iii for - HIGH + comma-separated list of test IDs to skip + -l, --level report only issues of a given severity level or higher + (-l for LOW, -ll for MEDIUM, -lll for HIGH) + -i, --confidence report only issues of a given confidence level or + higher (-i for LOW, -ii for MEDIUM, -iii for HIGH) -f {csv,html,json,screen,txt,xml}, --format {csv,html,json,screen,txt,xml} specify output format -o OUTPUT_FILE, --output OUTPUT_FILE write report to filename - -v, --verbose show extra information like excluded and included + -v, --verbose output extra information like excluded and included files -d, --debug turn on debug mode --ignore-nosec do not skip lines with # nosec comments -x EXCLUDED_PATHS, --exclude EXCLUDED_PATHS - Comma separated list of paths to exclude from scan. - Note that these are in addition to the excluded paths - provided in the config file. + comma-separated list of paths to exclude from scan + (note that these are in addition to the excluded paths + provided in the config file) -b BASELINE, --baseline BASELINE - Path to a baseline report. Only JSON formatted files - are accepted. - --ini INI_PATH Path to a .bandit file which supplies command line - arguments to Bandit. + path of a baseline report to compare against (only + JSON-formatted files are accepted) + --ini INI_PATH path to a .bandit file that supplies command line + arguments --version show program's version number and exit - The following plugin suites were discovered and loaded: + The following tests were discovered and loaded: B101 assert_used B102 exec_used B103 set_bad_file_permissions diff --git a/bandit/cli/main.py b/bandit/cli/main.py index edec3716..df357fde 100644 --- a/bandit/cli/main.py +++ b/bandit/cli/main.py @@ -149,7 +149,7 @@ def main(): # now do normal startup parser = argparse.ArgumentParser( - description='Bandit - a Python source code analyzer.', + description='Bandit - a Python source code security analyzer', formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument( @@ -158,51 +158,49 @@ def main(): ) parser.add_argument( '-r', '--recursive', dest='recursive', - action='store_true', help='process files in subdirectories' + action='store_true', help='find and process files in subdirectories' ) parser.add_argument( '-a', '--aggregate', dest='agg_type', action='store', default='file', type=str, choices=['file', 'vuln'], - help='group results by vulnerability type or file it occurs in' + help='aggregate output by vulnerability (default) or by filename' ) parser.add_argument( '-n', '--number', dest='context_lines', action='store', default=3, type=int, - help='max number of code lines to display for each issue identified' + help='maximum number of code lines to output for each issue' ) parser.add_argument( '-c', '--configfile', dest='config_file', action='store', default=None, type=str, - help=('optional config file to use for selecting plugins and ' - 'overriding defaults') + help='optional config file to use for selecting plugins and ' + 'overriding defaults' ) parser.add_argument( '-p', '--profile', dest='profile', action='store', default=None, type=str, - help='test set profile in config to use (defaults to all tests)' + help='profile to use (defaults to executing all tests)' ) parser.add_argument( '-t', '--tests', dest='tests', action='store', default=None, type=str, - help='comma separated list of test IDs to run' + help='comma-separated list of test IDs to run' ) parser.add_argument( '-s', '--skip', dest='skips', action='store', default=None, type=str, - help='comma separated list of test IDs to skip' + help='comma-separated list of test IDs to skip' ) parser.add_argument( '-l', '--level', dest='severity', action='count', - default=1, help=('results severity filter. Show only issues of a given' - ' severity level or higher. -l for LOW,' - ' -ll for MEDIUM, -lll for HIGH') + default=1, help='report only issues of a given severity level or ' + 'higher (-l for LOW, -ll for MEDIUM, -lll for HIGH)' ) parser.add_argument( '-i', '--confidence', dest='confidence', action='count', - default=1, help='confidence results filter, show only issues of this ' - 'level or higher. -i for LOW, -ii for MEDIUM, ' - '-iii for HIGH' + default=1, help='report only issues of a given confidence level or ' + 'higher (-i for LOW, -ii for MEDIUM, -iii for HIGH)' ) output_format = 'screen' if sys.stdout.isatty() else 'txt' parser.add_argument( @@ -216,7 +214,7 @@ def main(): ) parser.add_argument( '-v', '--verbose', dest='verbose', action='store_true', - help='show extra information like excluded and included files' + help='output extra information like excluded and included files' ) parser.add_argument( '-d', '--debug', dest='debug', action='store_true', @@ -228,19 +226,18 @@ def main(): ) parser.add_argument( '-x', '--exclude', dest='excluded_paths', action='store', - default='', help='Comma separated list of paths to exclude from scan. ' - 'Note that these are in addition to the excluded ' - 'paths provided in the config file.' + default='', help='comma-separated list of paths to exclude from scan ' + '(note that these are in addition to the excluded ' + 'paths provided in the config file)' ) parser.add_argument( '-b', '--baseline', dest='baseline', action='store', - default=None, help=('Path to a baseline report. Only JSON formatted ' - 'files are accepted.') + default=None, help='path of a baseline report to compare against ' + '(only JSON-formatted files are accepted)' ) parser.add_argument( '--ini', dest='ini_path', action='store', default=None, - help='Path to a .bandit file which supplies command line arguments to ' - 'Bandit.' + help='path to a .bandit file that supplies command line arguments' ) parser.add_argument( '--version', action='version', @@ -258,7 +255,7 @@ def main(): blacklist_info.append('%s\t%s' % (b['id'], b['name'])) plugin_list = '\n\t'.join(sorted(set(plugin_info + blacklist_info))) - parser.epilog = ('The following plugin suites were discovered and' + parser.epilog = ('The following tests were discovered and' ' loaded:\n\t{0}\n'.format(plugin_list)) # setup work - parse arguments, and initialize BanditManager diff --git a/tests/functional/test_runtime.py b/tests/functional/test_runtime.py index b84dbd61..e92f0d72 100644 --- a/tests/functional/test_runtime.py +++ b/tests/functional/test_runtime.py @@ -57,11 +57,13 @@ class RuntimeTests(testtools.TestCase): def test_help_arg(self): (retcode, output) = self._test_runtime(['bandit', '-h']) self.assertEqual(0, retcode) - self.assertIn("Bandit - a Python source code analyzer.", output) + self.assertIn( + "Bandit - a Python source code security analyzer", output + ) self.assertIn("usage: bandit [-h]", output) self.assertIn("positional arguments:", output) self.assertIn("optional arguments:", output) - self.assertIn("plugin suites were discovered and loaded:", output) + self.assertIn("tests were discovered and loaded:", output) def test_help_in_readme(self): replace_list = [' ', '\t']