Api refactor

.github/workflows/python-app.yml

@@ -26,7 +26,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
+        pip install flake8 pytest pytest-asyncio
         pip install -e .
         if [ -f test/requirements.txt ]; then pip install -r test/requirements.txt; fi
     - name: Install Playwright browser

.gitignore

@@ -169,3 +169,6 @@ cython_debug/
 playbooks/
 .penpal.yml
 .attackmate.yml
+attackmate.json
+attackmate.log
+output.log

docs/source/configuration/index.rst

@@ -11,12 +11,13 @@ is not used, attackmate will search at the following locations for the config-fi
 #. **$HOME/.config/attackmate.yml**
 #. **/etc/attackmate.yml**
 
-The optional configuration-file is in yaml-format and is divided into three sections:
+The optional configuration-file is in yaml-format and is divided into five sections:
 
 * **cmd_config**: defines settings for all commands
 * **msf_config**: connection settings for the msfrpcd
 * **bettercap_config**: connection settings for the bettercap rest-api
 * **sliver_config**: connection settings for the sliver-api
+* **remote_config**: connection settings for the remote attackmate server
 
 The following configuration file is an example for a basic configuration with
 sliver and metasploit:
@@ -51,3 +52,4 @@ For detailed information about the config sections see:
    bettercap_config
    msf_config
    sliver_config
+   remote_config

docs/source/configuration/remote_config.rst

@@ -0,0 +1,63 @@
+.. _remote_config:
+
+=============
+remote_config
+=============
+
+The remote_config section defines connections to remote AttackMate instances. This allows one AttackMate instance to act as a controller, dispatching playbooks or commands to remote nodes.
+
+Like other executors, the configuration uses unique identifiers (names) for each connection. If a command in a playbook does not explicitly specify a connection, the first entry defined in this configuration is used as the default.
+
+.. code-block:: yaml
+
+remote_config:
+  remote_server:
+    url: "https://10.0.0.5:5000"
+    username: admin
+    password: securepassword
+    cafile: "/path/to/cert.pem"
+  another_server:
+    url: "https://10.0.0.6:5000"
+    username: user
+    password: anotherpassword
+    cafile: "/path/to/another_cert.pem"
+
+.. code-block:: yaml
+
+commands:
+# Executed on 'another_server'
+- type: remote
+  connection: another_server
+  cmd: execute_command
+  remote_command:
+    type: shell
+    cmd: "whoami"
+
+ # Executed on 'remote_server' (defaults to first remote_config entry))
+ - type: remote
+   cmd: execute_playbook
+   playbook_yaml_path: path/to/playbook.yml
+
+.. confval:: url
+
+The base URL of the remote AttackMate REST API.
+
+:type: str :required: True
+
+.. confval:: username
+
+The username for authentication with the remote AttackMate instance.
+
+:type: str :required: False
+
+.. confval:: password
+
+The password for authentication with the remote AttackMate instance.
+
+:type: str :required: False
+
+.. confval:: cafile
+
+The path to a CA certificate file used to verify the remote server's SSL certificate. This is highly recommended when using HTTPS.
+
+:type: str :required: False

docs/source/developing/baseexecutor.rst

@@ -40,7 +40,7 @@ Example:
     from attackmate.result import Result
 
     class CustomExecutor(BaseExecutor):
-        def _exec_cmd(self, command) -> Result:
+        async def _exec_cmd(self, command) -> Result:
             self.logger.info(f"Executing custom command: {command.cmd}")
             return Result(stdout="Execution complete", returncode=0)
 
@@ -68,7 +68,7 @@ The following methods can be overridden in custom executors to modify behavior:
 
 .. code-block:: python
 
-    def _exec_cmd(self, command: BaseCommand) -> Result:
+    async def _exec_cmd(self, command: BaseCommand) -> Result:
         return Result(None, None)
 
 This is the core execution function and must be implemented in subclasses.

docs/source/developing/command.rst

