Skip to content

Providentia is a tool to manage cyber-exercise technical knowledge


Notifications You must be signed in to change notification settings



Repository files navigation

Clarified Security built tools:

ProvidentiaCatapult • EXPO

Providentia image

Providentia manages the inventory of your cyber exercise/lab/infrastructure environment: networks, hosts and more. The powerful JSON API can be used a single, centralized source of truth for rest of your toolset. Works best with Catapult.

Getting started

While it is possible to run Providentia on a host directly, the recommended approach is to use Docker containers and bundled Makefile. The requirements for this are:

  • make
  • python3
  • docker
  • docker compose plugin (version > 2)

First steps:


In development mode, the user who is cloning the repository should also be the one building the image and running Providentia in order to avoid file permission errors. Do not run the following commands as root, unless you know exactly what you are doing.

  1. Clone the repository

  2. Configure by running make config (will be run automatically if makevars file is missing)

    This will ask if you need to use sudo for launching docker, which in most cases is yes.

  3. Build the container images with make build

  4. Run the app with make start

    The local directory will be mounted in the container in development mode.


Development mode only works on the machine it's launched on, it will not function over network!


git clone
cd Providentia
make config # choose dev
make build
make start

After bootup, Providentia can be accessed at http://providentia.localhost and Keycloak will be running at http://keycloak.localhost. You may need to trust the self-signed TLS certificate if running production mode.


Providentia is a Ruby on Rails based web application, but contains multiple containers by default:



  • u: admin p: adminsecret


On first development mode boot, a sample exercise is created for you - "Test exercise".

  • u: providentia.admin p: providentia.admin-pass - has access to everything.
  • u: providentia.rt p: providentia.rt-pass - has access to Test Exercise as RT member (can see RT virtual machines).
  • u: p: - has access to Test Exercise as GT member (cannot see RT virtual machines)
  • u: providentia.teadmin p: providentia.teadmin-pass - has access to Test Exercise as environment administrator

Running in production


Default production configuration is insecure! Be warned!

The make based bootstrap can be used to start the application in production mode as well. It is primarily meant to be inspiration on how a production environment might look like - it is not meant to be used without altering it first.

The steps for setting up are similar to dev instructions above, except answer 'prod' when prompted for environment. Have a look at docker/prod directory on how the setup works and adapt it to your needs using configuration files:

  • web.env
  • db.env
  • docker-compose.yml
  • initdb.sql

A good example on how Providentia could be deployed in production via ansible can be seen at nova.core role


The main use case is consuming the API to create Ansible inventory in order to deploy networks and hosts to a virtualization environment. Since its creation in 2020, Providentia has been used to plan and deploy numerous Locked Shields (LS), Crossed Swords (XS) and other non-public cyber exercises.

  • Can be used to manage infrastructure, defensive or offensive exercises
    • Supports multiple identical cloned environments for each actor
  • Planning and design of exercise networking
    • Templating engine, allowing for value substitution in addresses, domains, etc.
    • Supports multiple address pool within same layer 2
    • Supports multiple NIC-s per host
    • Avoids address conflicts and overlaps
    • Supports static, dynamic, virtual addressing
  • Hosts inventory: virtual machines, containers and physical devices
  • Enabled describing detailed services, which can be used to perform automatic checks
    • Powerful pattern matching to easily apply services to multiple hosts at once
    • Flexible configuration for individual checks
  • Authentication handled by external SSO via OpenID Connect
  • JSON API, with accompanying Ansible inventory plugin as part of nova.core collection

Roadmap / planned features

  • Rebuild access control for more flexibility
  • UI overhaul for virtual machines/hosts
  • Cluster mode management
  • DNS zones management
  • Credentials management
  • Import/Export of environments


Providentia was created and is maintaned by mromulus.

Thanks to Clarified Security for enabling this work to continue.

Clarified Security logo


This project is available as open source under the terms of the MIT License.

For commercial support and consulting, contact us at


Providentia is a tool to manage cyber-exercise technical knowledge







  • Ruby 67.3%
  • Haml 23.7%
  • JavaScript 3.4%
  • CSS 3.2%
  • HTML 0.9%
  • Dockerfile 0.6%
  • Other 0.9%