Merge pull request #252 from ait-testbed/main

up version in development

Author: thorinaboenke

README.md

@@ -1,6 +1,5 @@
 AttackMate <img alt="Logo" src="/images/AttackMate_logo_no_logo.png" align="right" height="90">
 ==========
-[![Build Status](https://aecidjenkins.ait.ac.at/buildStatus/icon?job=AECID%2FAECID%2Fattackmate%2Fmain)]( "https://aecidjenkins.ait.ac.at/job/AECID/job/AECID/job/attackmate/job/main/")
 
 AttackMate is a tool to automate cyber attack scenarios that supports scripting of attack techniques across all phases of the Cyber Kill Chain. AttackMate's design principles aim to integrate with penetration testing and attack emulation frameworks such as Metasploit and Sliver Framework and enables simple execution of commands via shell or ssh. For example, AttackMate enables to execute Metasploit modules or generate payloads and run commands in Metasploit sessions. Moreover, it is able to generate Sliver implants, automatize Sliver to send C2 commands, and configure and compile LD_PRELOAD-rootkits. AttackMate also offers a simple interface to automate shell or ssh interaction, run commands in background mode, transfer files via sftp, and start http clients or servers. All attack steps may be scheduled, chained, and repeatedly executed using a simple configuration file that supports variable declarations and conditional workflows.
 

create_hashes.py

@@ -20,13 +20,13 @@ the configuration is used as the default.
 .. code-block:: yaml
 
   remote_config:
-    remote_server:
-      url: "https://10.0.0.5:5000"
+    attackmate-server:
+      url: "https://10.0.0.5:8445"
       username: admin
       password: securepassword
       cafile: "/path/to/cert.pem"
-    another_server:
-      url: "https://10.0.0.6:5000"
+    another-server:
+      url: "https://10.0.0.6:8445"
       username: user
       password: anotherpassword
       cafile: "/path/to/another_cert.pem"
@@ -38,15 +38,15 @@ default connection is used when none is specified:
 .. code-block:: yaml
 
   commands:
-    # Executed on 'another_server'
+    # Executed on 'another-server'
     - type: remote
-      connection: another_server
+      connection: another-server
       cmd: execute_command
       remote_command:
         type: shell
         cmd: "whoami"
 
-    # Executed on 'remote_server' (defaults to first remote_config entry))
+    # Executed on 'attackmate-server' (defaults to first remote_config entry))
     - type: remote
       cmd: execute_playbook
       playbook_path: path/to/playbook.yml

docs/source/configuration/remote_config.rst

@@ -22,6 +22,7 @@ Welcome to AttackMate's documentation!
    preparation/index
    configuration/index
    basic
+   remote_api_intro
 
 .. toctree::
    :maxdepth: 4

docs/source/index.rst

@@ -0,0 +1,156 @@
+.. _remote_api_intro:
+
+==========
+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-api-server <https://github.com/ait-testbed/attackmate-api-server>`__:
+  runs on the remote AttackMate host and exposes an HTTPS API.
+* `attackmate-client <https://github.com/ait-testbed/attackmate-client>`__:
+  runs on the local/client host and sends commands or playbooks to the API
+  server.
+
+`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 <https://github.com/ait-testbed/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:
+
+.. code-block:: yaml
+
+    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:
+
+.. code-block:: yaml
+
+    commands:
+      - type: remote
+        cmd: execute_playbook
+        connection: attackmate-server
+        playbook_path: examples/remote_put.yml
+
+Run it with:
+
+.. code-block:: console
+
+    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:
+
+.. code-block:: console
+
+    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:
+
+.. code-block:: yaml
+
+    msf_config:
+      server: localhost
+      port: 55553
+      password: hackerman
+      ssl: true
+
+A common symptom of a wrong Metasploit configuration, or msfrpcd not running, is:
+
+.. code-block:: text
+
+    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:
+
+.. code-block:: console
+
+    tail -f /var/log/attackmate-api/*_output.log

docs/source/remote_api_intro.rst

@@ -25,9 +25,9 @@ dependencies = [
     "playwright",
     "argon2-cffi",
     "uvicorn",
-    "dotenv",
+    "python-dotenv>=1.1.0",
     "passlib",
-    "python-multipart",
+    "python-multipart>=0.0.32",
     "attackmate-client>=0.1.2",
 ]
 dynamic = ["version"]

pyproject.toml

@@ -8,7 +8,7 @@
 __license__ = 'GPLv3'
 __maintainer__ = 'Wolfgang Hotwagner, Max Landauer, Markus Wurzenberger, Florian Skopik'
 __status__ = 'Production'
-__version__ = '1.0.1'
+__version__ = '1.0.2'
 __version_string__ = (
     f'(Austrian Institute of Technology)\t'
     f'{__website__}\tVersion: {__version__}')