CalderaAgent

A lightweight Go implant for MITRE Caldera purple‑team adversary emulation. The agent beacons to a Caldera server, pulls task instructions, executes them in an isolated process group (so EDR kill‑tree actions don’t terminate the agent), and returns rich telemetry so blue teams can measure prevention vs detection.

---

Features

Capability	Notes
Detached execution	Uses setsid (Linux) so child process termination doesn’t propagate to the agent.
Timeout watchdog	Each instruction honours the timeout field and returns exit‑code 124 if exceeded.
Blocked‑by‑EDR flag	If the child receives SIGKILL, the agent reports status = 1 for accurate SOC scoring.
Verbose debugging	Run with CG_DEBUG=1 to print beacon traffic and execution traces.

---

Quick start

# clone your fork
git clone https://github.com/Bhanunamikaze/CalderaAgent.git
cd CalderaAgent

# build for the local platform
CGO_ENABLED=0 go build -o agent CalderaAgent.go

# run (replace URL with your Caldera server)
./caldera-linux-agent -server https://caldera_server:8443 -insecure -debug

Cross‑compile examples

# Linux x64 (default)
go build -o agent-linux CalderaAgent.go

# Windows x64
GOOS=windows GOARCH=amd64 go build -o agent.exe CalderaAgent.go

---

Usage

Usage: ./agent <C2 URL>

Once launched, the agent will beacon every sleep seconds, execute abilities, and post results back to /beacon.

Linux

./bin/caldera-linux-agent -server https://caldera_server:8443 -insecure -debug

Arguments:

• -server <url> : CALDERA server URL.
• -insecure : Disables TLS certificate verification. Use this only when you are intentionally connecting to a server with an untrusted or self-signed certificate.
• -debug : Enables verbose debug logging to stdout.
• --fresh : Ignores any persisted paw state and registers as a new CALDERA agent identity.

Debug can also be enabled with:

CG_DEBUG=1 ./bin/caldera-linux-agent -server https://caldera_server:8443 -insecure

Windows

.\bin\caldera-agent-windows.exe -server https://caldera_server:8443 -insecure -debug

Arguments:

• -server <url> : CALDERA server URL.
• -insecure : Disables TLS certificate verification.
• -debug : Enables verbose debug logging.

---

Telemetry schema

Field	Description
exit_code	Native process exit code (or 124 on timeout).
status	0 = executed / runtime error, 1 = blocked by EDR (SIGKILL).
pid	Child PID for reference in EDR logs.

---

Linux Agent Support

Supported

• HTTP beaconing to /beacon
• Payload download from /file/download
• Result posting back to /beacon
• sh executor
• payload deletion via delete_payload
• bounded stdout/stderr capture
• transport timeouts and response cleanup
• process-group kill on timeout
• paw persistence across restarts
• --fresh identity reset
• pending-result replay after transient communication loss
• in-flight instruction journaling
• instruction-level sleep
• watchdog handling
• deferred deadman handling on signal/watchdog termination

Persistence behavior

Linux state is stored in the first writable location from:

1. $HOME/.caldera-agent/
2. /tmp/.caldera-agent/

Files used:

• paw.json
• pending-results.json
• inflight.json

Windows Agent Support

Supported

• HTTP beaconing to /beacon
• Payload download from /file/download
• Result posting back to /beacon
• executor selection for:
  • cmd
  • psh
  • pwsh
• payload deletion via delete_payload
• debug logging via -debug

License

This project is released under the MIT License. See LICENSE for full text.