Skip to content

Commit

Permalink
Add contributing.md file
Browse files Browse the repository at this point in the history 
Resolves PyCQA#548

Add code of conduct.

Add links to contributing.md file.

Fix typo.

Fix docs for B610,B611,B703 (PyCQA#555)

* Fix docs for B610,B611,B703

* Address flake8 notice by adding blank line

* Fix long lines

Use SPDX license identifier instead of bulky headers (PyCQA#530)

* Use SPDX license identifier instead of bulky headers

There exists a nice, consistent way to denote licenses in source
files. It's called SPDX and further information is here [1].

This commit migrates the bulky apache-2 license headers with the
SPDX short identifier equivalent.

[1] https://spdx.org/ids-how

Signed-off-by: Eric Brown <browne@vmware.com>

* Update test-requirements.txt

Add a section explaining "nosec" (PyCQA#554)

* Add a section explaining "nosec"

References PyCQA#553

* Remove duplicated "in your code"

replace 'then' with 'than'

Signed-off-by: Pablo Woolvett <pablo.wooveltt@iconstruye.onmicrosoft.com>

Add sha1 to the list of insecure hashes

The hashlib.new test plugin was only checking for MD4 and MD5.
This patch extends the list of insecure hashes to include SHA1,
which has known exploits.

Fixes PyCQA#560

Signed-off-by: Eric Brown <browne@vmware.com>

Use GitHub Actions to run CI (PyCQA#565)

* Use GitHub Actions to run CI

This change utilizes GitHub Actions to run the CI for our unit tests instead of the current Travis-CI.

* Delete .travis.yml

Ignore common directories by default

This fix follows the example of flake8 in that it sets a default
list of common directories and filename patterns to exclude.

Fixes PyCQA#543

Signed-off-by: Eric Brown <browne@vmware.com>

Add push and pull request to GH Action trigger

It appears that Actions are not triggered for all pull requests.
I suspect the Actions need to register for event push and pull_request
in order to run CI on commits.

Signed-off-by: Eric Brown <browne@vmware.com>

Fix grammar issues and typos.

Fix more grammar issues

Added @lukehinds text

about commit messages and squash commits
from https://gist.githubusercontent.com/lukehinds/3337941149fc25ed91567037a0ebf026/raw/c1db6186c7e14ff316db2fe61fa046ab07251275/gistfile1.txt

Remove extra parentheses
  • Loading branch information
glyphack committed Feb 27, 2020
1 parent 7a2ef1b commit fa5981e
Show file tree
Hide file tree
Showing 2 changed files with 247 additions and 20 deletions.
244 changes: 244 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,244 @@
# Contributing to Bandit
Thanks for considering to take part in the improvement of Bandit project, contributions are always welcome!
Here are guidelines and rules that can be helpful if you plan to want to get involved in the project.

#### Table Of Contents
[Code of Conduct](#code-of-conduct)

[How Can I Contribute?](#how-can-i-contribute)
* [Reporting Bugs](#reporting-bugs)
* [Suggesting Enhancements](#suggesting-enhancements)
* [Your First Code Contribution](#your-first-code-contribution)
* [Pull Requests](#pull-requests)
* [Commit Message Guidelines](#commit-message-guidelines)
* [Squash Commits](#squash-commits)
* [Things You Should Know Before Getting Started](#things-you-should-know-before-getting-started)

## Code of Conduct
Everyone who participates in this project is governed by [Bandit Code of Conduct](https://github.com/Glyphack/bandit/blob/master/CODE_OF_CONDUCT.md#contributor-covenant-code-of-conduct).

## Reporting Bugs
If you encountered a bug and want to let us know use [GitHub issues](https://guides.github.com/features/issues/).

**Before submitting a new issue** you might want to check [existsing issue](https://github.com/PyCQA/bandit/issues) to know if there is already a reported issue and the issue is still open
in that case you can add a comment to the existing issue instead of creating a new one.

### Submitting your first issue
We encourage using a issue template to improve quality of reported issues, however if you feel limited by the template please format the issue in a manner that best allows you to describe the problem.
Navigate to the issues tab and select `new issue`, then select the **bug report** template and fill out the form,
to submit a good bug report keep in mind that:
* Use a descriptive title so other people can understand what the issue is about.
* Be specific about the details, for e.g. what command did you use, what version of Bandit did you use or in what
environment you observed the bug(CI or development) and other things that may be useful.

## Suggesting Enhancements
If you want to suggest and enhancement open a new issue and use the **feature request** template.

**Before submitting an enhancement** please check for existing [feature requests](https://github.com/PyCQA/bandit/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement)
and make sure the feature does not exist or requested already.

Useful things to point out in your feature request:
* Explain your feature request in a way that everyone can understand maybe with an example from another project or pictures
* Please try to explain how this feature can help Bandit project

## Your First Code Contribution
You can start contributing to Bandit project by picking [bug issues](https://github.com/PyCQA/bandit/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
These issues can be easier to resolve rather than a feature request and can get you up and running with the code base.

## Pull Requests
The best way to get started with Bandit is to grab the source:

`git clone https://github.com/PyCQA/bandit.git`

Create you own branch to start writing code:
```shell script
git checkout -b mybranch
git push origin mybranch
```
You can test any changes with tox:

```
pip install tox
tox -e pep8
tox -e py27
tox -e py35
tox -e docs
tox -e cover
```
If everything is done, proceed with [opening a new pull request](https://help.github.com/en/desktop/contributing-to-projects/creating-a-pull-request)

### Commit Message Guidelines

We follow the commit formatting recommendations found on [Chris Beams' How to Write a Git Commit Message article](https://chris.beams.io/posts/git-commit/).

Well formed commit messages not only help reviewers understand the nature of
the Pull Request, but also assists the release process where commit messages
are used to generate release notes.

A good example of a commit message would be as follows:

```
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
```

Note the `Resolves #123` tag, this references the issue raised and allows us to
ensure issues are associated and closed when a pull request is merged.

Please refer to [the github help page on message types](https://help.github.com/articles/closing-issues-using-keywords/)
for a complete list of issue references.

### Squash Commits

Should your pull request consist of more than one commit (perhaps due to
a change being requested during the review cycle), please perform a git squash
once a reviewer has approved your pull request.

A squash can be performed as follows. Let's say you have the following commits:

initial commit
second commit
final commit

Run the command below with the number set to the total commits you wish to
squash (in our case 3 commits):

git rebase -i HEAD~3

You default text editor will then open up and you will see the following::

pick eb36612 initial commit
pick 9ac8968 second commit
pick a760569 final commit

# Rebase eb1429f..a760569 onto eb1429f (3 commands)

We want to rebase on top of our first commit, so we change the other two commits
to `squash`:

pick eb36612 initial commit
squash 9ac8968 second commit
squash a760569 final commit

After this, should you wish to update your commit message to better summarise
all of your pull request, run:

git commit --amend

You will then need to force push (assuming your initial commit(s) were posted
to github):

git push origin your-branch --force

## Things You Should Know Before Getting Started

### Vulnerability Tests
Vulnerability tests or "plugins" are defined in files in the plugins directory.

Tests are written in Python and are autodiscovered from the plugins directory.
Each test can examine one or more type of Python statements. Tests are marked
with the types of Python statements they examine (for example: function call,
string, import, etc).

Tests are executed by the ``BanditNodeVisitor`` object as it visits each node
in the AST.

Test results are managed in the ``Manager`` and aggregated for
output at the completion of a test run through the method `output_result` from ``Manager`` instance.

### Writing Tests
To write a test:
- Identify a vulnerability to build a test for, and create a new file in
examples/ that contains one or more cases of that vulnerability.
- Consider the vulnerability you're testing for, mark the function with one
or more of the appropriate decorators:
- @checks('Call')
- @checks('Import', 'ImportFrom')
- @checks('Str')
- Create a new Python source file to contain your test, you can reference
existing tests for examples.
- The function that you create should take a parameter "context" which is
an instance of the context class you can query for information about the
current element being examined. You can also get the raw AST node for
more advanced use cases. Please see the context.py file for more.
- Extend your Bandit configuration file as needed to support your new test.
- Execute Bandit against the test file you defined in examples/ and ensure
that it detects the vulnerability. Consider variations on how this
vulnerability might present itself and extend the example file and the test
function accordingly.


### Extending Bandit

Bandit allows users to write and register extensions for checks and formatters.
Bandit will load plugins from two entry-points:

- `bandit.formatters`
- `bandit.plugins`

Formatters need to accept 5 things:

- `manager`: an instance of `bandit manager`
- `fileobj`: the output file object, which may be sys.stdout
- `sev_level` : Filtering severity level
- `conf_level`: Filtering confidence level
- `lines=-1`: number of lines to report

Plugins tend to take advantage of the `bandit.checks` decorator which allows
the author to register a check for a particular type of AST node. For example

::

@bandit.checks('Call')
def prohibit_unsafe_deserialization(context):
if 'unsafe_load' in context.call_function_name_qual:
return bandit.Issue(
severity=bandit.HIGH,
confidence=bandit.HIGH,
text="Unsafe deserialization detected."
)

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']}
# Or a check for using mako templates in bandit_mako that
entry_points={'bandit.plugins': ['mako = bandit_mako']}

2. If you're using pbr, add something like the following to your `setup.cfg`
file::

[entry_points]
bandit.formatters =
bson = bandit_bson:formatter
bandit.plugins =
mako = bandit_mako
23 changes: 3 additions & 20 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A security linter from PyCQA
* Documentation: https://bandit.readthedocs.io/en/latest/
* Source: https://github.com/PyCQA/bandit
* Bugs: https://github.com/PyCQA/bandit/issues

* Contributing: https://github.com/PyCQA/bandit/blob/master/CONTRIBUTING.md
Overview
--------
Bandit is a tool designed to find common security issues in Python code. To do
Expand Down Expand Up @@ -424,25 +424,8 @@ To register your plugin, you have two options:

Contributing
------------
Contributions to Bandit are always welcome!

The best way to get started with Bandit is to grab the source::

git clone https://github.com/PyCQA/bandit.git

You can test any changes with tox::

pip install tox
tox -e pep8
tox -e py27
tox -e py35
tox -e docs
tox -e cover

Please make PR requests using your own branch, and not master::

git checkout -b mychange
git push origin mychange
Follow our Contributing file:
https://github.com/PyCQA/bandit/blob/master/CONTRIBUTING.md

Reporting Bugs
--------------
Expand Down

0 comments on commit fa5981e

Please sign in to comment.