executor docs

docs/source/developing/baseexecutor.rst

@@ -31,6 +31,7 @@ Implementing a Custom Executor
 -------------------------------
 
 To create a custom executor, inherit from ``BaseExecutor`` and implement the ``_exec_cmd()`` method. Other methods can be overriden as needed.
+New executors must be registered using the @executor_factory.register_executor('<command_type>') decorator.
 
 Example:
 
@@ -99,4 +100,20 @@ executor __init__.py
 --------------------
 .. note::
 
-    Add the new executor to the ``__all__`` list in the ``__init__.py`` file of the ``attackmate.executors`` module.
+    Add the new executor to the ``__all__`` list in the ``__init__.py`` file of the ``attackmate.executors`` module so it can be imported elsewhere.
+
+.. code-block:: python
+
+    # src/attackmate/executors/__init__.py
+    # other imports
+    from .shell.shellexecutor import ShellExecutor
+    from .metasploit.msfsessionexecutor import CustomExecutor # new executor
+    # other imports
+
+    __all__ = [
+        'RemoteExecutor',
+        'BrowserExecutor',
+        'ShellExecutor',
+        'CustomExecutor', # new executor
+        # other executors
+    ]

docs/source/developing/command.rst

@@ -33,7 +33,7 @@ make it usable in external python scripts.
 
 **Example: a simple command with no sub-behaviors**
 
-::
+.. code-block:: python
 
     from typing import Literal
     from .base import BaseCommand
@@ -50,7 +50,7 @@ make it usable in external python scripts.
 
 **Example: a command with sub-behaviors expressed via** ``cmd``
 
-::
+.. code-block:: python
 
     from typing import Literal
     from .base import BaseCommand
@@ -68,7 +68,7 @@ make it usable in external python scripts.
 
 The new command should be handled by an executor in `src/attackmate/executors` that extends ``BaseExecutor`` and implements the ``_exec_cmd()`` method. For example:
 
-::
+.. code-block:: python
 
     from attackmate.executors.base_executor import BaseExecutor
     from attackmate.result import Result
@@ -92,7 +92,7 @@ When a command is executed, the ``create_executor`` method retrieves the corresp
 
 Accordingly, executors must be registered using the ``@executor_factory.register_executor('<command_type>')`` decorator.
 
-::
+.. code-block:: python
 
     @executor_factory.register_executor('debug')
     class DebugExecutor(BaseExecutor):
@@ -103,7 +103,7 @@ If the new executor class requires additional initialization arguments, these mu
 All configurations are always passed to the ``ExecutorFactory``.
 The factory filters the provided configurations based on the class constructor signature, ensuring that only the required parameters are used.
 
-::
+.. code-block:: python
 
         def _get_executor_config(self) -> dict:
         config = {
@@ -118,13 +118,35 @@ The factory filters the provided configurations based on the class constructor s
         }
         return config
 
+4. Add the Executor to the __init__ file of the attackmate.executors module
+===========================================================================
 
-4. Modify the Loop Command to Include the New Command
+Add the new executor to the __all__ list in the __init__.py file of the attackmate.executors module so it can be imported elsewhere.
+
+.. code-block:: python
+
+    # src/attackmate/executors/__init__.py
+    # other imports
+    from .shell.shellexecutor import ShellExecutor
+    from .metasploit.msfsessionexecutor import CustomExecutor # new executor
+    # other imports
+
+    __all__ = [
+        'RemoteExecutor',
+        'BrowserExecutor',
+        'ShellExecutor',
+        'CustomExecutor', # new executor
+        # other executors
+    ]
+
+
+
+5. Modify the Loop Command to Include the New Command
 =====================================================
 
 in `/src/attackmate/schemas/loop.py` update the ``LoopCommand`` schema to include the new command.
 
-::
+.. code-block:: python
 
     Command = Union[
             ShellCommand,
@@ -133,11 +155,12 @@ in `/src/attackmate/schemas/loop.py` update the ``LoopCommand`` schema to includ
         ]
 
 
-4. Modify the RemotelyExecutableCommand Union to Include the New Command
+6. Modify the RemotelyExecutableCommand Union to Include the New Command
 ========================================================================
 
 in `src/attackmate/schemas/command_subtypes.py`, update the ``RemotelyExecutableCommand`` type alias to include the new command
