ansible-audit

KO | EN

gitlite — search

#javascript #react #ai #go #golang #linux #macos #java #cli #kubernetes #vue #awesome-list #ios #open-source

(★ 8)

Ansible auditing callback plugin

ansible-audit Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# audit

An Ansible callback plugin to assist in auditing environments in conjunction
with a playbook expecting errors to be present.

- [License](#license)
- [Description](#description)
- [Use Cases](#use_case)
- [How To Use](#usage)
- [Playbook](#playbook_example)
- [Output](#output)

## License

This file is part of Ansible

Ansible is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Ansible is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Ansible.  If not, see <http://www.gnu.org/licenses/>.

## Description

This module assists in auditing devices/systems with an ansible playbook.
Typically ansible stops on erroring tasks, however, this plugin relies on
tasks having 'ignore_errors: yes' so ansible continues processing the play
book.  This plugin then produces a report on success and failures in a number
of formats.

This plugin works around the fact that ansible will typically stop on failure,
or, ignore failures without maintaining desired statistics.  This plugin
expects playbook tasks to fail and be ignored in the playbook which allows us
to keep statistics regarding the failures, warnings, ok's etc.

## Use Cases

You might consider using this callback plugin if:

* You wish to audit desired state, but, not change state on a bunch of systems

## Usage

First, either copy the following files to your ansible callback plugins
directory.  `audit.py`, `audit_fruitsalad.jinja` and `audit_results.jinja`.

Or, easier still, create a `callback_plugins` directory in the same
directory as your playbook and copy the above files into this new
directory.

### External variables

A number of variables can be passed through to the audit plugin modifying
configuration or providing content to the jinja templates.

* AUDIT_NAME - The name of the audit. If left blank, defaults to 'No audit name specified'
* CUSTOMER - A customer name.  If left blank, defaults to 'No customer specified'
* OUTPUT_DIR - Where to output the zip file containing the JSON and HTML files.
* DISPLAY_PATH - If 'TRUE', display path to zip file on finish.  Default is not to display.

Ansible specific:
* ANSIBLE_CALLBACK_WHITELIST - Instructs ansible to use the custom
  plugin. **Note:** This requirement has been removed.

### Examples

Example when files are in the ansible module directory:
    To use this plugin in conjunction with your playbook, below are some
    options on how to run::

```bash
        $ AUDIT_NAME='My Systems' CUSTOMER="CUSTOMER" \
            DISPLAY_PATH=TRUE \
            ansible-playbook --ask-sudo-pass site.yml -k
```

This will audit the systems referenced in your site.yml playbook and output
a zip file into the self.config['working_dir'], and, print out the path to
the zip file.

Example, when the files are stored in a separate modules path:

```bash
        $ AUDIT_NAME='My Systems' CUSTOMER="CUSTOMER" \
            ANSIBLE_CONFIG='./audit/ansible.cfg' \
            OUTPUT_DIR=/tmp/audit/ DISPLAY_PATH=TRUE \
            ansible-playbook --ask-sudo-pass ansible-audit-playbook-example/site.yml -k
```

Where the ./audit/ansible.cfg contains a directive pointing to your callback
plugins directory.  I simply copied the default /etc/ansible/ansible.cfg and
modified the callback_plugins directive to suit my needs.  For instance:

```
[defaults]

callback_plugins   = /usr/share/ansible/plugins/callback:./:./audit
```

Tested with:
* ansible 2.3.0.0, 2.3.1.0, 2.4.3 & 2.5.0
* python version = 2.7.12

## Playbook example

`ignore_errors: yes` is required as we don't want ansible stopping on failure.

`changed_when: false` is required as the commands/shell should NOT change any state.
We don't want ansible saying the result of the task is changed.

```
- name: 1. Failing task
  command: /bin/false
  ignore_errors: yes
  changed_when: false

- name: 2. Succeeding task
  command: /bin/false
  ignore_errors: yes
  changed_when: false

- name: 3. Warning task
  shell: |
    echo "WARNING: This task returned a warning."
    exit 1
  args:
    executable: /bin/bash
  ignore_errors: yes
  changed_when: false

- name: 4. Warning task
  shell: |
    echo "WARNING: This task returns a warning too."
    exit 0
  args:
    executable: /bin/bash
  ignore_errors: yes
  changed_when: false

- name: _Don't report on this task
  debug:
    msg: "Tasks that have no name, or, name prepended with _ won't be displayed in the results"

```

For a complete example, check out: https://github.com/Im0/ansible-audit-playbook-example

## Output

The plugin will produce a zipfile within the configured directory defined in
self.config['working_dir'].  The zip file contains a JSON file and two HTML
files.

`working_dir` can be overwritten by specifying the external variable OUTPUT_DIR.
ie.  OUTPUT_DIR=/tmp/ansible

Alter the jinja templates if you wish to adjust the look and feel of the HTML
output.

ansible-audit

ansible-audit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ansible-audit

ansible-audit Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README