Remote API

AttackMate can execute commands and playbooks on a remote AttackMate instance. This is useful when the tools required by a playbook, such as Metasploit, Sliver, browsers, or network access to a target environment, are available on another host.

The remote setup uses two components:

attackmate-client offers a CLI and a python library to execute commands and playbooks on a remote AttackMate server. It is only required on the client when you want to use the Remote API on an attackmate-api-server.

The attackmate-ansible role can install and configure both sides.

Requirements

A working remote setup needs at least:

  • AttackMate installed on the server.

  • attackmate-api-server installed and running on the server.

  • attackmate-client installed on the client, to access the remote API.

  • The server TLS certificate copied to the client.

  • A valid remote_config entry on the client, or provided as cli argument to attackmate-client.

  • Any tools used by the remote playbook installed on the server, for example msfrpcd for Metasploit commands.

If you installed Attackmate on the client, it is not recommended to install attackmate-client, as it will already have pulled that in as a dependency.

You can install just the attackmate-client, if all you want to do on the client is to send remote commands and playbooks to the attackmate-api-server via CLI or the python library.

Architecture

When a remote playbook uses cmd: execute_playbook, the referenced playbook_path is read on the client machine. The client then sends the playbook YAML content to the API server.

The commands inside that submitted playbook run on the server. Therefore paths inside the submitted playbook, such as payload paths, temporary files, local uploads, or tool configuration, are resolved on the server.

Sample Config

Save this as /etc/attackmate.yml on the client:

msf_config:
  server: localhost
  password: hackerman

cmd_config:
  command_delay: 2

remote_config:
  attackmate-server:
    url: "https://10.0.0.5:8445"
    username: admin
    password: securepassword
    cafile: "/etc/ssl/certs/attackmate.pem"

The cafile must point to the certificate used by the API server. If the certificate is missing or does not match the server, HTTPS verification will fail.

First Run

Create a small local wrapper playbook on the client:

commands:
  - type: remote
    cmd: execute_playbook
    connection: attackmate-server
    playbook_path: examples/remote_put.yml

Run it with:

uv run attackm8 --debug remote_wrapper.yml

The local attackmate should log in to the remote API server, send the referenced playbook, and print the remote execution result.

Testing The API Server

Check that the API service is reachable:

curl -k https://10.0.0.5:8445/

Metasploit

If a playbook uses Metasploit commands, msfrpcd must be running on the server and the AttackMate server configuration must match it.

Example:

msf_config:
  server: localhost
  port: 55553
  password: hackerman
  ssl: true

A common symptom of a wrong Metasploit configuration, or msfrpcd not running, is:

2026-05-20 11:01:37 INFO     | Login successful for 'admin' at https://192.168.0.30:8445. Token stored.
2026-05-20 11:02:37 ERROR    | Request Error (POST https://192.168.0.30:8445/playbooks/execute/yaml): The read operation timed out

Troubleshooting

The read operation timed out

The client waited longer than its configured HTTP timeout. This can happen when the remote playbook is still running, waiting for a session, or stuck in a tool such as Metasploit. Check the server logs and any AttackMate playbook logs.

You can also increase the timeout period of attackmate-client by changing DEFAULT_TIMEOUT in /usr/local/share/attackmate/.venv/lib/python3.12/site-packages/attackmate_client/attackmate_client.py

Server Logs

If file logging is enabled for API playbook runs, inspect the configured log directory, for example:

tail -f /var/log/attackmate-api/*_output.log