auditree-framework

Tool to run compliance control checks as unit tests and build up a body of evidence.

This framework gives you the tools you need to create an auditable body of evidence, and is designed to be "DevSecOps" friendly. Collection & validation of evidence is modelled as python unit tests, evidence is stored & versioned in a git repository, notifications can be configured to send to Slack, create issues, contact PagerDuty, or just write files into git. The goal is to enable the digital transformation of compliance activities, and make these everyday operational tasks for the team managing the system.

Installation

Prerequisites

• Supported for execution on OSX and LINUX.
• Supported for execution with Python 3.6 and above.

If you haven't already you need to generate a new ssh key for your Github account as per this guide

Check out the code

git clone git@github.com:ComplianceAsCode/auditree-framework
cd auditree-framework

For users

python3 -m venv venv
. venv/bin/activate
make install

For developers

python3 -m venv venv
. venv/bin/activate
make develop

Code style and formatting

This repository uses yapf for code formatting and flake8 for code styling. It also uses pre-commit hooks that are integrated into the development process and the CI. When you run make develop you are ensuring that the pre-commit hooks are installed and updated to their latest versions for this repository. This ensures that all delivered code has been properly formatted and passes the linter rules. See the pre-commit configuration file for details on yapf and flake8 configurations.

Since yapf and flake8 are installed as part of the pre-commit hooks, running yapf and flake8 manually must be done through pre-commit. See examples below:

make code-format
make code-lint

...will run yapf and flake8 on the entire repo and is equivalent to:

pre-commit run yapf --all-files
pre-commit run flake8 --all-files

...and when looking to limit execution to a subset of files do similar to:

pre-commit run yapf --files compliance/*
pre-commit run flake8 --files compliance/*

Unit tests

To run the frameworks test suite, use:

make test

Build Documentation

Documentation sources live in doc-source, and are also auto-generated from the source codes doc strings. The auto-generated documentation (compliance*rst, modules.rst) is ignored by git & should not be modified directly - make changes in the python code.

To build the documentation locally run:

make docs

This will update the files in doc with the latest documentation. These files should not be modified by hand.

Try it

First, create an empty credentials file:

touch ~/.credentials

Go to the demo checks and install required dependencies:

cd doc/demo-checks
pip install -r requirements.txt

Run the fetchers:

compliance --fetch -v --evidence=local -C setup.json

And then run the checks of the demo accreditations:

compliance --check demo.accreditation1,demo.accreditation2 --evidence=local -v -C setup.json

See a more detailed quick start guide.

Contribute

Help us to improve the Auditree framework. See CONTRIBUTING.

Ecosystem

We are building a set of common fetchers/checks in Arboretum. If you have a library of checks, please let us know & we'll link here.

We have a data gathering and reporting tool called Harvest which lets you process your evidence locker and generate reports over the data held.

We have a tool called Prune which lets you mark evidence as no longer being collected, in a suitably tracked manner.

We have a tool called Plant which lets you add evidence to evidence lockers without the use of fetchers or checks.