-::
+
+.. code-block:: python
 
     RemotelyExecutableCommand: TypeAlias = Annotated[
         Union[
@@ -176,7 +199,7 @@ in `src/attackmate/schemas/command_subtypes.py`, update the ``RemotelyExecutable
 
 Once these steps are completed, the new command will be fully integrated into AttackMate and available for execution.
 
-6. Add Documentation
+7. Add Documentation
 =====================
 
 Finally, update the documentation in `docs/source/playbook/commands` to include the new command.

docs/source/developing/integration.rst

@@ -67,11 +67,11 @@ Understanding the Result Object
 ===============================
 
 When executing a command with AttackMate, the result is returned as an instance of the ``Result`` class. This object contains the standard output (`stdout`) and the return code (`returncode`) of the executed command.
-Commands that run in the Background return Result('Command started in background', 0)
+Commands that run in the :ref:`background` return Result('Command started in background', 0)
 
 .. note::
    Regular Commands return a ``Result`` object.
-   Commands that run in background mode return ``Result('Command started in background', 0)``.
+   Commands that run in :ref:`background` mode return ``Result('Command started in background', 0)``.
 
 Attributes
 ----------

docs/source/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to AttackMate's documentation!
-==================================
+======================================
 
 .. toctree::
    :maxdepth: 1
@@ -32,6 +32,7 @@ Welcome to AttackMate's documentation!
    playbook/commands/index
    playbook/session/index
    playbook/examples
+   playbook/troubleshooting
 
 .. toctree::
    :maxdepth: 1

docs/source/playbook/commands/browser.rst

@@ -1,3 +1,5 @@
+.. _browser:
+
 =======
 browser
 =======
@@ -11,6 +13,9 @@ Execute commands using a Playwright-managed Chromium browser. This executor can
    etc.) across multiple commands, use the :confval:`creates_session` to open a named
    session and :confval:`session` to reuse it.
 
+   Background mode is not supported for this commands.
+
+
 .. code-block:: yaml
 
    vars:

docs/source/playbook/commands/include.rst

@@ -1,9 +1,15 @@
+.. _include:
+
 =======
 include
 =======
 
 Include and run commands from another yaml-file.
 
+.. note::
+
+   Background mode is not supported for this commands.
+
 .. code-block:: yaml
 
       # main.yml:

docs/source/playbook/commands/index.rst

@@ -28,6 +28,24 @@ Every command, regardless of its type supports the following general options:
           cmd: nmap localhost
           save: /tmp/nmap_localhost.txt
 
+.. confval:: metadata
+
+   An optional dictionary of key-value pairs that are logged alongside the command
+   but have no effect on execution.
+
+   :type: Dict
+   :default: None
+
+   .. code-block:: yaml
+
+      commands:
+        - type: debug
+          cmd: Come on, Cat
+          metadata:
+            version: 1
+            author: Ellen Ripley
+
+
 .. confval:: exit_on_error
 
    Attackmate will exit with an error if the command returns a non-zero exit code.
@@ -107,6 +125,8 @@ Every command, regardless of its type supports the following general options:
    :type: int
    :default: ``3``
 
+.. _conditionals:
+
 .. confval:: only_if
 
    Execute this command only if the condition evaluates to ``True``. Supported operators:
@@ -153,6 +173,8 @@ Every command, regardless of its type supports the following general options:
    .. warning::
 
         When comparing strings with integers, standard Python conventions apply:
+        see `Python reference — Comparisons
+        <https://docs.python.org/3/reference/expressions.html#comparisons>`_
 
         **Equality / Inequality** (``==``, ``!=``):
         A string and an integer are never equal, so ``"1" == 1`` is ``False``
@@ -161,7 +183,8 @@ Every command, regardless of its type supports the following general options:
         **Identity** (``is``, ``is not``):
         Compares object identity, not value. ``"1" is 1`` is always ``False``
         because a string and an integer are distinct objects, regardless of
-        their apparent values.
+        their apparent values.  see `Python reference — Value vs. identity
+        <https://docs.python.org/3/reference/expressions.html#is>`_
 
         **Ordering** (``<``, ``<=``, ``>``, ``>=``):
         Comparing a string with an integer raises a ``TypeError`` in Python 3
@@ -178,12 +201,18 @@ Every command, regardless of its type supports the following general options:
         while the literal is parsed as a ``bool`` by ``ast``.  Use string
         literals for boolean-like flags stored in the ``VariableStore``:
         ``$flag == "True"``.
+        see `Python built-in — bool (subclass of int)
+        <https://docs.python.org/3/library/functions.html#bool>`_
 
         Importantly, before a condition is evaluated, all ``$variable`` references are
         resolved by the ``VariableStore``.  **The store holds every value as a
         plain Python** ``str``, even values that were originally integers
         are coerced to ``str`` on ingress.
 
+
+.. _background:
+
+
 .. confval:: background
 
    Execute the command as a background subprocess. When enabled, output is not printed
@@ -194,23 +223,20 @@ Every command, regardless of its type supports the following general options:
 
    .. note::
 
-      The command in background-mode will change the :ref:`builtin variables <builtin-variables>`
+      The command in background mode will change the :ref:`builtin variables <builtin-variables>`
       ``RESULT_STDOUT`` to "Command started in Background" and ``RESULT_CODE`` to 0.
 
    Background mode is not supported for
 
-   * MsfModuleCommand
-   * IncludeCommand
-   * VncCommand
-   * BrowserCommand
+   * :ref:`MsfModuleCommand <msf-module>`
+   * :ref:`IncludeCommand <include>`
+   * :ref:`VncCommand <vnc>`
+   * :ref:`BrowserCommand <browser>`
 
    Background mode together with a session is not supported for the following commands:
 
-   * SSHCommand
-   * SFTPCommand
-
-
-
+   * :ref:`SSHCommand <ssh>`
+   * :ref:`SFTPCommand <sftp>`
 
 
 .. confval:: kill_on_exit
@@ -221,23 +247,6 @@ Every command, regardless of its type supports the following general options:
    :type: bool
    :default: ``True``
 
-.. confval:: metadata
-
-   An optional dictionary of key-value pairs that are logged alongside the command
-   but have no effect on execution.
-
-   :type: Dict
-   :default: None
-
-   .. code-block:: yaml
-
-      commands:
-        - type: debug
-          cmd: Come on, Cat
-          metadata:
-            version: 1
-            author: Ellen Ripley
-
 
 The next pages will describe each command type in detail.
 

docs/source/playbook/commands/msf-module.rst

@@ -10,6 +10,9 @@ Execute Metasploit modules via the Metasploit RPC API.
 
    To configure the connection to ``msfrpcd``, see :ref:`msf_config`.
 
+   Background mode is not supported for this commands.
+
+
 Some modules (like auxiliary scanners) produce direct output:
 
 .. code-block:: yaml

docs/source/playbook/commands/sftp.rst

@@ -1,3 +1,5 @@
+.. _sftp:
+
 ====
 sftp
 ====
@@ -8,8 +10,11 @@ created by either command can be reused by the other.
 
 .. note::
 
-   This command caches all settings so
-   that they only need to be defined once.
+   This command caches all settings so that they only need to be defined once.
+
+   Background mode with a session is not supported for this commands.
+
+
 .. code-block:: yaml
 
    vars:
@@ -45,8 +50,8 @@ File Transfer
 
    The SFTP operation to perform.
 
-   * ``put`` — upload a file from the local machine to the remote host
-   * ``get`` — download a file from the remote host to the local machine
+   * ``put`` - upload a file from the local machine to the remote host
+   * ``get`` - download a file from the remote host to the local machine
 
    :type: str
    :required: True

docs/source/playbook/commands/ssh.rst

@@ -11,6 +11,8 @@ Execute commands on a remote host via SSH.
    This command caches all settings so
    that they only need to be defined once.
 
+   Background mode with a session is not supported for this commands.
+
 .. code-block:: yaml
 
    vars:

docs/source/playbook/commands/vnc.rst

@@ -1,3 +1,5 @@
+.. _vnc:
+
 ===
 vnc
 ===
@@ -11,6 +13,10 @@ cached after the first command, so subsequent commands only need to specify what
    VNC sessions must be explicitly closed with ``cmd: close``, otherwise AttackMate
    will hang on exit.
 
+.. note::
+
+   Background mode is not supported for this commands.
+
 .. code-block:: yaml
 
    vars: