No description, website, or topics provided.
Python
Latest commit 484141f Feb 22, 2017 @willthames committed on GitHub Merge pull request #17 from ypid/fix/code_execution_vulnerability
Fix code execution vulnerability by switching to yaml.safe_load
Permalink
Failed to load latest commit information.
lib/ansiblereview Fix code execution vulnerability by switching to yaml.safe_load Feb 21, 2017
test Add check for competing group variables Aug 12, 2016
.gitignore Construct Error object correctly May 17, 2016
.travis.yml
CHANGELOG.md Python3 readiness Dec 8, 2016
LICENSE
MANIFEST.in Improve ansible-review packaging Dec 15, 2016
README.md Allow filtering of standards Sep 28, 2016
setup.cfg
setup.py
test-deps.txt
tox.ini

README.md

Setup

Using pip

pip install ansible-review

From source

# Install dependency https://github.com/willthames/ansible-lint
git clone https://github.com/willthames/ansible-review
export PYTHONPATH=$PYTHONPATH:`pwd`/ansible-review/lib
export PATH=$PATH:`pwd`/ansible-review/bin

Usage

ansible-review reviewtarget [target2...]

ansible-review will review inventory files, role files, python code (modules, plugins) and playbooks.

  • The goal is that each file that changes in a changeset should be reviewable simply by passing those files as the arguments to ansible-review.
  • Roles are slightly harder, and sub-roles are yet harder still (currently just using -R to process roles works very well, but doesn't examine the structure of the role)
  • Using {{ playbook_dir }} in sub roles is so far very hard.
  • This should work against various repository styles
    • per-role repository
    • roles with sub-roles
    • per-playbook repository
  • It should work with rolesfiles and with local roles.

Typical approaches

  • git ls-files | xargs ansible-review works well in a roles repo to review the whole role. But it will review the whole of other repos too.
  • git diff branch_to_compare | ansible-review will review only the changes between the branches and surrounding context.

Reviews

Reviews are nothing without some standards or checklists against which to review.

ansible-review comes with a couple of built-in checks, such as a playbook syntax checker and a hook to ansible-lint. You define your own standards.

Configuration

If your standards (and optionally inhouse lint rules) are set up, create a configuration file in the appropriate location (this will depend on your operating system)

The location can be found by using ansible-review with no arguments.

You can override the configuration file location with the -c flag.

[rules]
lint = /path/to/your/ansible/lint/rules
standards = /path/to/your/standards/rules

The standards directory can be overridden with the -d argument, and the lint rules directory can be overriden with the -r argument.

Standards file

A standards file comprises a list of standards, and optionally some methods to check those standards.

Create a file called standards.py (this can import other modules)

from ansiblereview include Standard, Result

use_modules_instead_of_command = Standard(dict(
    name = "Use modules instead of commands",
    version = "0.2",
    check = ansiblelint('ANSIBLE0005,ANSIBLE0006'),
    types = ['playbook', 'task'],
))

standards = [
  use_modules_instead_of_command,
  packages_should_not_be_latest,
]

When you add new standards, you should increment the version of your standards. Your playbooks and roles should declare what version of standards you are using, otherwise ansible-review assumes you're using the latest.

To add standards that are advisory, don't set the version. These will cause a message to be displayed but won't constitute a failure.

An example standards file is available in examples/standards.py

If you only want to check one or two standards quickly (perhaps you want to review your entire code base for deprecated bare words), you can use the -s flag with the name of your standard. You can pass -s multiple times.

git ls-files | xargs ansible-review -s "bare words are deprecated for with_items"

you can see the name of the standards being checked for each different file by running ansible-review with the -v option.

Standards checks

A typical standards check will look like:

def check_playbook_for_something(candidate, settings):
    result = Result(candidate.path) # empty result is a success with no output
    with open(candidate.path, 'r') as f:
        for (lineno, line) in enumerate(f):
            if line is dodgy:
                # enumerate is 0-based so add 1 to lineno
                result.errors.append(Error(lineno+1, "Line is dodgy: reasons"))
    return result

All standards check take a candidate object, which has a path attribute. The type can be inferred from the class name (i.e. type(candidate).__name__)

They return a Result object, which contains a possibly empty list of Error objects. Error objects are formed of a line number and a message. If the error applies to the whole file being reviewed, set the line number to None. Line numbers are important as ansible-review can review just ranges of files to only review changes (e.g. through piping the output of git diff to ansible-review)

The ansiblelint check is ready out of the box, and just takes a list of IDs or tags to check. You can point to your own ansible-lint rules using the configuration file or -d /path/to/ansible/lint/rules