Core concepts
Commands
Did no one tell you there would be commands? Spolier alert, there are! Read on to learn about them.
Overview
RedTeamer is accessed by using the redteamer command. On its own, it's a pretty uselss command. That's why it offers subcommands to perform operations that are actually useful.
Available Commands
To view a list of available subcommands, simply run redteamer --help.
__ _ _
/ / | || |
/ / _ __ ___ __| || |_ ___ __ _ _ __ ___ ___ _ __
/ / | '__| / _ \ / _` || __| / _ \ / _` || '_ ` _ \ / _ \| '__|
_ / / | | | __/| (_| || |_ | __/| (_| || | | | | || __/| |
(_)/_/ |_| \___| \__,_| \__| \___| \__,_||_| |_| |_| \___||_|
RedTeamer is a powerful command-line tool for orchestrating red team
security operations and conducting real-world adversary simulations.
š Commercial use requires a professional license.
š Learn more at: https://redteamer.io
USAGE
redteamer [command] [--flags]
EXAMPLES
# View quickstart and page output with less
redteamer explain quickstart | less -R
# Inilize the example module to prepare it for offline use
redteamer init example.rtmod.hcl
# Generate a draft inputs file for the example module
redteamer draft example.rtmod.hcl > inputs.rtval.hcl
# Edit the inputs file, then run the module with it
redteamer run example.rtmod.hcl -f inputs.rtval.hcl
COMMANDS
completion [command] Generate the autocompletion script for the specified shell
explain <topic|path> Show docs for a topic, module, or pack
help [command] Help about any command
GENERATE & VALIDATE
draft <path> Create a draft inputs file for a module
eval [--flags] Evaluate inputs from many sources and print one merged result
format [path|-] [--flags] Format .rtmod.hcl and .rtval.hcl files in a deterministic style
validate [path] [--flags] Validate modules without executing them
RUN & ANALYZE
history [--flags] List past runs; filter by time, tag, or module
init <path> [--flags] Initialize a module or a pack for offline use
output <run|path> [expr] [--flags] Print outputs from a past run (or the last run of a module)
run <path> [--flags] Run a module using the given inputs
serve [command] Start background servers (app, LSP, MCP)
IMPORT AND EXPORT
export <file> [--flags] Create a portable bundle of runs, artifacts, and packs (with dependencies)
import <file> [--flags] Load a bundle of runs, artifacts, and packs into the local environment
inspect [command] Show what a bundle contains
FLAGS
-d --debug Enable debug logging
-h --help Help for redteamer
-v --version Version for redteamer
Tab-Completion
RedTeamer supports tab-completion.
To setup RedTeamer tab-completion in your bash shell, run the following command:
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source <(redteamer completion bash)
To load completions for every new session, execute once:
BASH:
redteamer completion bash > /etc/bash_completion.d/redteamer
You will need to start a new shell for this setup to take effect.
Validate Command
Use the validate command to verify the given modules are syntactically valid.
Validates all modules in a pack to check for syntax errors, missing values, and other issues
USAGE
Ā Ā validate <path>Ā [--flags]Ā Ā
FLAGS
Ā Ā Ā Ā -hĀ --help Help for validate
Ā Ā Ā Ā -pĀ --project Set the project scopeĀ (default)
Example Usage:
āÆ redteamer validate example.rtmod.hcl
Format Command
Use the format command to rewrite given modules to follow our style conventions.
Ā Ā Formats a single module file or all redteamer files in a directory
Ā Ā to follow RedTeamer's standard formatting rules.
Ā Ā
Ā Ā This helps keep your code clean, readable, and consistent.
Ā Ā It supports both individual files and whole directories containing .rtmod.hcl or .rtval files.
USAGE
Ā Ā format <path>Ā [--flags]Ā Ā
FLAGS
Ā Ā Ā Ā -hĀ --help Help for format
Ā Ā Ā Ā -pĀ --project Set the project scopeĀ (default)
Example Usage:
āÆ redteamer format example.rtmod.hcl
Docs Command
Use the docs command to generate and output usage docs.
Ā Ā Manage and explore documentation for packs and modules
USAGE
Ā Ā docsĀ [command]Ā [--flags]Ā Ā
COMMANDS
Ā Ā Ā Ā generate <path> Generate documentation from a pack path.
Ā Ā Ā Ā list List all available documentation files.
Ā Ā Ā Ā show <path> Show a specific document by file path.
FLAGS
Ā Ā Ā Ā -hĀ --help Help for docs
Ā Ā Ā Ā -pĀ --project Set the project scopeĀ (default)
Example Usage:
āÆ redteamer docs show blocks/service
# service block
The service block defines a long-running container process that runs in
the
background for the duration of the run.
## Meta Arguments
Meta arguments are special parameters used to control the behavior of
blocks. Note meta arguments cannot be referenced.
ā¢ count ( number ): Specifies the number of instances to generate.
ā¢ for_each ( map or set ): Defines an iterable collection to loop over.
## Required Arguments
The following arguments are required arguments.
ā¢ image ( string ): The container image to use for running the service.
## Optional Arguments
The following arguments are optional arguments.
ā¢ command ( list of string ): Overrides the default command specified in the
container image.
ā¢ depends_on ( set of reference ): Declares other blocks that this one
depends on. These must run successfully before this block can start.
ā¢ entrypoint ( list of string ): Overrides the default entrypoint specified
in the container image.
ā¢ envs ( map of string ): A map of environment variables to set for the
service. Defaults to variables from the image and current process.
ā¢ host_network ( bool ): Attaches the service container to the host network.
ā¢ privileged ( bool ): Runs the service in privileged mode, inheriting all
permissions of the executing user.
ā¢ when ( bool ): A condition that decides if the block should run. If false,
the block is skipped and default values are returned.
ā¢ workdir ( string ): Specifies the working directory for the service.
Defaults to the image's working directory.
## Nested Blocks
Nested blocks used to control the behavior of parent blocks.
## assert
assert blocks are used to validate values. If the condition is false, the
block fails with the error message.
ā¢ condition ( bool ): A boolean expression that must be true. If false, the
assertion fails.
For example: len(var.password) >= 8 checks that a password is at least 8
characters long.
ā¢ error_msg ( string ): A custom message to show when the assertion fails.
Use this to help users fix the issue.
## health
Defines the service container health check. The system runs this check
inside the container to confirm it is working correctly.
ā¢ command ( string ): The shell command to check if the container is healthy.
Run inside the container.
ā¢ interval ( number ): Time (in seconds) between each health check attempt.
ā¢ retries ( number ): Number of failures allowed before the container is
marked unhealthy.
ā¢ start_period ( number ): Time to wait (in seconds) after the container
starts before running health checks.
ā¢ timeout ( number ): Time limit (in seconds) for the command to finish.
## port
The port block defines the mapping of container ports to host ports, with
optional configuration for host address and protocol.
Note: Mapping to host ports below 1024 requires CAP_NET_ADMIN or root
privileges.
ā¢ container_port ( number ): The port number on the container to be mapped
to the host.
ā¢ host_address ( string ): The specific host IP address to bind to the port
mapping. If not provided, the default is an empty string, which binds to all
network interfaces.
ā¢ host_port ( number ): The port number on the host to map to the specified
container port. If not provided, a random available port on the host will be
used.
ā¢ protocol ( string ): The network protocol for the port mapping, such as
tcp or udp . Defaults to tcp .
## retry
Retry blocks define retry behavior for a block. You can control when to
retry, how many times, how long to wait, and whether to use exponential
backoff.
ā¢ attempts ( number ): The maximum number of times to retry the block.
ā¢ backoff ( bool ): If true, the retry delay will grow exponentially with
each attempt.
ā¢ condition ( bool ): A boolean expression that decides whether to retry. If
this returns true, the block will retry.
ā¢ delay ( number ): How many seconds to wait between retries.
## Example Block
service "example" {
image = ""
command = []
depends_on = null
entrypoint = []
envs = {}
host_network = false
privileged = false
when = true
workdir = ""
}
...
Eval Command
Use the eval command to quicly and convintly evaluate RedTeamer expressions.
Usage:
redteamer eval [flags]
Aliases:
eval, e
Examples:
## Experiment with RedTeamer expressions
redteamer eval 'math::sum([10+2, var.num])' -v num=5
Flags:
-h, --help help for eval
-f, --val-file stringArray Load var values from the given file.
Repeat flag to load more than one value file
-v, --var stringArray Set a var value to be availble to the expression.
Repeat flag to set more than one var value.
Example Usage:
āÆ redteamer eval 'math::sum([10+2, var.num])' -v num=5
17
Run Command
Use the run command to execute the actions defined in the given module
Usage:
redteamer run [flags]
Aliases:
run, r
Examples:
## Run a module file by path
redteamer run path/to/example.rtmod.hcl
## Run a module file by path and set multiple input values
redteamer run path/to/example.rtmod.hcl -v target=10.1.1.1 -v port=8888
## Run a module file by path and load input values from a file
redteamer run path/to/example.rtmod.hcl -f ./example.rtvar
Flags:
-a, --annotation stringToString Associate annotations with this run to provide any contextual data. (default [])
-h, --help help for run
-l, --label stringToString Associate labels with this run for future discoverbilty. (default [])
-p, --project string Define a project for this run to be associated with. (default "default")
-v, --val stringArray Set an input value for one of the module inputs.
Repeat flag to set more than one input value.
-f, --val-file stringArray Load input values from the given file.
Repeat flag to load more than one value file
Example Usage:
āÆ redteamer run example.rtmod.hcl
ā [3.00s] wait.name
ā Waiting for 3s
ā
ā wait.name = {
ā "hours" = 0
ā "minutes" = 0
ā "seconds" = 3
ā }
ā [2.07s] exec.command.ping
ā ping 127.0.0.1 -c 3
ā PING 127.0.0.1 (127.0.0.1) 56(84) bytes of data.
ā 64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.050 ms
ā 64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.032 ms
Install Command
Use the install command to manually install pack by url.
Usage:
redteamer install [flags]
Aliases:
install, i
Examples:
## Install a pack from github
redteamer install github.com/redteamer/tools?ref=v1.0.2
## Install all dependecies for a given local directory
redteamer install ../path/to/metadroid-pack
## Install a pack stored on a http server
redteamer install https://example.com/hfuzz.zip
## Install a pack stored in a S3 bucket (May require preconfigured credentials)
redteamer install s3::https://s3-eu-west-1.amazonaws.com/hooli/hfuzz.zip
## Install a pack stored in a GCS Bucket bucket (May require preconfigured credentials)
redteamer install gcs::https://www.googleapis.com/storage/v1/hooli/hfuzz.zip
Flags:
--force Force reinstallion of pack and any dependecies
--header stringToString Specify headers to append to any http requests (default [])
-h, --help help for install
--insecure Allow insecure http connections
--option stringToString Specify options to append to any requests (default [])
Example Usage:
āÆ redteamer install github.com/redteamer-io/exp
CACHED: git::https://github.com/redteamer-io/exp.git
Get Command
Use the get command to get entities, artifacts, projects, packs, and runs.
Usage:
redteamer get [command]
Aliases:
get, g
Examples:
## Get list of all projects
redteamer get projects
## Get list of installed packs
redteamer get packs
## Get Entities in the acme project
redteamer get entities -p acme
## Get specefic Entity by ID
redteamer get entity be5fe999-7eb5-51f0-9ad8-faefad9d68f7
## Get Artifacts of kind password in the default project
redteamer get artifacts -k password
## Get Runs in the default project
redteamer get runs
Available Commands:
artifacts Get list of artifacts
entities Get list of entities
packs Get list of installed packs
projects Get list of projects
runs List run history
Flags:
-h, --help help for get
Use "redteamer get [command] --help" for more information about a command.
Example Usage
āÆ redteamer get runs
ID MODULE EXECUTED
-- ------ --------
15e19b62-6013-4d39-9a61-a51ef0b5df47 /home/jdoe/demo/test2.rtmod.hcl one day ago
431cbdad-5b19-454a-a6d7-85c20fdb34e6 /home/jdoe/demo/test1.rtmod.hcl 3 days ago
4c4bf921-c9d8-4509-bc17-de3b48a7817b /home/jdoe/demo/test1.rtmod.hcl 2 days ago
e450e0e3-409b-48ef-971a-725f761af852 /home/jdoe/demo/test1.rtmod.hcl 3 days ago
RedTeamer is a CLI tool for building and running red team modules using HCL.
Usage:
redteamer [command]
WORKFLOW COMMANDS:
draft Create a starter input file for a module
init Prepare module or pack dependencies for offline use
replay Re-run a module using inputs from a previous run
run Execute a module with inputs (validates inputs and runs init if needed)
UTILITY COMMANDS:
evaluate Resolve HCL expressions in an inputs file
format Format HCL files to standard layout and style
validate Validate syntax and expressions in a module or pack
HISTORY COMMANDS:
history View past runs with filtering (tags, modules, time)
inspect Show logs, inputs, outputs, and DAG of a specific run
output Get a specific output value from a previous run
TRANSFER COMMANDS:
export Package runs and artifacts into a .tar.gz archive
import Load runs and data from a RedTeamer archive
OTHER COMMANDS:
completion Generate the autocompletion script for the specified shell
explain Show documentation for a module, pack, or built-in topic
help Help about any command
serve Run internal services (e.g., LSP or MCP server)
update Check for and install RedTeamer updates
Flags:
-h, --help Show help for redteamer
--version Print the version number
Use "redteamer [command] --help" for more information about a command.