Adding connections api

README.md

@@ -17,7 +17,8 @@ Each portspoof_py instance runs independently and exposes a JSON API. portspoof_
 7. [Adding nodes](#adding-nodes)
 8. [Fetch cron](#fetch-cron)
 9. [HTTP trigger endpoint](#http-trigger-endpoint)
-10. [Dashboard](#dashboard)
+10. [JSON API](#json-api)
+11. [Dashboard](#dashboard)
 11. [Upgrading](#upgrading)
 12. [Troubleshooting](#troubleshooting)
 
@@ -56,6 +57,8 @@ portspoof_concentrator/
 │   ├── footer.php        Shared footer with version number
 │   ├── functions.php     Node CRUD, fetch helpers, run_fetch(), dashboard queries
 │   └── style.php         Shared CSS (included inline by both pages)
+├── api/
+│   └── connections.php   JSON API — recent connections (token-protected)
 └── cron/
     └── fetch.php         CLI polling script — run via cron or manually (CLI only)
 ```
@@ -421,6 +424,68 @@ When the endpoint is disabled: `503 Service Unavailable`.
 
 ---
 
+## JSON API
+
+### `GET /api/connections.php`
+
+Returns connections ingested within a configurable lookback window, newest first.
+
+Uses the same `TRIGGER_TOKEN` for authentication as `trigger.php` — set it in `config.php` before use.
+
+#### Parameters
+
+| Parameter | Default | Max | Description |
+|---|---|---|---|
+| `minutes` | `10` | `1440` | Lookback window in minutes |
+| `node_id` | _(all)_ | — | Filter results to a specific node ID |
+
+#### Authentication
+
+```bash
+# Authorization header (preferred)
+curl -H "Authorization: Bearer your-token" https://yourserver/api/connections.php
+
+# Query string
+curl "https://yourserver/api/connections.php?token=your-token"
+```
+
+#### Examples
+
+```bash
+# Last 10 minutes from all nodes
+curl -H "Authorization: Bearer your-token" https://yourserver/api/connections.php
+
+# Last 30 minutes from node 2
+curl -H "Authorization: Bearer your-token" "https://yourserver/api/connections.php?minutes=30&node_id=2"
+```
+
+#### Response
+
+```json
+{
+    "since": "2026-03-11T14:01:00Z",
+    "minutes": 10,
+    "count": 3,
+    "connections": [
+        {
+            "id": 9821,
+            "occurred_at": "2026-03-11 14:10:42.831204",
+            "node_id": 1,
+            "node_name": "honeypot-eu-1",
+            "src_ip": "198.51.100.42",
+            "src_port": 54312,
+            "dst_port": 443,
+            "banner_hex": "485454502f312e31203230300d0a",
+            "banner_len": 14
+        }
+    ]
+}
+```
+
+`banner_hex` is null when portspoof_py sent no banner. `occurred_at` is in the database timezone (UTC recommended).
+
+---
+
 ## Dashboard
 
 `index.php` auto-refreshes every 30 seconds and shows: