diff --git a/README.md b/README.md index 38ffd23..057423c 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,57 @@ Docker bench requires Docker 1.6.2 or later in order to run, since it depends on Additionally, there was a bug in Docker 1.6.0 that would not allow mounting `-v /dev:/dev`. If you are getting an error while accessing `resolv.conf`, please update your docker to 1.6.2. Also note that the default image and `Dockerfile` uses `FROM: alpine` which doesn't contain `auditctl`, this will generate errors in section 1.8 to 1.18. Distribution specific Dockerfiles that fixes this issue are available in the [distros directory](https://github.com/docker/docker-bench-security/tree/master/distros). +## Running Docker Bench Bats tests + +[Bats](https://github.com/sstephenson/bats) is a [TAP](http://testanything.org/)-compliant testing framework for Bash. It provides a simple way to verify that the UNIX programs you write behave as expected. + +All Docker Bench scipts are also available as Bats tests. Also container level (and image level) tests are automatically generated for all containers avaiable on host. It's possible to run all or only selected test(s), if you like. + +By default TAP test results are reported, but it's possible to produce a "pretty" printed output too. + +Use the following command to run Docker Bench Bats tests: + +``` +Help documentation for run_tests.sh + +Basic usage: run_tests.sh [-c] [-p|-t] [-o path] [ ...] + +Command line switches are optional. The following switches are recognized. +-c --Displays number of tests. No further functions are performed. +-g --Generates all CIS Bats tests without execution. No further functions are performed. +-p --Show results in pretty format. +-t --Show results in TAP format. This is the default format. +-t --Create test results files: tests_.tap in test result folder. +-o --Specify test result folder. Default to /var/docker-bench/results. +-h --Displays this help message. No further functions are performed. + +Example: run_tests.sh -t -o /var/docker-bench/results +``` + +You need to run `run_tests.sh` on Docker host as `root` user. + +### Running Docker Bench Bats tests from Docker image + +First, clone and compile your `docker-bench-tests` Docker image. + +```sh +git clone https://github.com/gaia-adm/docker-bench-security.git +cd docker-bench-security +docker build -t docker-bench-tests -f bats.Dockerfile . +``` + +Then run `docker-bench-tests` container (as bellow). Test results will be saved into `/var/docker-bench` folder in TAP format. Test results file is named accoring to the `test_.tap` pattern. + +```sh +docker run -it --net host --pid host --cap-add audit_control \ + -v /var/lib:/var/lib \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v /usr/lib/systemd:/usr/lib/systemd \ + -v /var/docker-bench:/var/docker-bench + -v /etc:/etc --label docker_bench_security \ + docker-bench-tests +``` + ## Building Docker Bench for Security If you wish to build and run this container yourself, you can follow the following steps: