Trento Checks

Trento Checks are the way Trento provides continous infractructure compliance.

They are implemented with a declarative, YAML-based DSL aiming at expressing some expectations on the configuration of a target system, or a group of target systems.

The Checks are then executed by our Trento checks engine, Wanda.

Usage

The Checks code was originally hosted together with Wanda itself and only later decoupled in this repository, so most of the related documentation will remain there until migrated somewhere else (if ever).

You can start learning more by consulting the specification document # Developing Checks

Wanda architecture aims to simplify testing Checks Executions and adding new ones.

Requirements

Make
Docker CLI or Podman using the Docker compatibility feature
Asdf

Setup

# add all rered plugins
asdf plugin add bats jq shellcheck shfmt
# install development software
asdf install

Starting a local environment

Start the environment with:

$ docker-compose up -d

Wanda is exposed on port 4000 and the API documentation is available at http://localhost:4000/swaggerui

Note that the message broker must be reachable by Wanda and all the targets.

Adding new Checks

Built-in Checks can be found in the Catalog directory at ./checks/

To implement new checks and test them:

write a new Check Specification file
locate the newly created Check in the Catalog directory ./checks/
test the execution as described in the check engine

Static code analysis

# run tlint on checks
# https://github.com/trento-project/tlint
make lint

# lint on shell scripts
make shellcheck

# format shell scripts and tests
make shfmt

Tests

The ./test folder contains the test suites for the checks catalog.

# Run tests against the local environment
make test

# Customize the environment URLs
WANDA_URL=http://wanda.example \
  FACTS_SERVICE_URL=amqp://user:pwd@rabbitmq.example:5672 \
  make test

Write a test

Tests are written in bash scripting using the Bats test framework.

A test suite is a file with .bats extension and they should be named after the check that is the subject of the test (for example, test/156F64.bats contains the tests for the check checks/156F64.yaml).

Every .bats file under ./test folder is executed.

The anatomy of a typical test is: * an instance of Trento agent that simulates the exepcted behaviour is spinned-up with a known agent id; * the instance must connect to the running development environment (Wanda and RabbitMQ); * a check execution is requested to Wanda for the current check on the given agent id; * the check result is requested to Wanda * the check result is evaluated by the test script according to the expectations * the Trento agent instance is tore down.

Test fixtures

To simulate different Trento agent behaviours, a containerized version is provided by Trento Barbecue, which defines file-based, ephemeral execution contexts for the Trento agent.

The ./test/fixtures folder contains a folder for each scenario we want to test our checks against.

To create a new fixture: * create a folder named by the fixture; * add all files to override the basic behavior; * optionally, add a setup.sh script to run manual modification to the image at build time.

Contributing

See CONTRIBUTING guide.

License

See the LICENSE notice.