From aec24f2f2ea36d1cb54b6359d39e4272249caf92 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Thu, 12 Mar 2026 16:03:53 +0100 Subject: [PATCH 01/10] add more errors to troubleshooting section --- docs/source/basic.rst | 2 + docs/source/playbook/troubleshooting.rst | 97 ++++++++++++++++++++++++ 2 files changed, 99 insertions(+) diff --git a/docs/source/basic.rst b/docs/source/basic.rst index a3b96ebb..111e1b73 100644 --- a/docs/source/basic.rst +++ b/docs/source/basic.rst @@ -1,3 +1,5 @@ +.. _basic-usage: + =========== Basic Usage =========== diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index c940df89..6d827a1f 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -87,6 +87,49 @@ the ``cmd`` field is missing from a ``shell`` command. ---- +.. _error-commands-not-a-list: + +Commands Not Formatted as a List +--------------------------------- + +**Symptom** + +.. code-block:: text + + ERROR | A Validation error occured when parsing playbook file playbooks/example.yml + ERROR | Traceback (most recent call last): + ... + pydantic_core._pydantic_core.ValidationError: 1 validation error for Playbook + commands + Input should be a valid list [type=list_type, input_value={'type': 'shell', + 'cmd': 'whoami'}, input_type=dict] + +**Cause** + +The ``commands`` field in the playbook is not formatted as a YAML list. +A command was defined as a plain mapping instead of a list entry. + +**Solution** + +Each command must be a list item, prefixed with ``-``: + +.. code-block:: yaml + + # Wrong — commands is a plain mapping: + commands: + type: shell + cmd: whoami + + # Correct — commands is a list: + commands: + - type: shell + cmd: whoami + +.. seealso:: + See * :ref:`Basic Usage ` for the full playbook structure. + +---- + Sliver Command Execution Errors =============================== @@ -156,3 +199,57 @@ and port, or is blocked by a firewall. .. seealso:: :ref:`sliver` and :ref:`sliver_config` for setup instructions and required configuration fields. + +Remote Command Execution Errors +=============================== + +.. _error-remote-connection-not-found: + +Remote Connection Not Found in Config +-------------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing REMOTE AttackMate command: Type='remote', RemoteCmd='execute_command' on server attackmate_server + ERROR | Execution failed: Remote connection 'attackmate_server' not found in config. + ... + attackmate.execexception.ExecException: Remote connection 'attackmate_server' not found in config. + ERROR | Error: Remote connection 'attackmate_server' not found in config. + +**Cause** + +A ``remote`` command references a connection name (here ``attackmate_server``) +that has no corresponding entry in the ``remote_config`` section of the +configuration file. + +**Solution** + +* Ensure the connection name used in the playbook command matches an entry + defined in ``remote_config`` in your configuration file. +* Check for typos in the connection name - it is case-sensitive. + +.. code-block:: yaml + + # In your config file — define the connection: + remote_config: + attackmate_server: + url: https://theremoteserver:8445 + username: testuser + password: testuser + cafile: /path/to/cert.pem + + # In your playbook — reference the same name: + commands: + - type: remote + cmd: execute_command + connection: attackmate_server + remote_command: + type: shell + cmd: whoami + +.. seealso:: + :ref:`remote_config` for the full list of required configuration fields. + +---- From 3dc5c9423d56002be707f41b744ffc27e84baa45 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Fri, 13 Mar 2026 14:40:40 +0100 Subject: [PATCH 02/10] add more remote troubleshooting --- docs/source/playbook/troubleshooting.rst | 196 +++++++++++++++++++++++ 1 file changed, 196 insertions(+) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index 6d827a1f..c2ba6e56 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -253,3 +253,199 @@ configuration file. :ref:`remote_config` for the full list of required configuration fields. ---- + +.. _error-remote-authentication-failed: + +Remote Authentication Failed +----------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing REMOTE AttackMate command: Type='remote', RemoteCmd='execute_command' on server attackmate_server (https://localhost:8445) + INFO | Client will verify https://localhost:8445 SSL using CA: /path/to/cert.pem + INFO | Successfully created remote client for: attackmate_server + INFO | Attempting login to https://localhost:8445/login for user 'admin'... + ERROR | Login failed for 'admin' at https://localhost:8445: 401 - {"detail":"Incorrect username or password"} + ERROR | Authentication failed or credentials not provided for https://localhost:8445 + ERROR | No response received from remote server (client communication failed). + ERROR | Error: No response received from remote server (client communication failed). + +**Cause** + +The credentials provided in the configuration do not match those expected +by the remote AttackMate server. The server returned a ``401 Unauthorized`` +response. + +**Solution** + +* Check that the ``username`` and ``password`` in your ``remote_config`` + entry are correct. +* Verify that the user account exists on the remote AttackMate server and + that the password has not changed. + + +.. seealso:: + :ref:`remote` and :ref:`remote_config` for the full list of required configuration fields. + +---- + +.. _error-remote-ssl-cert-not-found: + +Remote SSL Certificate Not Found +---------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing REMOTE AttackMate command: Type='remote', RemoteCmd='execute_command' on server attackmate_server (https://localhost:8445) + ERROR | CA certificate file not found: /path/to/certificate.pem. Falling back to default verification. + INFO | Successfully created remote client for: attackmate_server + INFO | Attempting login to https://localhost:8445/login for user 'testuser'... + ERROR | Login request to https://localhost:8445 failed: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1010) + ... + httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1010) + ERROR | Authentication failed or credentials not provided for https://localhost:8445 + ERROR | No response received from remote server (client communication failed). + ERROR | Error: No response received from remote server (client communication failed). + +**Cause** + +The CA certificate file specified in ``remote_config`` could not be found at +the given path. AttackMate fell back to default SSL verification, which then +failed because the remote server uses a self-signed certificate. + +**Solution** + +* Check that the ``cafile`` path in your ``remote_config`` points to the + correct certificate file and that the file exists. +* Ensure the path is absolute or correctly relative to the working directory + from which AttackMate is invoked. + +.. code-block:: yaml + + remote_config: + attackmate_server: + url: https://theremoteserver:8445 + username: testuser + password: testuser + cafile: /path/to/cert.pem +.. seealso:: + :ref:`remote` and :ref:`remote_config` for the full list of required configuration fields. + +---- + +.. _error-remote-command-not-supported: + +Command Type Not Supported on Remote Instances +------------------------------------------------------ + +**Symptom** + +.. code-block:: text + + ERROR | A Validation error occured when parsing playbook file playbooks/remote_remote.yml + ERROR | Traceback (most recent call last): + ... + pydantic_core._pydantic_core.ValidationError: 1 validation error for Playbook + commands.0.remote.remote_command + Input tag 'remote' found using 'type' does not match any of the expected tags: + 'sliver-session', 'sliver', 'browser', 'shell', 'msf-module', 'msf-session', + 'msf-payload', 'sleep', 'ssh', 'father', 'sftp', 'debug', 'setvar', 'regex', + 'mktemp', 'include', 'loop', 'webserv', 'http-client', 'json', 'vnc', 'bettercap' + [type=union_tag_invalid, input_value={'type': 'remote', 'cmd':...'path/to/playbook'}, input_type=dict] + +**Cause** + +A ``remote`` command was used as the ``remote_command`` of another ``remote`` +command - that is, a remote command was nested inside another remote command. +This is not supported; a remote AttackMate instance cannot itself dispatch +further remote commands. + +.. code-block:: yaml + + # Wrong — remote cannot be used as a remote_command: + commands: + - type: remote + cmd: execute_command + connection: attackmate_server + remote_command: + type: remote + cmd: execute_playbook + connection: another_server + playbook_path: + +**Solution** + +* Remove the nesting — a ``remote`` command can only wrap command types that + are executable on the target AttackMate instance directly. +* If you tried to execute a RemotelyExecutableCommand on the remote instance check for spelling mistakes in the ``type`` field + + +---- + +.. _error-remote-playbook-invalid: + +Invalid Playbook Submitted to Remote Instance (422 Server Error) +---------------------------------------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing REMOTE AttackMate command: Type='remote', RemoteCmd='execute_playbook' on server attackmate_server (https://localhost:8445) + INFO | Login successful for 'testuser' at https://localhost:8445. Token stored. + ERROR | API Error (POST https://localhost:8445/playbooks/execute/yaml): 422 + ERROR | Server Detail: {'message': 'Invalid playbook: 1 validation error(s).', 'errors': ["'commands': Input should be a valid list"]} + ERROR | No response received from remote server (client communication failed). + ERROR | Error: No response received from remote server (client communication failed). + +**Cause** + +The playbook submitted to the remote AttackMate instance failed validation +on the server side. Authentication succeeded, but the server rejected the +playbook with a ``422 Unprocessable Entity`` response. The server returns +a ``422`` in three cases: + +* **YAML parse error** — the playbook file is not valid YAML. The error + message will read ``Invalid playbook YAML: failed to parse YAML.`` +* **Validation error** — the playbook is valid YAML but fails Pydantic + model validation, for example a missing required field or an invalid + command type. The error message will read + ``Invalid playbook: N validation error(s).`` +* **Value error** — the playbook contains a semantic error that cannot be + caught by schema validation alone. The error message will read + ``Invalid playbook YAML.`` + +In the example above the ``commands`` field is not a valid list — the same +underlying issue described in :ref:`error-commands-not-a-list`, but caught +by the remote instance rather than locally. + +**Solution** + +* Inspect the ``errors`` field in the server detail for the specific + validation message. +* Validate the playbook locally first by running it directly with AttackMate + before submitting it to a remote instance — local validation produces more + detailed error output: + +.. code-block:: bash + + $ uv run attackmate playbooks/whoami.yml + +* For YAML syntax errors, check the playbook file for incorrect indentation, + missing colons, or unquoted special characters. +* For validation errors, refer to the playbook schema + +.. seealso:: + :ref:`error-commands-not-a-list` for the command not a valid list validation error. + + :ref:`error-invalid-command-type` for invalid command type errors. + + :ref:`error-missing-field` for missing required field errors. + + :ref:`remote` for documentation on the ``execute_playbook`` command. + +---- From 883ec2c0fc8267d5345aede0436da2f897b99cd1 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Fri, 13 Mar 2026 15:10:30 +0100 Subject: [PATCH 03/10] remove old log lines --- docs/source/playbook/troubleshooting.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index c2ba6e56..da44230f 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -399,8 +399,6 @@ Invalid Playbook Submitted to Remote Instance (422 Server Error) INFO | Login successful for 'testuser' at https://localhost:8445. Token stored. ERROR | API Error (POST https://localhost:8445/playbooks/execute/yaml): 422 ERROR | Server Detail: {'message': 'Invalid playbook: 1 validation error(s).', 'errors': ["'commands': Input should be a valid list"]} - ERROR | No response received from remote server (client communication failed). - ERROR | Error: No response received from remote server (client communication failed). **Cause** From 9689ac28b593e91248d5f2f96bec1fb96b616357 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Fri, 13 Mar 2026 15:10:43 +0100 Subject: [PATCH 04/10] password as SecretStr --- src/attackmate/executors/remote/remoteexecutor.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/attackmate/executors/remote/remoteexecutor.py b/src/attackmate/executors/remote/remoteexecutor.py index 5ad3f766..79091d2f 100644 --- a/src/attackmate/executors/remote/remoteexecutor.py +++ b/src/attackmate/executors/remote/remoteexecutor.py @@ -1,6 +1,7 @@ import logging import json from typing import Dict, Any, Optional +from pydantic import SecretStr from attackmate.executors.executor_factory import executor_factory from attackmate_client import RemoteAttackMateClient @@ -81,7 +82,7 @@ def setup_connection(self, command: AttackMateRemoteCommand) -> RemoteAttackMate client = RemoteAttackMateClient( server_url=info['url'], username=info['user'], - password=info['pass'], + password=SecretStr(info['pass']), cacert=info['cafile'] ) self._clients_cache[conn_name] = client From d1483a07fb70447203cdedb6b13d3b79153f0caf Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Fri, 13 Mar 2026 15:14:44 +0100 Subject: [PATCH 05/10] remove extra log lines --- docs/source/playbook/troubleshooting.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index da44230f..a4a4c77d 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -269,8 +269,7 @@ Remote Authentication Failed INFO | Attempting login to https://localhost:8445/login for user 'admin'... ERROR | Login failed for 'admin' at https://localhost:8445: 401 - {"detail":"Incorrect username or password"} ERROR | Authentication failed or credentials not provided for https://localhost:8445 - ERROR | No response received from remote server (client communication failed). - ERROR | Error: No response received from remote server (client communication failed). + **Cause** @@ -308,8 +307,7 @@ Remote SSL Certificate Not Found ... httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1010) ERROR | Authentication failed or credentials not provided for https://localhost:8445 - ERROR | No response received from remote server (client communication failed). - ERROR | Error: No response received from remote server (client communication failed). + **Cause** From 252c88d73db6754f8c83aab5da92de26765d11d0 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Fri, 13 Mar 2026 15:21:23 +0100 Subject: [PATCH 06/10] fix test with secret password --- test/units/test_remoteexecutor.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/test/units/test_remoteexecutor.py b/test/units/test_remoteexecutor.py index a088517d..ae980a85 100644 --- a/test/units/test_remoteexecutor.py +++ b/test/units/test_remoteexecutor.py @@ -2,6 +2,7 @@ import tempfile import pytest from unittest.mock import MagicMock, patch +from pydantic import SecretStr from attackmate.executors.remote.remoteexecutor import RemoteExecutor from attackmate.execexception import ExecException from attackmate.schemas.config import RemoteConfig @@ -151,12 +152,12 @@ def test_setup_connection_creates_new_client( client = executor.setup_connection(mock_remote_command) assert client == mock_client_instance - mock_client_class.assert_called_once_with( - server_url='https://primary.example.com', - username='user1', - password='pass1', - cacert='/path/to/ca.pem' - ) + call_kwargs = mock_client_class.call_args.kwargs + assert call_kwargs['server_url'] == 'https://primary.example.com' + assert call_kwargs['username'] == 'user1' + assert isinstance(call_kwargs['password'], SecretStr) + assert call_kwargs['password'].get_secret_value() == 'pass1' + assert call_kwargs['cacert'] == '/path/to/ca.pem' assert executor._clients_cache['primary'] == mock_client_instance @patch('attackmate.executors.remote.remoteexecutor.RemoteAttackMateClient') From 3ea278202a460fe4fd802620ce1a15c98af11ad5 Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Mon, 16 Mar 2026 16:25:35 +0100 Subject: [PATCH 07/10] add ssh errors to troubleshooting --- docs/source/playbook/troubleshooting.rst | 178 +++++++++++++++++++++++ 1 file changed, 178 insertions(+) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index a4a4c77d..7968e8cf 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -445,3 +445,181 @@ by the remote instance rather than locally. :ref:`remote` for documentation on the ``execute_playbook`` command. ---- + +SSH Command Errors +================== + +.. _error-ssh-no-session: + +No Existing SSH Session +----------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing SSH-Command: 'id' + ERROR | No existing session + +**Cause** + +An ``ssh`` command was executed, but AttackMate could not find an active session for the target host. This typically happens when: +* The user specified in the playbook does not exist on the remote target. + + +**Solution** + +* Verify User Existence: Ensure the ``user`` specified in your playbook actually exists on the target machine. + +.. seealso:: + :ref:`ssh` for details on how ssh sessions are used within AttackMate. + +---- + +.. _error-unable-to-connect-session: + +Unable to connect SSH Session +----------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing SSH-Command: 'id' + ERROR | [Errno None] Unable to connect to port 22 on 10.110.0.17 + +**Cause** + +An ``ssh`` command was executed, but AttackMate could not establish a TCP +connection to the specified port on the target host. This typically means +one of the following: + +* The target host is unreachable (e.g. routing issue, host is down). +* The SSH service is not running or is listening on a different port. +* A firewall or network policy is blocking the connection. +* The IP address or port in the SSH configuration is incorrect. + +**Solution** +* Verify that the target host is reachable, for example with ``ping`` or + ``traceroute``. +* Confirm that an SSH service is running on the target and listening on the + configured port (default: ``22``). +* Check that no firewall rule is blocking the connection on either the + client or the target side. +* Review the ``host`` and ``port`` fields in your SSH configuration and + ensure they match the target. +* Check Credentials: If you are using password or key-based authentication, + verify that the credentials in your configuration/playbook are valid for that remote user. + +.. seealso:: + :ref:`ssh` for details on how ssh sessions are used within AttackMate. + +---- + +.. _error-ssh-session-not-in-store: + +SSH Session Not Found in Session Store +--------------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing SSH-Command: 'id' + ERROR | SSH-Session not in Session-Store: example-session + +**Cause** + +An ``ssh`` command references a named session that does not exist in +AttackMate's session store. This happens when the ``session`` field in +the command points to a session that was never established — either +because the session-opening command was never executed, was skipped due +to a prior error, or the session name contains a typo. + +**Solution** +* Review the playbook order and confirm the session is established before + it is used. +* Ensure that a session-opening SSH command with the matching session name + runs successfully before any commands that reference it. +* Check for typos in the ``session`` field — session names are case-sensitive. + +.. code-block:: yaml + + # Wrong — session name does not match the created session: + commands: + - type: ssh + cmd: id + username: user + key_filename: /home/user/.ssh/key + hostname: 10.0.0.1 + creates_session: "foothold" + - type: ssh + cmd: id + session: "typo-session" # does not match "foothold" + + # Correct — session name matches exactly: + commands: + - type: ssh + cmd: id + username: user + key_filename: /home/user/.ssh/key + hostname: 10.0.0.1 + creates_session: "foothold" + - type: ssh + cmd: id + session: "foothold" + + +.. seealso:: + :ref:`ssh` for details on how SSH sessions are created and referenced + within AttackMate. + +---- + +Webserv Command Errors +====================== + +.. _error-webserv-hangs: + +Playbook Hangs After webserv Command +-------------------------------------- + +**Symptom** + +The playbook stops progressing and hangs indefinitely after a ``webserv`` +command. No subsequent commands are executed. + +.. code-block:: text + + 2026-03-16 16:22:19 INFO | Delay before commands: 1.0 seconds + 2026-03-16 16:22:20 INFO | Serving /home/user/files/example.txt via HTTP on Port 8000 + +**Cause** + +The ``webserv`` command starts an HTTP file server and blocks execution +until the server is stopped. Without setting ``background: true``, AttackMate +waits for the server to finish before continuing, which causes the playbook +to hang indefinitely. + +**Solution** + +* Always set ``background: true`` on ``webserv`` commands so that the server + is started in the background and playbook execution continues immediately. + +.. code-block:: yaml + + # Wrong — webserv blocks playbook execution: + commands: + - type: webserv + local_path: /home/user/files/example.txt + port: 8000 + + # Correct — webserv runs in the background: + commands: + - type: webserv + local_path: /home/user/files/example.txt + port: 8000 + background: true + +.. seealso:: + :ref:`webserv` for the full list of available configuration fields. From 630b575dfcc5f038eff1a1a050ec97d10b6a5fdc Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Mon, 16 Mar 2026 16:27:32 +0100 Subject: [PATCH 08/10] webserv link --- docs/source/playbook/commands/webserv.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/playbook/commands/webserv.rst b/docs/source/playbook/commands/webserv.rst index 03dd7457..51f4dd74 100644 --- a/docs/source/playbook/commands/webserv.rst +++ b/docs/source/playbook/commands/webserv.rst @@ -1,3 +1,5 @@ +.. _webserv: + ======= webserv ======= From 741547085876283c6e1689cc46717831b9363efb Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Tue, 17 Mar 2026 15:39:06 +0100 Subject: [PATCH 09/10] add certificate invalid --- docs/source/playbook/troubleshooting.rst | 50 ++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index 7968e8cf..69ca15e9 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -333,6 +333,55 @@ failed because the remote server uses a self-signed certificate. .. seealso:: :ref:`remote` and :ref:`remote_config` for the full list of required configuration fields. + +---- + +.. _error-remote-ssl-cert-invalid: + +Remote SSL Certificate Invalid +-------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Executing REMOTE AttackMate command: Type='remote', RemoteCmd='execute_command' on server attackmate_server (https://localhost:8445) + INFO | Client will verify https://localhost:8445 SSL using CA: /path/to/wrong.pem + INFO | Successfully created remote client for: attackmate_server + INFO | Attempting login to https://localhost:8445/login for user 'testuser'... + ERROR | Login request to https://localhost:8445 failed: [X509] PEM lib (_ssl.c:4106) + +**Cause** + +The CA certificate file specified in ``remote_config`` was found and loaded, +but its contents are not valid for verifying the remote server's certificate. +This happens when the ``cafile`` points to the wrong certificate — for example +a certificate from a different CA or an unrelated server. + +**Solution** + +* Ensure that the ``cafile`` in your ``remote_config`` points to the correct + CA certificate that was used to sign the remote AttackMate server's + certificate. +* If you are unsure which certificate to use, check the server setup + documentation or regenerate the certificate and update both the server + and the ``cafile`` path accordingly. + +.. code-block:: yaml + + remote_config: + attackmate_server: + url: https://localhost:8445 + username: testuser + password: testuser + cafile: /path/to/correct-ca.pem # must match the server's CA + +.. seealso:: + + :ref:`remote` and :ref:`remote_config` for the full list of required + configuration fields. +`` + ---- .. _error-remote-command-not-supported: @@ -446,6 +495,7 @@ by the remote instance rather than locally. ---- + SSH Command Errors ================== From 071d78aec79db1efe26c3ead93a91c99ba70941f Mon Sep 17 00:00:00 2001 From: thorinaboenke Date: Tue, 17 Mar 2026 15:56:33 +0100 Subject: [PATCH 10/10] add metasploit server unreachable --- docs/source/playbook/troubleshooting.rst | 43 ++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/docs/source/playbook/troubleshooting.rst b/docs/source/playbook/troubleshooting.rst index 69ca15e9..7f418c3f 100644 --- a/docs/source/playbook/troubleshooting.rst +++ b/docs/source/playbook/troubleshooting.rst @@ -673,3 +673,46 @@ to hang indefinitely. .. seealso:: :ref:`webserv` for the full list of available configuration fields. + +---- + +Msf Command Errors +====================== + +.. _error-msf-connection-refused: + +Metasploit RPC Server Unreachable +----------------------------------- + +**Symptom** + +.. code-block:: text + + INFO | Delay before commands: 0 seconds + WARNING | Creating temporary file.. + ERROR | HTTPSConnectionPool(host='127.0.0.1', port=55553): Max retries exceeded + with url: /api/ (Caused by NewConnectionError('Failed to establish a + new connection: [Errno 111] Connection refused')) + +**Cause** + +AttackMate could not connect to the Metasploit RPC server (``msfrpcd``). +The server is either not running, not listening on the configured port, or +is blocked by a firewall. + +**Solution** + +* Start the Metasploit RPC server before running the playbook. The default + command to start it is: + +.. code-block:: bash + + msfrpcd -P yourpassword -p 55553 -S + +* Verify that the ``port`` in your ``msf_config`` matches the port + ``msfrpcd`` is listening on. +* Ensure no firewall rule is blocking the connection to the configured port. + +.. seealso:: + :ref:`msf-module` and :ref:`msf_config` for setup instructions and required + configuration fields.