Guides

Serve Modules over REST

Expose your redteamer modules as a local REST API so other tools, CI pipelines, and internal UIs can call them programmatically.

Overview

Serving modules over HTTP lets you call redteamer without the CLI. This is useful for automation and integrations. Start the server like this:

rt serve api --listen "127.0.0.1:8080"

By default the API binds to 127.0.0.1 on port 8080. Every available module is exposed as its own endpoint and a live OpenAPI document is generated describing each modules inputs and outputs.

What the server provides

An HTTP endpoint for each module
A live OpenAPI 3.1 document that describes inputs and outputs
Example request and response schemas that clients can use to build SDKs or test tooling

You can fetch the OpenAPI doc:

GET /v1/openapi.json

The resulting spec includes typed request and response schemas and example payloads for each module.

Authentication and operator identity

The redteamer HTTP server does not provide built in authentication or access control. Deploy it behind an API gateway or reverse proxy that enforces your security policy. The gateway should forward the caller identity with the X-ID header:

X-ID: user@example.com

The server records that header in audit trails to attribute runs to operators.

Without a gateway the server treats requests as local and anonymous. For production use place the API behind a gateway that enforces authentication, authorization, and rate limits.

Example request

Start a run by posting to the module run endpoint:

curl -X POST http://127.0.0.1:8080/v1/modules/evilcorp/utils/s3-enum/run \
  -H "Content-Type: application/json" \
  -H "X-ID: alice@redteam.local" \
  -d '{
    "domain": "evilcorp.com"
  }'

Typical response:

{
  "run_id": "2f91a0",
  "status": "running",
  "created_at": "2025-02-17T14:01:32Z"
}

Use the OpenAPI spec to discover additional endpoints for logs, outputs, and run status.

Best practices

Run the server on localhost when you need local integrations only.
Put the server behind an authenticated gateway for shared environments.
Forward a stable X-ID value so audit logs can attribute work to operators.
Limit network exposure and use mutual TLS or your gateway of choice for secure deployments.

Example workflow

Start the server:
```
rt serve api --listen "127.0.0.1:8080"
```

Inspect the OpenAPI document:

curl http://127.0.0.1:8080/v1/openapi.json | jq .

Launch a run:

curl -X POST http://127.0.0.1:8080/v1/modules/evilcorp/utils/s3-enum/run \
  -H "Content-Type: application/json" \
  -H "X-ID: alice@redteam.local" \
  -d '{"domain":"evilcorp.com"}'

Retrieve outputs or trace using endpoints documented in the OpenAPI spec.

Troubleshooting

If the OpenAPI endpoint is empty check that the server discovered modules and that the module catalog is loaded.
If runs show up as anonymous ensure your gateway is forwarding X-ID correctly.
If you cannot bind to the requested address check for port conflicts or firewall rules.