Add new output module for Splunk

bbot/modules/output/splunk.py

@@ -0,0 +1,59 @@
+from bbot.core.errors import RequestError
+
+from bbot.modules.output.base import BaseOutputModule
+
+
+class Splunk(BaseOutputModule):
+    watched_events = ["*"]
+    meta = {"description": "Send every event to a splunk instance through HTTP Event Collector"}
+    options = {
+        "url": "",
+        "hectoken": "",
+        "index": "",
+        "source": "",
+        "timeout": 10,
+    }
+    options_desc = {
+        "url": "Web URL",
+        "hectoken": "HEC Token",
+        "index": "Index to send data to",
+        "source": "Source path to be added to the metadata",
+        "timeout": "HTTP timeout",
+    }
+
+    async def setup(self):
+        self.url = self.config.get("url", "")
+        self.source = self.config.get("source", "bbot")
+        self.index = self.config.get("index", "main")
+        self.timeout = self.config.get("timeout", 10)
+        self.headers = {}
+
+        hectoken = self.config.get("hectoken", "")
+        if hectoken:
+            self.headers["Authorization"] = f"Splunk {hectoken}"
+        if not self.url:
+            return False, "Must set URL"
+        if not self.source:
+            self.warning("Please provide a source")
+        return True
+
+    async def handle_event(self, event):
+        while 1:
+            try:
+                data = {
+                    "index": self.index,
+                    "source": self.source,
+                    "sourcetype": "_json",
+                    "event": event.json(),
+                }
+                await self.helpers.request(
+                    url=self.url,
+                    method="POST",
+                    headers=self.headers,
+                    json=data,
+                    raise_error=True,
+                )
+                break
+            except RequestError as e:
+                self.warning(f"Error sending {event}: {e}, retrying...")
+                await self.helpers.sleep(1)

bbot/test/test_step_2/module_tests/test_module_splunk.py

@@ -0,0 +1,58 @@
+import json
+import httpx
+
+from .base import ModuleTestBase
+
+
+class TestSplunk(ModuleTestBase):
+    downstream_url = "https://splunk.blacklanternsecurity.fakedomain:1234/services/collector"
+    config_overrides = {
+        "output_modules": {
+            "splunk": {
+                "url": downstream_url,
+                "hectoken": "HECTOKEN",
+                "index": "bbot_index",
+                "source": "bbot_source",
+            }
+        }
+    }
+
+    def verify_data(self, j):
+        if not j["source"] == "bbot_source":
+            return False
+        if not j["index"] == "bbot_index":
+            return False
+        data = j["event"]
+        if not data["data"] == "blacklanternsecurity.com" and data["type"] == "DNS_NAME":
+            return False
+        return True
+
+    async def setup_after_prep(self, module_test):
+        self.url_correct = False
+        self.method_correct = False
+        self.got_event = False
+        self.headers_correct = False
+
+        async def custom_callback(request):
+            j = json.loads(request.content)
+            if request.url == self.downstream_url:
+                self.url_correct = True
+            if request.method == "POST":
+                self.method_correct = True
+            if "Authorization" in request.headers:
+                self.headers_correct = True
+            if self.verify_data(j):
+                self.got_event = True
+            return httpx.Response(
+                status_code=200,
+            )
+
+        module_test.httpx_mock.add_callback(custom_callback)
+        module_test.httpx_mock.add_callback(custom_callback)
+        module_test.httpx_mock.add_response()
+
+    def check(self, module_test, events):
+        assert self.got_event == True
+        assert self.headers_correct == True
+        assert self.method_correct == True
+        assert self.url_correct == True

docs/scanning/output.md

@@ -135,6 +135,25 @@ output_modules:
     password: P@ssw0rd
 ```
 
+### Splunk
+
+The `splunk` output module sends [events](events.md) in JSON format to a desired splunk instance via [HEC](https://docs.splunk.com/Documentation/Splunk/9.2.0/Data/UsetheHTTPEventCollector).
+
+You can customize this output with the following config options:
+
+```yaml title="~/.bbot/config/bbot.yml"
+output_modules:
+  splunk:
+    # The full URL with the URI `/services/collector/event`
+    url: https://localhost:8088/services/collector/event
+    # Generated from splunk webui
+    hectoken: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+    # Defaults to `main` if not set
+    index: my-specific-index
+    # Defaults to `bbot` if not set
+    source: /my/source.json
+```
+
 ### Asset Inventory
 
 The `asset_inventory` module produces a CSV like this: