fix tests, started interact.sh developer docs

bbot/core/helpers/command.py

@@ -127,7 +127,7 @@ async def run_live(self, *command, check=False, text=True, **kwargs):
                 log.warning(f"Stderr for run_live({command_str}):\n\t{stderr}")
 
 
-def _spawn_proc(self, *command, **kwargs):
+async def _spawn_proc(self, *command, **kwargs):
     """Spawns an asynchronous subprocess.
 
     Prepares the command and associated keyword arguments. If the `input` argument is provided,

bbot/core/helpers/helper.py

@@ -19,11 +19,29 @@
 
 class ConfigAwareHelper:
     """
-    A central class designed to provide easy access to helpers.
-
-    Since certain helper functions rely on configuration-specific parameters
-    (such as dns and http which rely on rate-limits etc.,) it also provides
-    certain helpers with access to the config and the current BBOT scan instance.
+    Centralized helper class that provides unified access to various helper functions.
+
+    This class serves as a convenient interface for accessing helper methods across different files.
+    It is designed to be configuration-aware, allowing helper functions to utilize scan-specific
+    configurations like rate-limits. The class leverages Python's `__getattribute__` magic method
+    to provide seamless access to helper functions across various namespaces.
+
+    Attributes:
+        config (dict): Configuration settings for the BBOT scan instance.
+        _scan (Scan): A BBOT scan instance.
+        bbot_home (Path): Home directory for BBOT.
+        cache_dir (Path): Directory for storing cache files.
+        temp_dir (Path): Directory for storing temporary files.
+        tools_dir (Path): Directory for storing tools, e.g. compiled binaries.
+        lib_dir (Path): Directory for storing libraries.
+        scans_dir (Path): Directory for storing scan results.
+        wordlist_dir (Path): Directory for storing wordlists.
+        current_dir (Path): The current working directory.
+        keep_old_scans (int): The number of old scans to keep.
+
+    Examples:
+        >>> helper = ConfigAwareHelper(config)
+        >>> ips = helper.dns.resolve("www.evilcorp.com")
     """
 
     from . import ntlm
@@ -106,7 +124,22 @@ def _make_dummy_module(self, name, _type="scan"):
 
     def __getattribute__(self, attr):
         """
-        Allow static functions from sub-helpers to be accessed from the main class
+        Do not be afraid, the angel said.
+
+        Overrides Python's built-in __getattribute__ to provide convenient access to helper methods.
+
+        This method first attempts to find an attribute within this class itself. If unsuccessful,
+        it then looks in the 'misc', 'dns', and 'web' helper modules, in that order. If the attribute
+        is still not found, an AttributeError is raised.
+
+        Args:
+            attr (str): The attribute name to look for.
+
+        Returns:
+            Any: The attribute value, if found.
+
+        Raises:
+            AttributeError: If the attribute is not found in any of the specified places.
         """
         try:
             # first try self

bbot/core/helpers/interactsh.py

@@ -19,6 +19,65 @@
 
 
 class Interactsh:
+    """
+    A pure python implementation of ProjectDiscovery's interact.sh.
+
+    *"Interactsh is an open-source tool for detecting out-of-band interactions. It is a tool designed to detect vulnerabilities that cause external interactions."*
+
+    - https://app.interactsh.com
+    - https://github.com/projectdiscovery/interactsh
+
+    This class facilitates interactions with the interact.sh service for
+    out-of-band data exfiltration and vulnerability confirmation. It allows
+    for customization by accepting server and token parameters from the
+    configuration provided by `parent_helper`.
+
+    Attributes:
+        parent_helper (ConfigAwareHelper): An instance of a helper class containing configuration data.
+        server (str): The server to be used. If None (the default), a random server will be chosen from a predetermined list.
+        correlation_id (str): An identifier to correlate requests and responses. Default is None.
+        custom_server (str): Optional. A custom interact.sh server. Loaded from configuration.
+        token (str): Optional. A token for interact.sh API. Loaded from configuration.
+        _poll_task (AsyncTask): The task responsible for polling the interact.sh server. Default is None.
+
+    Examples:
+        ```python
+        # instantiate interact.sh client (no requests are sent yet)
+        >>> interactsh_client = s.helpers.interactsh()
+        # register with an interact.sh server
+        >>> interactsh_domain = await interactsh_client.register()
+        [INFO] Registering with interact.sh server: oast.me
+        [INFO] Successfully registered to interactsh server oast.me with correlation_id rg99x2f860h5466ou3so [rg99x2f860h5466ou3so86i07n1m3013k.oast.me]
+        # simulate an out-of-band interaction
+        >>> await s.helpers.request(f"https://{interactsh_domain}/test")
+        # wait for out-of-band interaction to be registered
+        >>> await asyncio.sleep(10)
+        >>> data_list = await interactsh_client.poll()
+        >>> print(data_list)
+        [
+            {
+                "protocol": "dns",
+                "unique-id": "rg99x2f860h5466ou3so86i07n1m3013k",
+                "full-id": "rg99x2f860h5466ou3so86i07n1m3013k",
+                "q-type": "A",
+                "raw-request": "...",
+                "remote-address": "1.2.3.4",
+                "timestamp": "2023-09-15T21:09:23.187226851Z"
+            },
+            {
+                "protocol": "http",
+                "unique-id": "rg99x2f860h5466ou3so86i07n1m3013k",
+                "full-id": "rg99x2f860h5466ou3so86i07n1m3013k",
+                "raw-request": "GET /test HTTP/1.1 ...",
+                "remote-address": "1.2.3.4",
+                "timestamp": "2023-09-15T21:09:24.155677967Z"
+            }
+        ]
+        # finally, shut down the client
+        >>> await interactsh_client.deregister()
+        ```
+    """
+
     def __init__(self, parent_helper):
         self.parent_helper = parent_helper
         self.server = None

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
         # dev/helpers/index.md
         - Command: dev/helpers/command.md
         - DNS: dev/helpers/dns.md
+        - Interactsh: dev/helpers/interactsh.md
         - Miscellaneous: dev/helpers/misc.md
   - Misc:
     - Release History: release_history.md