Add docs for formatters
Add some documentation around the available formatters and how a user might want to plugin their own. Uses the sphinx autodoc feature. Change-Id: Ic90fbc3928de9149220209d6bd3b3be35b8a2f9a
This commit is contained in:
Eric Brown
parent
353634ff7a
commit
a829f94650
@ -12,6 +12,25 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
Description
|
||||
-----------
|
||||
This formatter outputs the issues in a comma separated values format.
|
||||
|
||||
Sample Output
|
||||
-------------
|
||||
.. code-block:: none
|
||||
|
||||
filename,test_name,issue_severity,issue_confidence,issue_text,line_number,
|
||||
line_range
|
||||
examples/yaml_load.py,blacklist_calls,MEDIUM,HIGH,"Use of unsafe yaml load.
|
||||
Allows instantiation of arbitrary objects. Consider yaml.safe_load().
|
||||
",5,[5]
|
||||
|
||||
.. versionadded:: 0.11.0
|
||||
|
||||
"""
|
||||
|
||||
from __future__ import absolute_import
|
||||
import csv
|
||||
import logging
|
||||
|
||||
@ -13,6 +13,136 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
Description
|
||||
-----------
|
||||
This formatter outputs the issues as HTML.
|
||||
|
||||
Sample Output
|
||||
-------------
|
||||
.. code-block:: html
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
|
||||
<title>
|
||||
Bandit Report
|
||||
</title>
|
||||
|
||||
<style>
|
||||
|
||||
html * {
|
||||
font-family: "Arial", sans-serif;
|
||||
}
|
||||
|
||||
pre {
|
||||
font-family: "Monaco", monospace;
|
||||
}
|
||||
|
||||
.bordered-box {
|
||||
border: 1px solid black;
|
||||
padding-top:.5em;
|
||||
padding-bottom:.5em;
|
||||
padding-left:1em;
|
||||
|
||||
}
|
||||
|
||||
.metrics-box {
|
||||
font-size: 1.1em;
|
||||
line-height: 130%;
|
||||
}
|
||||
|
||||
.metrics-title {
|
||||
font-size: 1.5em;
|
||||
font-weight: 500;
|
||||
margin-bottom: .25em;
|
||||
}
|
||||
|
||||
.issue-description {
|
||||
font-size: 1.3em;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.candidate-issues {
|
||||
margin-left: 2em;
|
||||
border-left: solid 1px; LightGray;
|
||||
padding-left: 5%;
|
||||
margin-top: .2em;
|
||||
margin-bottom: .2em;
|
||||
}
|
||||
|
||||
.issue-block {
|
||||
border: 1px solid LightGray;
|
||||
padding-left: .5em;
|
||||
padding-top: .5em;
|
||||
padding-bottom: .5em;
|
||||
margin-bottom: .5em;
|
||||
}
|
||||
|
||||
.issue-sev-high {
|
||||
background-color: Pink;
|
||||
}
|
||||
|
||||
.issue-sev-medium {
|
||||
background-color: NavajoWhite;
|
||||
}
|
||||
|
||||
.issue-sev-low {
|
||||
background-color: LightCyan;
|
||||
}
|
||||
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<span id='metrics'>
|
||||
<div class='metrics-box bordered-box'>
|
||||
<div class='metrics-title'>
|
||||
Metrics:<br>
|
||||
</div>
|
||||
Total lines of code: <span id='loc'>5</span><br>
|
||||
Total lines skipped (#nosec): <span id='nosec'>0</span>
|
||||
</div>
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
|
||||
<br>
|
||||
<span id='results'>
|
||||
|
||||
<span id='issue-0'>
|
||||
<div class='issue-block issue-sev-medium'>
|
||||
<b>blacklist_calls: </b> Use of unsafe yaml load. Allows instantiation
|
||||
of arbitrary objects. Consider yaml.safe_load().
|
||||
<br>
|
||||
<b>Severity: </b>MEDIUM<br />
|
||||
<b>Confidence: </b>HIGH</br />
|
||||
<b>File: </b><a href='examples/yaml_load.py' target='_blank'>
|
||||
examples/yaml_load.py</a> <br />
|
||||
|
||||
<span id='code'>
|
||||
<pre>
|
||||
4 ystr = yaml.dump({'a' : 1, 'b' : 2, 'c' : 3})
|
||||
5 y = yaml.load(ystr)
|
||||
6 yaml.dump(y)
|
||||
</pre>
|
||||
</span>
|
||||
|
||||
</div>
|
||||
</span>
|
||||
|
||||
</span>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
.. versionadded:: 0.14.0
|
||||
|
||||
"""
|
||||
|
||||
import logging
|
||||
|
||||
from bandit.core.test_properties import accepts_baseline
|
||||
|
||||
@ -12,6 +12,81 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
Description
|
||||
-----------
|
||||
This formatter outputs the issues in JSON.
|
||||
|
||||
Sample Output
|
||||
-------------
|
||||
.. code-block:: javascript
|
||||
|
||||
{
|
||||
"errors": [],
|
||||
"generated_at": "2015-12-16T22:27:34Z",
|
||||
"metrics": {
|
||||
"_totals": {
|
||||
"CONFIDENCE.HIGH": 1,
|
||||
"CONFIDENCE.LOW": 0,
|
||||
"CONFIDENCE.MEDIUM": 0,
|
||||
"CONFIDENCE.UNDEFINED": 0,
|
||||
"SEVERITY.HIGH": 0,
|
||||
"SEVERITY.LOW": 0,
|
||||
"SEVERITY.MEDIUM": 1,
|
||||
"SEVERITY.UNDEFINED": 0,
|
||||
"loc": 5,
|
||||
"nosec": 0
|
||||
},
|
||||
"examples/yaml_load.py": {
|
||||
"CONFIDENCE.HIGH": 1,
|
||||
"CONFIDENCE.LOW": 0,
|
||||
"CONFIDENCE.MEDIUM": 0,
|
||||
"CONFIDENCE.UNDEFINED": 0,
|
||||
"SEVERITY.HIGH": 0,
|
||||
"SEVERITY.LOW": 0,
|
||||
"SEVERITY.MEDIUM": 1,
|
||||
"SEVERITY.UNDEFINED": 0,
|
||||
"loc": 5,
|
||||
"nosec": 0
|
||||
}
|
||||
},
|
||||
"results": [
|
||||
{
|
||||
"code": "4 ystr = yaml.dump({'a' : 1, 'b' : 2, 'c' : 3})\n5
|
||||
y = yaml.load(ystr)\n6 yaml.dump(y)\n",
|
||||
"filename": "examples/yaml_load.py",
|
||||
"issue_confidence": "HIGH",
|
||||
"issue_severity": "MEDIUM",
|
||||
"issue_text": "Use of unsafe yaml load. Allows instantiation of
|
||||
arbitrary objects. Consider yaml.safe_load().\n",
|
||||
"line_number": 5,
|
||||
"line_range": [
|
||||
5
|
||||
],
|
||||
"test_name": "blacklist_calls"
|
||||
}
|
||||
],
|
||||
"stats": [
|
||||
{
|
||||
"filename": "examples/yaml_load.py",
|
||||
"issue totals": {
|
||||
"HIGH": 0,
|
||||
"LOW": 0,
|
||||
"MEDIUM": 1,
|
||||
"UNDEFINED": 0
|
||||
},
|
||||
"score": {
|
||||
"CONFIDENCE": 10,
|
||||
"SEVERITY": 5
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
.. versionadded:: 0.10.0
|
||||
|
||||
"""
|
||||
|
||||
from __future__ import absolute_import
|
||||
import datetime
|
||||
import json
|
||||
|
||||
@ -13,6 +13,28 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
Description
|
||||
-----------
|
||||
This formatter outputs the issues as plain text.
|
||||
|
||||
Sample Output
|
||||
-------------
|
||||
.. code-block:: none
|
||||
|
||||
>> Issue: [blacklist_calls] Use of unsafe yaml load. Allows instantiation
|
||||
of arbitrary objects. Consider yaml.safe_load().
|
||||
|
||||
Severity: Medium Confidence: High
|
||||
Location: examples/yaml_load.py:5
|
||||
4 ystr = yaml.dump({'a' : 1, 'b' : 2, 'c' : 3})
|
||||
5 y = yaml.load(ystr)
|
||||
6 yaml.dump(y)
|
||||
|
||||
.. versionadded:: 0.9.0
|
||||
|
||||
"""
|
||||
|
||||
import collections
|
||||
import datetime
|
||||
import logging
|
||||
|
||||
@ -12,6 +12,29 @@
|
||||
# License for the specific language governing permissions and limitations
|
||||
# under the License.
|
||||
|
||||
r"""
|
||||
Description
|
||||
-----------
|
||||
This formatter outputs the issues as XML.
|
||||
|
||||
Sample Output
|
||||
-------------
|
||||
.. code-block:: xml
|
||||
|
||||
<?xml version='1.0' encoding='utf-8'?>
|
||||
<testsuite name="bandit" tests="1"><testcase
|
||||
classname="examples/yaml_load.py" name="blacklist_calls"><error
|
||||
message="Use of unsafe yaml load. Allows instantiation of arbitrary
|
||||
objects. Consider yaml.safe_load(). " type="MEDIUM">Severity: MEDIUM
|
||||
Confidence: HIGH Use of unsafe yaml load. Allows instantiation of arbitrary
|
||||
objects. Consider yaml.safe_load().
|
||||
|
||||
Location examples/yaml_load.py:5</error></testcase></testsuite>
|
||||
|
||||
.. versionadded:: 0.12.0
|
||||
|
||||
"""
|
||||
|
||||
from __future__ import absolute_import
|
||||
import logging
|
||||
import sys
|
||||
|
||||
5
doc/source/formatters/csv.rst
Normal file
5
doc/source/formatters/csv.rst
Normal file
@ -0,0 +1,5 @@
|
||||
---
|
||||
csv
|
||||
---
|
||||
|
||||
.. automodule:: bandit.formatters.csv
|
||||
5
doc/source/formatters/html.rst
Normal file
5
doc/source/formatters/html.rst
Normal file
@ -0,0 +1,5 @@
|
||||
----
|
||||
html
|
||||
----
|
||||
|
||||
.. automodule:: bandit.formatters.html
|
||||
@ -1,2 +1,43 @@
|
||||
Bandit Report Formatters
|
||||
========================
|
||||
|
||||
Bandit supports many different formatters to output various security issues in
|
||||
python code. These formatters are created as plugins and new ones can be
|
||||
created to extend the functionality offered by bandit today.
|
||||
|
||||
Example Formatter
|
||||
-----------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def report(manager, filename, sev_level, conf_level, lines=-1,
|
||||
out_format='bson'):
|
||||
result = bson.dumps(issues)
|
||||
with utils.output_file(filename, 'w') as fout:
|
||||
fout.write(result)
|
||||
|
||||
To register your plugin, you have two options:
|
||||
|
||||
1. If you're using setuptools directly, add something like the following to
|
||||
your `setup` call::
|
||||
|
||||
# If you have an imaginary bson formatter in the bandit_bson module
|
||||
# and a function called `formatter`.
|
||||
entry_points={'bandit.formatters': ['bson = bandit_bson:formatter']}
|
||||
|
||||
2. If you're using pbr, add something like the following to your `setup.cfg`
|
||||
file::
|
||||
|
||||
[entry_points]
|
||||
bandit.formatters =
|
||||
bson = bandit_bson:formatter
|
||||
|
||||
|
||||
Complete Formatter Listing
|
||||
----------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
|
||||
5
doc/source/formatters/json.rst
Normal file
5
doc/source/formatters/json.rst
Normal file
@ -0,0 +1,5 @@
|
||||
----
|
||||
json
|
||||
----
|
||||
|
||||
.. automodule:: bandit.formatters.json
|
||||
5
doc/source/formatters/text.rst
Normal file
5
doc/source/formatters/text.rst
Normal file
@ -0,0 +1,5 @@
|
||||
----
|
||||
text
|
||||
----
|
||||
|
||||
.. automodule:: bandit.formatters.text
|
||||
5
doc/source/formatters/xml.rst
Normal file
5
doc/source/formatters/xml.rst
Normal file
@ -0,0 +1,5 @@
|
||||
---
|
||||
xml
|
||||
---
|
||||
|
||||
.. automodule:: bandit.formatters.xml
|
||||
Loading…
x
Reference in New Issue
Block a user