@@ -47,7 +47,7 @@ The new command should be handled by an executor in `src/attackmate/executors``
 
     @executor_factory.register_executor('debug')
     class DebugExecutor(BaseExecutor):
-        def _exec_cmd(self, command: DebugCommand) -> Result:
+        async def _exec_cmd(self, command: DebugCommand) -> Result:
             self.logger.info(f"Executing debug command: {command.cmd}")
             return Result(stdout="Debug executed", returncode=0)
 

docs/source/remote.rst

@@ -0,0 +1,50 @@
+
+Remote Execution
+=================
+AttackMate can be used for remote command execution.
+This section explains hoe the server handles authentication, logging, and AttackMate instances.
+
+Authentication
+--------------
+
+The AttackMate API server secures its endpoints using **token-based authentication**.
+
+* **Login Endpoint**: Clients must first authenticate by sending a username and password to the `/login` endpoint (e.g., `https://localhost:8445/login`). This endpoint is defined in `main.py` and uses FastAPI's `OAuth2PasswordRequestForm` for standard form encoding.
+* **Token Generation**: Upon successful authentication, the server generates an access token and returns it to the client. 
+* **Token Storage and Usage**:
+    * The provided token is received and then stored globally (`CURRENT_TOKEN`) and optionally in an environment variable (`ATTACKMATE_API_TOKEN`).
+    * For subsequent requests to protected endpoints (like `/command` or `/playbooks`), the client include this token in the `X-Auth-Token` header.
+    * The `update_token_from_response` function in `client.py` also suggests a mechanism for token renewal, where the server might return a new token in a response.
+* **SSL/TLS**: The `main.py` server is configured to run with HTTPS on port `8443`, requiring `key.pem` and `cert.pem` files for SSL/TLS encryption. Clients should specify the path to the server's public certificate.
+
+Logging
+-------
+
+The AttackMate API server provides the following logging features:
+
+* **Centralized Logging**: `main.py` initializes several loggers (`attackmate_api`, `playbook`, `output`, `json`) at startup.
+* **Instance-Specific Logging**: For remote command and playbook executions, AttackMate implements instance-specific logging.
+    * The `instance_logging` context manager (from `log_utils.py`) creates dedicated log files for each AttackMate instance based on its `instance_id`.
+    * These logs are stored in a `attackmate_server_logs` directory (relative to the project root, or a configurable absolute path like `/var/log/attackmate_instances`).
+    * Each remote command or playbook execution within an instance generates new timestamped log files (e.g., `20240715_123456_my_instance_output.log`).
+    * This ensures that logs from different concurrent AttackMate instances remain separate.
+* **Log Levels**: Log levels can be adjusted for debugging, providing more verbose output when needed.
+
+AttackMate Instances
+--------------------
+
+The AttackMate API server manages AttackMate instances to handle multiple execution contexts.
+
+* **Default Instance**: On startup, `main.py` initializes a single default AttackMate instance named `default_context`. This instance handles request to process entire playbooks.
+* **Instance Management**: 
+    * The server can create and manage multiple AttackMate instances, each identified by a unique `instance_id`.
+* **Instance Lifecycle**:
+    * Instances are stored in a global dictionary (`state.INSTANCES`).
+    * When the API server starts (`lifespan` function in `main.py`), it loads a global AttackMate configuration and creates the `default_context` instance.
+    * When the API server shuts down, it iterates through all active instances, performing cleanup operations like `clean_session_stores()` and `kill_or_wait_processes()` to ensure resources are properly released.
+* **Command and Playbook Execution**:
+    * The API routes (`commands`, `playbooks` routers included in `main.py`) receive client requests.
+    * These requests specify an `instance_id` (or implicitly use `default_context`).
+    * The API then dispatches the command or playbook to the designated AttackMate instance for execution. This allows for isolated execution environments, where variables and session data for one instance do not interfere with another.
+* **State Management**: 
+    * Each AttackMate instance maintains its own internal state, including a `VariableStore`. 

pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 ]
 description = "AttackMate is an attack orchestration tool that executes full attack-chains based on playbooks."
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.10"
 keywords = ["Pentest", "Attack", "Orchestration", "Hacking", "Simulating", "Attackchain"]
 license = {text = "GPL-3.0"}
 dependencies = [
@@ -27,15 +27,16 @@ dependencies = [
     "uvicorn",
     "dotenv",
     "passlib",
-    "python-multipart"
+    "python-multipart",
+    "attackmate-client @ git+https://github.com/ait-testbed/attackmate-client.git",
 ]
 dynamic = ["version"]
 
 [project.scripts]
 attackmate = "attackmate.__main__:main"
 
 [build-system]
-requires = ["setuptools"]
+requires = ["setuptools>=61.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
 # [tool.setuptools]
@@ -55,3 +56,9 @@ version = {attr = "attackmate.metadata.__version__"}
 
 [tool.mypy]
 explicit_package_bases = true
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio>=1.3.0",
+    "vcrpy>=8.1.1",
+]