Overview

This document provides a high-level overview for developers interested in understanding the project structure and contribution process.

Purpose

This project facilitates the creation, execution, and log collection of automated attack simulations within a defined virtual environment.

Project Structure

The codebase is generally organized as follows:

  • ansible/: Contains Ansible playbooks defining the scenario setup and the attack playbooks.

  • docs/: Contains the Sphinx documentation source files.

  • scripts/: Contains helper scripts

  • packer/: Contains Packer templates (e.g., .pkr.hcl or .json files) and associated scripts used to build the base virtual machine images for the simulation environment components (e.g., attacker, victim, server machines).

  • terragrunt/: Contains Terragrunt configuration files (terragrunt.hcl) used to orchestrate the deployment and management of the underlying infrastructure (virtual machines, networks, etc.).

Getting Started with Development

  1. Prerequisites: Ensure you have the necessary base software installed, such as OpenStack, OpenTofu, Ansible, Terragrunt (see Requirements)

  2. Setup: Clone the repository and follow the instructions in the Installation section to build the base environment

Contributing

Contributions to enhance scenarios, improve tooling, or fix bugs are welcome, following standard Git practices:

  1. Fork the repository.

  2. Create a descriptive feature branch (e.g., feat/add-new-scenario or fix/resolve-ssh-issue).

  3. Implement your changes, adhering to existing code style.

  4. Test your changes thoroughly.

  5. Update documentation (in docs/) if necessary.

  6. Submit a Pull Request against the main branch for review.