README
¶
SimRun
SimRun is an Attack Simulation Platform (ASP) for detection testing. It detonates attack simulations and verifies that the security alerts you expect fire in your SIEM (currently only Elastic Security is supported).
It ships as a single Go binary serving a REST API + WebSocket interface backed by PostgreSQL, with an embedded SvelteKit frontend.
Getting Started
Prerequisites
- mise — manages the Go 1.25 and Node 22 toolchains (or install them yourself)
- PostgreSQL
Build
mise build # builds the SvelteKit frontend and the simrun binary into dist/simrun
Run
simrun requires a PostgreSQL database; schema migrations run automatically on startup.
export SR_DATABASE_URL="postgres://user:pass@localhost:5432/simrun?sslmode=disable"
./dist/simrun
The UI and API are then served on http://localhost:8080.
Authentication is optional. Without
SR_GOOGLE_CLIENT_ID/SR_GOOGLE_CLIENT_SECRET, login is disabled and the app runs unauthenticated
Configuration
Deploy-time configuration is read from environment variables — the only SR_* env
surface. Everything else (connectors, secrets, packs, schedules, scenarios, app
defaults) lives in the database and is managed through the web UI.
| Variable | Required | Default | Description |
|---|---|---|---|
SR_DATABASE_URL |
yes | — | PostgreSQL connection string |
SR_WEB_PORT |
no | 8080 |
HTTP listen port |
SR_DATA_DIR |
no | ~/.simrun |
Local data dir (encryption key, SSH logs) |
SR_ENCRYPTION_KEY_FILE |
no | $SR_DATA_DIR/encryption.key |
Key file for encrypting stored secrets |
SR_DEBUG |
no | off | Verbose logging when set to a non-zero value |
SR_WEB_URL |
no | — | External base URL (used for OAuth redirects) |
SR_GOOGLE_CLIENT_ID / SR_GOOGLE_CLIENT_SECRET |
no | — | Google OAuth credentials (enables login) |
SR_GOOGLE_ALLOWED_DOMAIN |
no | — | Restrict OAuth login to a Google Workspace domain |
SR_AUTH_SESSION_TTL_HOURS |
no | 168 |
Session lifetime in hours |
Run with Docker
docker build -t simrun .
docker run -p 8080:8080 \
-e SR_DATABASE_URL="postgres://..." \
-v simrun-data:/home/nonroot/.simrun \
simrun
The image bundles the aws, gcloud, and az CLIs used by detonators. Persist
SR_DATA_DIR (the volume above) so the secret-encryption key survives restarts.
Architecture
A single Go binary handles:
- Simulation detonation and orchestration
- Alert matching and verification
- Log collection from security platforms
- Scenario parsing and execution
Simulation Packs
Simulations are distributed as external packs, installed and managed via the web UI:
- simrun-base-pack — custom simulations (AWS, Azure, GCP)
- simrun-stratus-pack — Stratus Red Team simulations
Concepts
Detonators
A detonator describes how and where an attack technique is executed.
- Simrun detonator — runs a simulation pack (Terraform-based; packs can themselves execute locally or over SSH)
- AWS CLI detonator — runs AWS CLI commands
Injectors
An injector is an alternative to detonators: instead of executing the end-to-end attack it takes a generated log message and injects it directly into the SIEM. This covers cases where end-to-end simulation isn't feasible but you still want to confirm the detection is operational.
- Elastic Injector
Alert Matchers
An alert matcher is a platform-specific integration that checks whether an expected alert was triggered.
- Elastic Security alerts
- Datadog security signals
Collectors
A collector retrieves logs from security platforms after detonation for analysis and rule generation.
- Elastic Collector — collects related logs from Elasticsearch by execution ID or user-agent correlation
Detonation and Alert Correlation
Each detonation is assigned a UUID, reflected in the detonation where possible and used to ensure the matched alert corresponds exactly to that detonation. If the detonator cannot reflect the UUID, the matcher can correlate using indicators the user provides (static indicators) or terraform output (dynamic indicators).
Simulations
A simulation is a reusable module describing how to perform a specific attack. Simulations are distributed as packs and installed via the web UI.
Development
mise run build-frontend # build just the SvelteKit frontend
go test ./... # run the test suite
mise run lint # run golangci-lint
go generate ./... # regenerate mocks (mockery)
mise run parser # regenerate parser from JSON schemas
Contributing
Issues and pull requests are welcome.
License
Licensed under the Apache License 2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
simrun
command
Command simrun is the ASP server: a web server with an embedded SvelteKit frontend that runs attack simulations and verifies expected security alerts.
|
Command simrun is the ASP server: a web server with an embedded SvelteKit frontend that runs attack simulations and verifies expected security alerts. |
|
internal
|
|
|
cloud/aws
Package awsauth provides AWS cross-account role assumption for simrun.
|
Package awsauth provides AWS cross-account role assumption for simrun. |
|
cloud/azure
Package azureauth provides Azure Workload Identity Federation for simrun.
|
Package azureauth provides Azure Workload Identity Federation for simrun. |
|
cloud/gcp
Package gcpauth provides GCP Workload Identity Federation for simrun.
|
Package gcpauth provides GCP Workload Identity Federation for simrun. |
|
cloud/k8s
Package k8sconfig generates kubeconfig files for Kubernetes clusters using CSP CLI tools (aws, gcloud, az).
|
Package k8sconfig generates kubeconfig files for Kubernetes clusters using CSP CLI tools (aws, gcloud, az). |
|
collectors
Package collectors gathers related logs from a SIEM after a simulation runs.
|
Package collectors gathers related logs from a SIEM after a simulation runs. |
|
config
Package config holds simrun's configuration types: env-only Bootstrap, DB-backed AppConfig, and the in-memory pack shapes used by the parser and runner.
|
Package config holds simrun's configuration types: env-only Bootstrap, DB-backed AppConfig, and the in-memory pack shapes used by the parser and runner. |
|
connectors/elastic
Package elastic is a minimal client for the Elastic Security detection-engine API, used to validate Elastic connectors.
|
Package elastic is a minimal client for the Elastic Security detection-engine API, used to validate Elastic connectors. |
|
credentials
Package credentials resolves per-connector credentials into the environment- variable maps consumed by detonators and CLI tools.
|
Package credentials resolves per-connector credentials into the environment- variable maps consumed by detonators and CLI tools. |
|
crypto
Package crypto provides AES-256-GCM encryption for secret values stored in the database.
|
Package crypto provides AES-256-GCM encryption for secret values stored in the database. |
|
db
Package db is the PostgreSQL persistence layer (pgx), running embedded migrations on startup.
|
Package db is the PostgreSQL persistence layer (pgx), running embedded migrations on startup. |
|
detonators
Package detonators executes attack simulations, via simulation packs or the AWS CLI.
|
Package detonators executes attack simulations, via simulation packs or the AWS CLI. |
|
envutil
Package envutil provides helpers for threaded environment variable management.
|
Package envutil provides helpers for threaded environment variable management. |
|
injectors
Package injectors writes log documents directly into a SIEM, bypassing detonation.
|
Package injectors writes log documents directly into a SIEM, bypassing detonation. |
|
matchers
Package matchers verifies that the security alerts expected by a scenario were generated after a simulation.
|
Package matchers verifies that the security alerts expected by a scenario were generated after a simulation. |
|
matchers/datadog
Package datadog matches expected Datadog security signals.
|
Package datadog matches expected Datadog security signals. |
|
matchers/elastic
Package elastic matches expected Elastic Security detection alerts.
|
Package elastic matches expected Elastic Security detection alerts. |
|
packs/executor
Package executor handles pack protocol communication using PackRunners.
|
Package executor handles pack protocol communication using PackRunners. |
|
packs/locks
Package locks provides a process-global keyed mutex used to serialize mutating filesystem operations on a single pack's cache directory.
|
Package locks provides a process-global keyed mutex used to serialize mutating filesystem operations on a single pack's cache directory. |
|
packs/resolver
Package resolver provides pack binary resolution and caching.
|
Package resolver provides pack binary resolution and caching. |
|
packs/runner
Package runner builds and runs pack binaries (local, uploaded, or remote) behind a common interface.
|
Package runner builds and runs pack binaries (local, uploaded, or remote) behind a common interface. |
|
packs/terraform
Package terraform provides programmatic Terraform execution using terraform-exec.
|
Package terraform provides programmatic Terraform execution using terraform-exec. |
|
parser
Package parser turns YAML scenario files into Scenario objects.
|
Package parser turns YAML scenario files into Scenario objects. |
|
results
Package results defines the shared run and scenario result types and a parallel scenario executor.
|
Package results defines the shared run and scenario result types and a parallel scenario executor. |
|
runner
Package runner is the scenario execution engine: it detonates or injects, polls for the expected alerts, and optionally collects related logs.
|
Package runner is the scenario execution engine: it detonates or injects, polls for the expected alerts, and optionally collects related logs. |
|
testutil/fakes
Package fakes provides in-memory implementations of every db.*Store interface.
|
Package fakes provides in-memory implementations of every db.*Store interface. |
|
testutil/testserver
Package testserver provides a one-line setup for HTTP-handler tests.
|
Package testserver provides a one-line setup for HTTP-handler tests. |
|
version
Package version holds build version information for simrun.
|
Package version holds build version information for simrun. |
|
web
Package web implements the REST API, WebSocket hub, and embedded-frontend HTTP server.
|
Package web implements the REST API, WebSocket hub, and embedded-frontend HTTP server. |
|
web/auth
Package auth provides Google OAuth login and session-cookie middleware for the web API.
|
Package auth provides Google OAuth login and session-cookie middleware for the web API. |
|
Package pack is the SDK for building simrun simulation packs — standalone binaries that simrun invokes over a JSON stdin/stdout protocol to detonate attacks and report results.
|
Package pack is the SDK for building simrun simulation packs — standalone binaries that simrun invokes over a JSON stdin/stdout protocol to detonate attacks and report results. |
|
aws
Package aws provides AWS SDK helpers for simulation packs.
|
Package aws provides AWS SDK helpers for simulation packs. |
|
azure
Package azure provides Azure SDK helpers for simulation packs.
|
Package azure provides Azure SDK helpers for simulation packs. |
|
gcp
Package gcp provides GCP SDK helpers for simulation packs.
|
Package gcp provides GCP SDK helpers for simulation packs. |