Leonidas Framework Documentation

Leonidas is a framework for executing attacker actions in the cloud. It uses a YAML-based format to define cloud attacker Tactics, Techniques, and Procedures (TTPs) along with their associated detection properties.

These YAML definitions can be compiled into three distinct outputs:

1. A web API: Exposes each test case as an individual endpoint.
2. Sigma rules: For detection engineering.
3. Documentation: For visualizing the defined TTPs.

Leonidas supports both AWS environments and Kubernetes environments.

The permissions field is mandatory and defines the access required for the test case.

AWS

List individual IAM permissions required (e.g., secretsmanager:GetSecretValue). Do not use managed policy names.

Kubernetes

List items following the Kubernetes RBAC rule format. Each item must include a namespaced boolean.

permissions:
  - namespaced: true
    apiGroups: [""]
    resources:
      - serviceaccounts
    verbs:
      - create

If no permissions are required for a Kubernetes test case, use an empty block:

permissions:
  - namespaced: true
    apiGroups: [""]
    resources: [""]
    verbs: [""]

Leonidas generates a JSON log entry for every executed test case. The structure of this entry varies slightly depending on whether you are using the AWS or Kubernetes platform, but both follow a core pattern of request and response blocks.

Core Fields

• request:
  • usecase: The specific test case executed.
  • args: Parameters passed to the request.
  • timestamp: Execution time (UTC).
  • identity (AWS only): The identity block used for the test case.
• response:
  • Contains the result of the execution. In AWS, this is the contents of the result variable. In Kubernetes, this includes the shell command, stdout, stderr, and exit_code.

Executors define how a test case is run.

sh

Used for standalone CLI execution and Kubernetes test cases. The code field is a multi-line string containing CLI commands. It supports Jinja2 templating (e.g., {{ variable_name }}) using values from input_arguments.

leonidas_aws

Used to embed Python attack logic into the Leonidas web API. Requires:

• implemented: Boolean (set to True to include in API generation).
• clients: A list of boto3 client names (e.g., ['iam', 's3']).
• code: A multi-line string containing the Python code to be embedded as an API endpoint.

leonidas_kube

Used to signal that a test case should be embedded in the web API. It relies on the sh executor for the actual logic (e.g., kubectl commands).

The input_arguments field is a YAML dictionary of arguments required for execution. These are exposed as HTTP POST parameters to the API and as variables within leonidas_aws executors.

Each argument requires:

• description: A text explanation of the parameter.
• type: Supported types are str, int, and file.
• value: A default value.

Special Case: file type If the type is file, the argument must be named custom_yaml. Files can be uploaded via Content-Type: multipart/form-data or specified as YAML in the definition. For Kubernetes, the file is saved to /tmp/custom.yml and used with kubectl -f apply.

input_arguments:
  custom_yaml:
    description: |
      YAML manifest for the pod - leave this empty to use the default spec
    type: file
    value: 
      apiVersion: v1
      kind: Pod
      # ... rest of manifest

To generate documentation from your definitions, use the generator to produce Markdown files in output/docs.

To create a prettified HTML version of the documentation using mkdocs:

1. Generate the markdown files.
2. Navigate to the output directory.
3. Run mkdocs build to create an HTML site in output/site.
4. Alternatively, run mkdocs serve to view the documentation locally.

# Generate markdown
poetry run ./generator.py docs

# Build HTML site
cd ../output
mkdocs build

# Or serve locally
mkdocs serve

Leonidas in Kubernetes uses a streaming logging sidecar pattern. The primary container logs execution events to stdout in JSON format, while the Flask runtime output is handled by a sidecar container.

Retrieve JSON execution logs

To get the pure JSON logs for test executions, use the following command. This is the preferred method for retrieving execution data:

kubectl logs -l app=leonidas -f

Retrieve Flask runtime logs

To debug the Flask server itself (e.g., to see HTTP requests or startup info), you must target the log-sidecar container:

kubectl logs -l app=leonidas -c log-sidecar -f

# Get JSON execution logs
kubectl logs -l app=leonidas -f

# Get Flask runtime logs for debugging
kubectl logs -l app=leonidas -c log-sidecar -f

For development, you can build and run the Leonidas Python API on your local machine. The API will listen at http://127.0.0.1:5000 and use your default AWS (~/.aws/config) or Kubernetes credentials.

Steps

1. cd generator
2. poetry install
3. poetry run ./generator.py generate-aws-api and/or generate-kube-api
4. cd ../output/leonidas
5. poetry install
6. poetry run python leonidas.py

Authentication

While it defaults to local profiles, you can override credentials by supplying a role ARN to assume, access keys, JWT tokens, or TLS client certificates in your requests.

To build documentation or Sigma rules from your definitions, you must install the generator locally using poetry. Navigate to the generator directory and run the install command.

cd generator
poetry install

Before running Leo, you must generate a caseconfig.yml file containing the test case definitions.

1. Navigate to the generator directory and run the generator script for Leo: poetry run python generator.py leo.
2. Copy the generated configuration to the Leo directory: cp ./output/caseconfig/caseconfig.yml ./leo.
3. Edit the caseconfig.yml file located in ./leo to configure the following:
   • URL: The target URL.
   • API gateway API key: Your authentication key.
   • Test case management: You can modify, reorder, or remove test cases as needed.

cd generator && poetry run python generator.py leo
cp ./output/caseconfig/caseconfig.yml ./leo
# Then edit ./leo/caseconfig.yml