Added Shodan Alert API Collector

In cooperation with Malawi CERT

Author: sebix

CHANGELOG.md

@@ -24,6 +24,7 @@ Please refer to the [NEWS](NEWS.md) for a list of changes which have an affect o
 
 ### Bots
 #### Collectors
+- `intelmq.bots.collectors.shodan.collector_alert`: Added a new collector to query the Shodan Alert API (PR#2618 by Sebastian Wagner and Malawi CERT).
 
 #### Parsers
 

docs/user/bots.md

@@ -1004,6 +1004,10 @@ Requires the shodan library to be installed:
 
 Only the proxy is used (requires `shodan-python > 1.8.1`). Certificate is always verified.
 
+**`api_key`**
+
+Your Shodan API Key.
+
 **`countries`**
 
 () A list of countries to query for. If it is a string, it will be spit by `,`.
@@ -1021,6 +1025,30 @@ applies, if not null.
 
 ---
 
+### Shodan Alert <div id="intelmq.bots.collectors.shodan.collector_alert" />
+
+Queries the Shodan Alert Streaming API.
+
+Configure Alerts in the Shodan Interface (Website or CLI tool), then receive the data on the alerts via the Streaming service.
+
+Requires the shodan library to be installed:
+
+- <https://github.com/achillean/shodan-python/>
+
+- <https://pypi.org/project/shodan/>
+
+**Module:** `intelmq.bots.collectors.shodan.collector_alert`
+
+**Parameters (also expects [feed parameters](#feed-parameters) and [HTTP parameters](#http-parameters)):**
+
+Of the generic HTTP parameters, only the proxy is used (requires `shodan-python > 1.8.1`). The API endpoint certificate is always verified.
+
+**`api_key`**
+
+Your Shodan API Key.
+
+---
+
 ### TCP <div id="intelmq.bots.collectors.tcp.collector" />
 
 TCP is the bot responsible to receive events on a TCP port (ex: from TCP Output of another IntelMQ instance). Might not

intelmq/bots/collectors/shodan/collector_alert.py

@@ -0,0 +1,45 @@
+"""
+SPDX-FileCopyrightText: 2025 Institute for Common Good Technology & Malawi CERT
+SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+
+from intelmq.lib.bot import CollectorBot
+
+from json import dumps as json_dumps
+from typing import Optional
+
+try:
+    from shodan import Shodan
+except ImportError:
+    shodan = None
+
+
+class ShodanAlertCollector(CollectorBot):
+    """
+    Stream Listener for Shodan Alerts
+    """
+
+    api_key: Optional[str] = None
+
+    def init(self):
+        if shodan is None:
+            raise ValueError("Library 'shodan' is needed but not installed.")
+
+        self.set_request_parameters()
+        if tuple(int(v) for v in pkg_resources.get_distribution("shodan").version.split('.')) <= (1, 8, 1):
+            if self.proxy:
+                raise ValueError('Proxies are given but shodan-python > 1.8.1 is needed for proxy support.')
+            else:
+                self.api = shodan.Shodan(self.api_key)
+        else:
+            self.api = shodan.Shodan(self.api_key,
+                                     proxies=self.proxy)
+
+    def process(self):
+        for alert in self.api.stream.alert():
+            report = self.new_report()
+            report['raw'] = json_dumps(alert)
+            self.send_message(report)
+
+
+BOT = ShodanAlertCollector