phēnix Apps

A collection of standard applications and Scorch components designed for use with phēnix.

📖 Overview

This repository contains the source code for official phēnix apps. These apps adhere to the phēnix App Contract:

1. Accept the stage as a single command-line argument.
2. Accept the experiment JSON over STDIN.
3. Return the updated experiment JSON over STDOUT.
4. Write structured JSON logs to stderr (or the file specified by PHENIX_LOG_FILE).

🚀 Getting Started

Prerequisites

• Python 3.12+
• Go 1.24+ (for Go-based apps)
• make

Installation

To install the Python apps and development dependencies in editable mode:

make install-dev

🛠️ Development

We use a Makefile to standardize development tasks.

# Development
make all         # Run all tools (format, lint, and test)
make check       # Run linters without fixing (for CI)
make format      # Format code (golangci-lint, ruff)
make lint        # Lint code and fix issues (golangci-lint, ruff, etc.)
make test        # Run unit tests

# Installation & Cleanup
make install-dev # Install development dependencies and tools
make install     # Install runtime dependencies
make clean       # Clean build artifacts

Apps

Application	Description
caldera	Runs operations and retrieves reports from a Caldera C2 server.
helics	Configures and manages HELICS (Hierarchical Engine for Large-scale Infrastructure Co-Simulation) federates.
mirror	Configures cluster-wide packet mirroring to a target node using GRE or ERSPAN tunnels.
otsim	Generates configuration files for OT-sim simulations.
protonuke	Injects command-line arguments for the protonuke agent service.
scale	Deploys large-scale infrastructure and applications using a plugin architecture.
sceptre	An integration application for the SCEPTRE emulation platform.
scorch	Orchestrates sequences of actions (components) for automated testing and validation.
wind_turbine	(Deprecated) Use the wind_turbine plugin within the scale app instead.
wireguard	Configures WireGuard VPN tunnels between nodes.

Scorch components

Component	Description
art	Executes adversary emulation techniques using the Atomic Red Team (ART) framework.
caldera	Runs operations and retrieves reports from a Caldera C2 server.
cc	Executes arbitrary shell commands on nodes via minimega's command and control.
collector	Collects files from specified nodes for post-experiment analysis.
disruption	Simulates network disruptions like Denial of Service (DoS) attacks.
ettercap	Runs the Ettercap suite for man-in-the-middle attacks.
hoststats	Collects host performance statistics (CPU, memory, etc.).
iperf	Measures network performance between nodes using iperf.
kafka	Interacts with Apache Kafka topics.
mm	Executes arbitrary minimega commands.
opcexport	Exports data from an OPC-UA server.
pcap	Manages network packet captures (.pcap files) across the experiment.
pipe	Implements minimega 'pipe' API.
providerdata	Collects and verifies data from pybennu providers, such as the RTDS or OPALRT.
qos	Applies Quality of Service (QoS) rules (e.g., latency, packet loss) to interfaces.
rtds	Interacts with RTDS (Real Time Digital Simulator) systems.
snort	Runs the Snort Intrusion Detection System on specified interfaces.
tcpdump	Captures network traffic using tcpdump.
trafficgen	Generates network traffic between specified source and destination nodes.
vmstats	Collects detailed VM statistics from minimega.