Clarified Security built tools:

Providentia • Catapult • EXPO

---

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.

Quickstart

To get Providentia up and running with decent defaults you could use a quickstart shell script, which downloads the required Docker compose files, the initial Zitadel SSO configuration and generates minimum required configuration.

Requirements:

• wget or curl for downloading
• docker
• docker compose plugin (version > 2)

curl https://raw.githubusercontent.com/ClarifiedSecurity/Providentia/refs/heads/main/quickstart.sh | sh

The last step of the script asks if you want to run Providentia locally or exposed over the network. If you are testing by yourself, local mode is easier and will expose the application at [https://providentia.localhost]. In network mode, you will be asked the domain suffix - if you pick "demo" here, the application will be accessible at [https://providentia.demo]. This configuration will be stored in .env file, which Docker Compose reads when starting the containers.

Note

If you are using networked mode, ensure that you have DNS records pointing to the machine or /etc/hosts for everyone involved contain the correct entries. Be warned! Changing the mode will break the ZITADEL configuration.

After the setup is complete, you can start use regular docker compose commands to start or stop the ser vices.

To start after the script has completed:

cd providentia && docker compose up

Demo credentials

Zitadel:

• u: zitadel-admin@localhost p: Password1!

Providentia:

On first boot, a sample environment is created for you - "Test exercise" along with users with varied permissions. The setup mimics a typical cyber-defense actor pattern and creates users with varied permissions:

Username	Password	Permissions
providentia.noaccess	Password1!	Cannot login.
providentia.admin	Password1!	Superadmin, has access to everything.
providentia.teadmin	Password1!	Access to Test Exercise as environment administrator (all permissions).
providentia.rt	Password1!	Access to Test Exercise as RT member (can see public machines, can see and alter RT VMs).
providentia.dev	Password1!	Access to Test Exercise as GT member (can see public machines, can see and alter infra and bt VMs).
providentia.bt	Password1!	Access to Test Exercise as BT member (can see public machines, can see BT VMs).
providentia.personal1	Password1!	Can login, cannot see any environments, can create personal environments.
providentia.personal2	Password1!	Can login, cannot see any environments, can create personal environments.
providentia.personal3	Password1!	Can login, cannot see any environments, can create personal environments.

Deploying

Caution

The quickstart setup above set up is not suitable for production use.

It is recommended to use the providentia Ansible role at nova.core to deploy Providentia for production environments.

Providentia requires certain external resources to be functional:

• OpenID Connect provider for authentication, for example Zitadel or Keycloak
• PostgreSQL database - included in the Ansible role, but can be replaced with an external instance
• A reverse proxy, Caddy used in examples

Development

Additional requirements:

• make
• python3

Important

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.

First steps:

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

2. Build the container images with make build

3. Run the app with make start

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

TL;DR:

git clone https://github.com/ClarifiedSecurity/Providentia.git
cd Providentia
make config
make build
make start

After bootup, Providentia can be accessed at http://providentia.localhost and Zitadel admin UI will be running at http://zitadel.localhost. The demo credentials can be used to log in.

Features

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

Credits

Providentia was created and is maintaned by mromulus.

Thanks to Clarified Security for enabling this work to continue.

License

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

For commercial support and consulting, contact us at info@clarifiedsecurity.com