From 0d191e1a98f5d720ad0acf281ff2160476099e3e Mon Sep 17 00:00:00 2001 From: Tizian Maxime Weigt Date: Sun, 1 Mar 2026 12:15:03 +0000 Subject: [PATCH] README.md aktualisiert --- README.md | 2436 ++++++----------------------------------------------- 1 file changed, 257 insertions(+), 2179 deletions(-) diff --git a/README.md b/README.md index b70b023..399331b 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ http://{instance_ip}:8081/api/v2 openapi: 3.0.0 info: title: TMW Shield REST API v2 + version: "2.0.0" servers: - url: http://{instance_ip}:8081/api/v2 @@ -37,11 +38,11 @@ servers: components: securitySchemes: - QueryKeyAuth: - type: bearer - in: header - name: Authorization - description: Bearer token authentication + BearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + description: Bearer token authentication (use Authorization header with Bearer ) schemas: GenericError: @@ -246,6 +247,8 @@ components: StatsAggregatedResponse: type: object properties: + range: + type: string allowed: type: array items: @@ -258,12 +261,25 @@ components: type: array items: type: integer + value_type: + type: string + enum: ["count_per_bucket", "pps"] + unit: + type: string + bucket_seconds: + type: integer activeProtections: type: array + items: + type: object sentProtections: type: array + items: + type: object activeAttacks: type: array + items: + type: object AttacksResponse: type: object properties: @@ -273,6 +289,25 @@ components: type: array items: type: object + properties: + attack_type: + type: string + target_ip: + type: string + dropped_pps: + type: integer + gbps: + type: number + multi_port: + type: boolean + dest_ports: + type: array + items: + type: integer + first_seen: + type: integer + last_seen: + type: integer AttacksHistoryResponse: type: object properties: @@ -282,6 +317,47 @@ components: type: array items: type: object + properties: + attack_type: + type: string + target_ip: + type: string + peak_pps: + type: integer + peak_gbps: + type: number + start: + type: integer + end: + type: integer + duration: + type: integer + protocols: + type: string + start_iso: + type: string + end_iso: + type: string + multi_port: + type: boolean + dest_ports: + type: array + items: + type: integer + + DestPortsResponse: + type: object + properties: + success: + type: boolean + ip: + type: string + ports: + type: array + items: + type: integer + multi_port: + type: boolean LogsResponse: type: object properties: @@ -297,6 +373,9 @@ components: status: type: string example: "ok" + version: + type: string + example: "2.0.0" WebhookEntry: type: object properties: @@ -365,6 +444,8 @@ components: type: string CheckIPRequest: type: object + required: + - ip properties: ip: type: string @@ -415,12 +496,6 @@ components: properties: node: type: string - AbuseIPDBEntry: - type: object - properties: - src: - type: string - example: "198.51.100.7" AbuseIPDBResponse: type: object properties: @@ -442,18 +517,42 @@ components: type: array items: type: object - AbuseIPDBConfigRequest: + SessionEntry: type: object properties: + src: + type: string dst: type: string - example: "10.0.0.1" - enable: + connections: + type: integer + age_sec: + type: number + src_port: + type: integer + nullable: true + dst_port: + type: integer + nullable: true + validated: type: boolean - example: true + nullable: true + ports_known: + type: boolean + SessionsResponse: + type: object + properties: + count: + type: integer + dst: + type: string + sessions: + type: array + items: + $ref: '#/components/schemas/SessionEntry' security: - - QueryKeyAuth: [] + - BearerAuth: [] paths: /blacklists: @@ -461,7 +560,7 @@ paths: summary: List Blacklist Entries description: Retrieves all blacklist entries across all interfaces security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Blacklist entries retrieved successfully @@ -486,7 +585,7 @@ paths: summary: Create Blacklist Entry description: Creates a new blacklist entry for blocking traffic security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -541,7 +640,7 @@ paths: summary: Remove Blacklist Entry description: Removes a blacklist entry security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -597,7 +696,7 @@ paths: summary: List Whitelist Entries description: Retrieves all whitelist entries across all interfaces security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Whitelist entries retrieved successfully @@ -622,7 +721,7 @@ paths: summary: Create Whitelist Entry description: Creates a new whitelist entry for allowing traffic security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -677,7 +776,7 @@ paths: summary: Remove Whitelist Entry description: Removes a whitelist entry security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -733,7 +832,7 @@ paths: summary: List Protocol Allow Entries description: Retrieves all protocol allow entries across all interfaces security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Protocol allow entries retrieved successfully @@ -758,7 +857,7 @@ paths: summary: Create Protocol Allow Entry description: Creates a new protocol allow entry for specific destination security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -809,7 +908,7 @@ paths: summary: Remove Protocol Allow Entry description: Removes a protocol allow entry security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -867,7 +966,7 @@ paths: summary: List Service Ports description: Retrieves all service ports across all interfaces security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Service ports retrieved successfully @@ -892,7 +991,7 @@ paths: summary: Add Service Port description: Adds a new service port for monitoring security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -938,7 +1037,7 @@ paths: summary: Remove Service Port description: Removes a service port security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -991,7 +1090,7 @@ paths: summary: List VLAN Bypass Entries description: Retrieves all VLAN bypass entries across all interfaces security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: VLAN bypass entries retrieved successfully @@ -1016,7 +1115,7 @@ paths: summary: Add VLAN Bypass Entry description: Adds a new VLAN bypass for traffic security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1062,7 +1161,7 @@ paths: summary: Remove VLAN Bypass Entry description: Removes a VLAN bypass entry security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1115,7 +1214,7 @@ paths: summary: Get Live Traffic Statistics description: Retrieves current live traffic statistics and counters security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Live statistics retrieved successfully @@ -1141,7 +1240,7 @@ paths: summary: Get Per-IP Statistics description: Retrieves traffic statistics for specific IP addresses security: - - QueryKeyAuth: [] + - BearerAuth: [] parameters: - name: ip in: query @@ -1175,7 +1274,7 @@ paths: summary: Get Aggregated Historical Statistics description: Retrieves aggregated historical traffic statistics security: - - QueryKeyAuth: [] + - BearerAuth: [] parameters: - name: range in: query @@ -1183,8 +1282,16 @@ paths: required: false schema: type: string - enum: ["1m", "1h", "1d", "week", "quarter"] + enum: ["1m", "1h", "1d", "week", "month", "quarter"] example: "1h" + - name: mode + in: query + description: Output mode (`count`/default = packet count per bucket, `pps` = packets per second) + required: false + schema: + type: string + enum: ["count", "pps"] + example: "count" responses: "200": description: Aggregated statistics retrieved successfully @@ -1205,12 +1312,51 @@ paths: schema: $ref: '#/components/schemas/GenericError' + /sessions: + get: + summary: List currently auto-whitelisted sessions + description: Retrieves active whitelist sessions, optionally filtered by destination IP. + security: + - BearerAuth: [] + parameters: + - name: dst + in: query + description: Destination IP to filter results + required: false + schema: + type: string + responses: + "200": + description: Sessions retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/SessionsResponse' + "400": + description: Bad request - Invalid dst IP address + content: + application/json: + schema: + $ref: '#/components/schemas/GenericError' + "401": + description: Unauthorized - Invalid or missing API key + content: + application/json: + schema: + $ref: '#/components/schemas/GenericError' + "500": + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/GenericError' + /attacks: get: summary: List Current Active Attacks description: Retrieves currently active attack information security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Active attacks retrieved successfully @@ -1236,7 +1382,7 @@ paths: summary: Get Attack History description: Retrieves historical attack data for specific IP security: - - QueryKeyAuth: [] + - BearerAuth: [] parameters: - name: ip in: query @@ -1265,12 +1411,48 @@ paths: schema: $ref: '#/components/schemas/GenericError' + + + /dest-ports: + get: + summary: Destination ports under attack + description: Lists destination ports seen in connection state for a target IP + security: + - BearerAuth: [] + parameters: + - name: ip + in: query + description: Destination IP to query + required: true + schema: + type: string + example: "203.0.113.5" + responses: + "200": + description: Ports data retrieved successfully + content: + application/json: + schema: + $ref: '#/components/schemas/DestPortsResponse' + "401": + description: Unauthorized - Invalid or missing API key + content: + application/json: + schema: + $ref: '#/components/schemas/GenericError' + "500": + description: Internal server error + content: + application/json: + schema: + $ref: '#/components/schemas/GenericError' + /logs: get: summary: Get System Logs description: Retrieves system and security logs security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: System logs retrieved successfully @@ -1296,7 +1478,7 @@ paths: summary: Get System Status description: Retrieves current TMW Shield system status and configuration security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: System status retrieved successfully @@ -1322,7 +1504,7 @@ paths: summary: List AbuseIPDB Blocked IPs description: Retrieves all AbuseIPDB blocklist entries security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: AbuseIPDB list retrieved successfully @@ -1347,7 +1529,7 @@ paths: summary: Add IP to AbuseIPDB Blocklist description: Adds an IP to the AbuseIPDB blocklist security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1391,7 +1573,7 @@ paths: summary: Remove IP from AbuseIPDB Blocklist description: Removes an IP from the AbuseIPDB blocklist security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1442,7 +1624,7 @@ paths: summary: List AbuseIPDB Enabled Destinations description: Retrieves all destinations with AbuseIPDB check enabled security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: AbuseIPDB config retrieved successfully @@ -1467,7 +1649,7 @@ paths: summary: Enable AbuseIPDB Check for Destination description: Enables AbuseIPDB check for a destination IP security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1516,7 +1698,7 @@ paths: summary: Disable AbuseIPDB Check for Destination description: Disables AbuseIPDB check for a destination IP security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1529,7 +1711,6 @@ paths: dst: type: string description: Destination IP address - example: "10.0.0.1" responses: "204": description: AbuseIPDB check disabled successfully @@ -1567,7 +1748,7 @@ paths: summary: List Webhooks description: Retrieves all configured webhooks security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Webhooks retrieved successfully @@ -1592,7 +1773,7 @@ paths: summary: Add Webhook description: Adds a new webhook for attack notifications security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1639,27 +1820,33 @@ paths: delete: summary: Remove Webhook - description: Removes a webhook + description: Removes a webhook (accepts query parameters or JSON body with identical fields) security: - - QueryKeyAuth: [] + - BearerAuth: [] + parameters: + - name: target + in: query + required: true + schema: + type: string + description: Target IP or CIDR + - name: url + in: query + required: true + schema: + type: string + description: Webhook URL to remove requestBody: - required: true + required: false content: application/json: schema: type: object - required: - - target - - url properties: target: type: string - description: Target IP or CIDR - example: "192.168.1.100" url: type: string - description: Webhook URL to remove - example: "https://example.com/webhook" responses: "204": description: Webhook removed successfully @@ -1697,7 +1884,7 @@ paths: summary: List Email Notifications description: Retrieves all configured email notifications security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Email notifications retrieved successfully @@ -1722,7 +1909,7 @@ paths: summary: Add Email Notification description: Adds a new email notification for attacks security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1771,7 +1958,7 @@ paths: summary: Remove Email Notification description: Removes an email notification security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1827,7 +2014,7 @@ paths: summary: Get SMTP Configuration description: Retrieves the SMTP server configuration security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: SMTP configuration retrieved successfully @@ -1852,7 +2039,7 @@ paths: summary: Configure SMTP description: Configures the SMTP server settings security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1917,7 +2104,7 @@ paths: summary: Check IP Threat description: Checks an IP address for threats security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -1962,7 +2149,7 @@ paths: summary: Get Cluster Status description: Retrieves current cluster membership status and statistics security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Cluster status retrieved successfully @@ -1988,7 +2175,7 @@ paths: summary: List Cluster Nodes description: Retrieves all nodes in the cluster security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Cluster nodes retrieved successfully @@ -2014,7 +2201,7 @@ paths: summary: Join Cluster description: Joins the node to an existing cluster via a seed node security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: true content: @@ -2060,7 +2247,7 @@ paths: summary: Leave Cluster description: Gracefully leaves the current cluster security: - - QueryKeyAuth: [] + - BearerAuth: [] responses: "200": description: Successfully left cluster @@ -2092,7 +2279,7 @@ paths: summary: Trigger Cluster Sync description: Requests full state synchronization from all nodes or a specific node security: - - QueryKeyAuth: [] + - BearerAuth: [] requestBody: required: false content: @@ -2126,2113 +2313,4 @@ paths: application/json: schema: $ref: '#/components/schemas/GenericError' -``` - ---- - -## Quick Examples - -### Check Status - -```bash -curl -H "Authorization: Bearer YOUR_KEY" http://localhost:8081/api/v2/status -``` - -### Blacklist IP - -```bash -curl -X POST -H "Authorization: Bearer YOUR_KEY" \ - -H "Content-Type: application/json" \ - -d '{"src":"1.2.3.4","dst":"5.6.7.8","direction":"both"}' \ - "http://localhost:8081/api/v2/blacklists" -``` - -### Statistics & Monitoring - -```bash -# Get live statistics -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/stats/live" - -# Get per-IP statistics -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/stats/per-ip?ip=203.0.113.5" - -# Get aggregated statistics -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/stats/aggregated?range=1h" - -# Get current attacks -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/attacks" - -# Get attack history -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/attacks/history?ip=203.0.113.5" - -# Get system logs -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/logs" - -# Get system status -curl -X GET -H "Authorization: Bearer YOUR_KEY" \ - "http://localhost:8081/api/v2/status" -``` - ---- - -# API Endpoints - ---- - -## 1. Instance Status - -### GET /api/v2/status - -Retrieves the current TMW Shield instance status. - -**Request:** - -```bash -curl -H "Authorization: Bearer YOUR_KEY" http://127.0.0.1:8081/api/v2/status -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "status": "ok" -} -``` - -**Possible Status Values:** - -- `ok` - Instance running normally -- `degraded` - Reduced functionality -- `error` - Error present - ---- - -## 2. Statistics - -### GET /api/stats/live - -Retrieves global real-time statistics including cumulative counters, current PPS rates, and validation statistics. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/stats/live -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "counters": { - "syn_received": 123456, - "syn_dropped": 1234, - "syn_allowed": 122222, - "syn_cookies_sent": 500, - "ack_packets_dropped": 50, - "ack_validated": 450, - "syn_ack_blocked": 10, - "unsolicited_syn_ack_blocked": 5, - "rst_blocked": 2, - "fin_blocked": 1, - "ip_whitelist_passed": 1000, - "udp_allowed": 50000, - "udp_blocked": 500, - "icmp_allowed": 100, - "icmp_blocked": 20, - "gre_allowed": 0, - "gre_blocked": 0, - "amp_allowed": 0, - "amp_blocked": 0, - "carpet_udp_blocked": 0, - "carpet_syn_blocked": 0, - "carpet_icmp_blocked": 0, - "fragments_blocked": 0 - }, - "current": { - "dropped_pps": 120, - "allowed_pps": 4500, - "validated_pps": 150 - }, - "validated": { - "syn_cookies_sent": 40, - "ack_validated": 100, - "ip_whitelist_passed": 10 - } -} -``` - -**Response Schema:** - -| Field | Type | Description | -| ----------------------------- | ------- | --------------------------------------------- | -| `counters` | object | Cumulative counters since system start | -| `counters.syn_received` | integer | All received SYN packets | -| `counters.syn_dropped` | integer | All dropped SYN packets | -| `counters.syn_allowed` | integer | All allowed SYN packets | -| `counters.syn_cookies_sent` | integer | All sent SYN cookies | -| `counters.ack_validated` | integer | All validated ACK packets | -| `counters.udp_blocked` | integer | All blocked UDP packets | -| `counters.ip_whitelist_passed`| integer | Packets that passed IP whitelist | -| `current` | object | Current packets per second rates | -| `current.dropped_pps` | integer | Current dropped packets/second | -| `current.allowed_pps` | integer | Current allowed packets/second | -| `current.validated_pps` | integer | Current validated packets/second | -| `validated` | object | Short-term validation statistics | - ---- - -### GET /api/stats/aggregated - -Retrieves aggregated statistics over a specific time range. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/stats/aggregated?range=1h' -``` - -**Query Parameter:** - -| Parameter | Type | Required | Description | Default | -| --------- | ------ | -------- | -------------------------------------------------------------------- | ------- | -| `range` | string | No | Time range: `1m`, `min`, `1h`, `hour`, `1d`, `day`, `month`, `week`, `quarter` | `1h` | - -**Range Details:** - -| Value | Meaning | Data Points | -| ---------------------- | ------------------ | ---------------------- | -| `1m`, `min` | Last 60 minutes | 60 points (1 min each) | -| `1h`, `hour` | Last 24 hours | 24 points (1 hour each) | -| `1d`, `day`, `month` | Last 30 days | 30 points (1 day each) | -| `week` | Last 7 days | 7 points (1 day each) | -| `quarter` | Last 90 days | 90 points (1 day each) | - -**Response (200 OK):** - -```json -{ - "allowed": [12, 10, 15, 8, 20], - "dropped": [0, 1, 0, 2, 1], - "validated": [8, 7, 9, 5, 11], - "activeProtections": [], - "sentProtections": [], - "activeAttacks": [], - "note": "Less than 90 days available" -} -``` - -**Response Schema:** - -| Field | Type | Description | -| -------------------- | ---------------- | ------------------------------------------------ | -| `allowed` | array[integer] | Allowed packets per time interval | -| `dropped` | array[integer] | Dropped packets per time interval | -| `validated` | array[integer] | Validated packets per time interval | -| `activeProtections` | array | Current protection measures | -| `sentProtections` | array | Sent webhooks | -| `activeAttacks` | array | Active attacks | -| `note` | string | _(optional)_ Notes (e.g., for incomplete data) | - ---- - -### GET /api/stats/per-ip - -Retrieves detailed statistics per protected source IP. This endpoint shows both current packets per second (pps) and cumulative total counters. - -**Request:** - -```bash -# Get all IPs -curl http://127.0.0.1:8081/api/stats/per-ip - -# Get only a specific IP -curl http://127.0.0.1:8081/api/stats/per-ip?ip=1.2.3.4 -``` - -**Query Parameter:** - -| Parameter | Type | Required | Description | -| --------- | ------ | -------- | -------------------------------------------------------- | -| `ip` | string | No | Filters the output for a specific IPv4 address. | - -**Response (200 OK):** - -```json -[ - { - "ip": "203.0.113.5", - "pps": { - "tcp_received": 100, - "udp_received": 50, - "icmp_received": 0, - "gre_received": 0, - "syn_received": 10, - "syn_allowed": 10, - "syn_dropped": 0, - "ack_received": 80, - "ack_validated": 80, - "ack_dropped": 0, - "syn_ack_blocked": 0, - "unsolicited_syn_ack_blocked": 0, - "unsolicited_syn_ack_allowed": 0, - "rst_blocked": 0, - "rst_allowed": 0, - "fin_blocked": 0, - "fin_allowed": 0, - "psh_flood_blocked": 0, - "urg_blocked": 0, - "tcp_invalid_flags_blocked": 0, - "udp_blocked": 0, - "udp_new_ip_blocked": 0, - "icmp_blocked": 0, - "gre_blocked": 0, - "gre_new_ip_blocked": 0, - "amp_blocked": 0, - "fragments_blocked": 0, - "malformed_packets": 0, - "rate_limited": 0, - "ip_blacklist_dropped": 0, - "carpet_udp_blocked": 0, - "carpet_syn_blocked": 0, - "carpet_syn_ack_blocked": 0, - "carpet_amp_blocked": 0, - "carpet_icmp_blocked": 0, - "udp_allowed": 50, - "icmp_allowed": 0, - "gre_allowed": 0, - "fragments_allowed": 0, - "tcp_dropped": 0, - "udp_dropped": 0, - "icmp_dropped": 0, - "gre_dropped": 0, - "total_dropped": 0, - "total_allowed": 150 - }, - "total": { - "syn_received": 1234, - "ack_received": 5678, - "udp_blocked": 12, - "icmp_blocked": 0, - "gre_blocked": 0, - "total_dropped": 12, - "total_allowed": 100000 - } - } -] -``` - -**Response Schema (Array Items):** - -| Field | Type | Description | -| --------------------- | ------- | ----------------------------------------------------- | -| `ip` | string | Source IPv4 address | -| `pps` | object | Current statistics (Deltas/Second) | -| `pps.tcp_received` | integer | Received TCP packets | -| `pps.udp_received` | integer | Received UDP packets | -| `pps.syn_received` | integer | Received SYN packets | -| `pps.syn_allowed` | integer | Allowed SYN packets | -| `pps.syn_dropped` | integer | Dropped SYN packets | -| `pps.ack_validated` | integer | Validated ACK packets | -| `pps.udp_blocked` | integer | Blocked UDP packets | -| `pps.total_dropped` | integer | Total dropped packets | -| `pps.total_allowed` | integer | Total allowed packets | -| `total` | object | Cumulative total counters (since recording started) | -| `total.syn_received` | integer | Total received SYN packets | -| `total.total_dropped` | integer | Total dropped packets | -| `total.total_allowed` | integer | Total allowed packets | - ---- - -## 3. Blacklist Management - -### GET /api/blacklist/add - -Adds a blacklist entry. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/blacklist/add?src=1.2.3.4&dst=5.6.7.8&direction=both' -``` - -**Query Parameter:** - -| Parameter | Type | Required | Description | Range | -| ----------- | ------ | -------- | ------------------------------- | -------------------- | -| `src` | string | Yes | Source IP address or CIDR block | IPv4 format | -| `dst` | string | Yes | Destination IP address or CIDR block | IPv4 format | -| `direction` | string | No | Filter direction | `src`, `dst`, `both` | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Added to blacklist" -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "Invalid IP address format" -} -``` - ---- - -### GET /api/blacklist/remove - -Removes a blacklist entry. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/blacklist/remove?src=1.2.3.4&dst=5.6.7.8' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------- | -| `src` | string | Yes | Source-IP-Adresse | -| `dst` | string | Yes | Destination-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Removed from blacklist" -} -``` - ---- - -### GET /api/blacklist/list - -Lists all blacklist entries. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/blacklist/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "blacklist_entries": [ - { - "src": "1.2.3.4", - "dst": "5.6.7.8", - "direction": "both", - "type": "IP", - "interfaces": ["eth0"] - } - ] -} -``` - -**Response Schema (Array Items):** - -| Feld | Type | Description | -| ------------ | ------------- | -------------------------------- | -| `src` | string | Source-IP/CIDR | -| `dst` | string | Destination-IP/CIDR | -| `direction` | string | Filter direction | -| `type` | string | Entry type (usually `IP`) | -| `interfaces` | array[string] | Affected network interfaces | - ---- - -## 4. Whitelist Management - -### GET /api/whitelist/add - -Adds a whitelist entry. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/whitelist/add?src=192.168.1.0&dst=10.0.0.0/24&direction=src' -``` - -**Query Parameter:** - -| Parameter | Type | Required | Description | -| ----------- | ------ | -------- | ----------------------------------- | -| `src` | string | Yes | Source IP address or CIDR block | -| `dst` | string | Yes | Destination IP address or CIDR block | -| `direction` | string | No | Filter direction (`src`, `dst`, `both`) | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Added to whitelist" -} -``` - ---- - -### GET /api/whitelist/remove - -Removes a whitelist entry. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/whitelist/remove?src=192.168.1.0&dst=10.0.0.0/24' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------- | -| `src` | string | Yes | Source-IP-Adresse | -| `dst` | string | Yes | Destination-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Removed from whitelist" -} -``` - ---- - -### GET /api/whitelist/list - -Lists all whitelist entries. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/whitelist/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "whitelist_entries": [ - { - "src": "192.168.1.0", - "dst": "10.0.0.0/24", - "direction": "src", - "type": "IP", - "interfaces": ["eth0", "eth1"] - } - ] -} -``` - -**Response Schema (Array Items):** - -| Feld | Type | Description | -| ------------ | ------------- | ------------------------------ | -| `src` | string | Source-IP/CIDR | -| `dst` | string | Destination-IP/CIDR | -| `direction` | string | Filter direction | -| `type` | string | Eintragstyp | -| `interfaces` | array[string] | Affected network interfaces | - ---- - -## 5. Protocol Allow (IP/Proto Management) - -### GET /api/protocol_allow/add - -Allows a network protocol for a destination IP. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/protocol_allow/add?dst=10.0.0.5&proto=6' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------- | ------------ | --------------------- | -| `dst` | string | Yes | Destination-IP-Adresse | -| `proto` | integer | Yes | IANA protocol number | - -**Common Protocol Numbers:** - -| Number | Name | Description | -| ------ | ---- | --------------------------------- | -| 1 | ICMP | Internet Control Message Protocol | -| 6 | TCP | Transmission Control Protocol | -| 17 | UDP | User Datagram Protocol | -| 47 | GRE | Generic Routing Encapsulation | -| 41 | IPv6 | IPv6 Encapsulation | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Protocol allowed", - "added_on": 1 -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to add protocol allow" -} -``` - ---- - -### GET /api/protocol_allow/remove - -Removes a protocol from the allow list. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/protocol_allow/remove?dst=10.0.0.5&proto=6' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------- | ------------ | --------------------- | -| `dst` | string | Yes | Destination-IP-Adresse | -| `proto` | integer | Yes | IANA protocol number | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Protocol removed" -} -``` - ---- - -### GET /api/protocol_allow/list - -Lists all allowed protocols. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/protocol_allow/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "protocol_allow_entries": [ - { - "dst": "10.0.0.5", - "proto": 6, - "interfaces": ["eth0"] - }, - { - "dst": "10.0.0.10", - "proto": 17, - "interfaces": ["eth0", "eth1"] - } - ] -} -``` - -**Response Schema (Array Items):** - -| Feld | Type | Description | -| ------------ | ------------- | ------------------------------ | -| `dst` | string | Destination-IP-Adresse | -| `proto` | integer | IANA protocol number | -| `interfaces` | array[string] | Affected network interfaces | - ---- - -## 6. VLAN Bypass - -### GET /api/bypass_vlan/add - -Enables VLAN bypass for a VLAN ID (bypasses protection for this VLAN). - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/bypass_vlan/add?vlan=100' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | Range | -| --------- | ------- | ------------ | ------------------- | ------------ | -| `vlan` | integer | Yes | VLAN-Identifikation | 0-4095 | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "VLAN bypass added", - "enabled_on": 1 -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to enable vlan bypass" -} -``` - ---- - -### GET /api/bypass_vlan/remove - -Disables VLAN bypass for a VLAN ID. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/bypass_vlan/remove?vlan=100' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------- | ------------ | ------------------- | -| `vlan` | integer | Yes | VLAN-Identifikation | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "VLAN bypass removed" -} -``` - ---- - -### GET /api/bypass_vlan/list - -Lists all VLAN bypass entries. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/bypass_vlan/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "bypass_vlan_entries": [ - { - "vlan": 100, - "interfaces": ["eth0", "eth0.100"] - }, - { - "vlan": 200, - "interfaces": ["eth0", "eth0.200"] - } - ] -} -``` - -**Response Schema (Array Items):** - -| Feld | Type | Description | -| ------------ | ------------- | ------------------------------ | -| `vlan` | integer | VLAN-Identifikation | -| `interfaces` | array[string] | Affected network interfaces | - ---- - -## 7. AbuseIPDB Integration - -### GET /api/abuseipdb/enable - -Enables AbuseIPDB check for a destination IP. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/abuseipdb/enable?dst=10.0.0.1' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | --------------- | -| `dst` | string | Yes | Destination-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "enabled_on": 1 -} -``` - ---- - -### GET /api/abuseipdb/disable - -Disables AbuseIPDB check for a destination IP. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/abuseipdb/disable?dst=10.0.0.1' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | --------------- | -| `dst` | string | Yes | Destination-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "AbuseIPDB disabled" -} -``` - ---- - -### GET /api/abuseipdb/add - -Adds an IP to the AbuseIPDB blocklist. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/abuseipdb/add?src=198.51.100.7' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------- | -| `src` | string | Yes | Source-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "IP added to AbuseIPDB blocklist", - "added_on": 1 -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to add IP to abuseipdb" -} -``` - ---- - -### GET /api/abuseipdb/remove - -Removes an IP from the AbuseIPDB blocklist. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/abuseipdb/remove?src=198.51.100.7' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------- | -| `src` | string | Yes | Source-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "IP removed from AbuseIPDB blocklist" -} -``` - ---- - -### GET /api/abuseipdb/clear - -Deletes all AbuseIPDB entries (blocklist and destinations). - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/abuseipdb/clear -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "AbuseIPDB entries cleared" -} -``` - ---- - -### GET /api/abuseipdb/list - -Lists all AbuseIPDB configurations. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/abuseipdb/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "blocked_ips": [ - { - "ip": "198.51.100.7", - "interfaces": ["eth0"] - } - ], - "enabled_destinations": [ - { - "ip": "10.0.0.1", - "interfaces": ["eth0"] - } - ] -} -``` - -**Response Schema:** - -| Field | Type | Description | -| ---------------------- | ----- | ------------------------------------------- | -| `blocked_ips` | array | IPs on AbuseIPDB blocklist | -| `enabled_destinations` | array | Destinations with AbuseIPDB check enabled | - ---- - -## 8. IP Check (Quick Lookup) - -### GET /api/check_ip - -Performs a quick check whether an IP connection is in whitelist or blacklist. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/check_ip?src=192.168.1.100&dst=10.0.0.1' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------- | -| `src` | string | Yes | Source-IP-Adresse | -| `dst` | string | Yes | Destination-IP-Adresse | - -**Response (200 OK):** - -```json -{ - "success": true, - "blacklisted": false, - "whitelisted": true -} -``` - -**Response Schema:** - -| Feld | Type | Description | -| ------------- | ------- | ------------------------------ | -| `success` | boolean | Anfrage erfolgreich bearbeitet | -| `blacklisted` | boolean | Verbindung ist auf Blacklist | -| `whitelisted` | boolean | Verbindung ist auf Whitelist | - ---- - -## 9. Logs & Monitoring - -### GET /api/logs - -Retrieves a list of active protections and the history of sent webhook notifications. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/logs -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "activeProtections": [ - { - "type": "syn_flood", - "target": "10.0.0.1", - "pps": 12345, - "last_seen": 1600000000, - "raw": "Mitigation active for 10.0.0.1 (syn_flood)" - } - ], - "sentProtections": [ - { - "type": "syn_flood", - "target": "10.0.0.1", - "pps": 12000, - "timestamp": 1600000000, - "status": "sent", - "response_code": 200, - "error": "none", - "hook": "https://hooks.example/attack" - } - ] -} -``` - -**activeProtections Schema:** - -| Feld | Type | Description | -| ----------- | ------- | ------------------------------------ | -| `type` | string | Schutztyp (z.B. `syn_flood`) | -| `target` | string | Destination-IP-Adresse | -| `pps` | integer | Packets per second | -| `last_seen` | integer | Unix timestamp of last activity | -| `raw` | string | _(optional)_ Roh-Logzeile | - -**sentProtections Schema:** - -| Feld | Type | Description | -| --------------- | ------- | ------------------------------------ | -| `type` | string | Schutztyp | -| `target` | string | Destination-IP-Adresse | -| `pps` | integer | Packets per second | -| `timestamp` | integer | Unix timestamp of the webhook sent | -| `status` | string | Webhook-Status (z.B. `sent`) | -| `response_code` | integer | HTTP status response from the hook | -| `error` | string | Fehlerbeschreibung (falls vorhanden) | -| `hook` | string | Verwendete Webhook-URL | - ---- - -### GET /api/attacks - -Lists all currently detected and active attacks on the system live. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/attacks -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "attacks": [ - { - "attack_type": "TCP SYN", - "target_ip": "77.90.25.153", - "dropped_pps": 417330, - "gbps": 0.21367296, - "first_seen": 1769030407, - "last_seen": 1769030422 - } - ] -} -``` - -**Attack Schema (Array Items):** - -| Feld | Type | Description | -| ------------------ | ------- | ------------------------------------------------ | -| `attack_type` | string | Attack type (e.g., `syn_flood`, `udp_flood`) | -| `target_ip` | string | Primary target of the attack | -| `dropped_pps` | integer | Current drop rate in packets per second | -| `gbps` | number | Current attack bandwidth in Gbit/s | -| `first_seen` | integer | Unix timestamp of first detection | -| `last_seen` | integer | Unix timestamp of last activity | - ---- - -### GET /api/attacks/history - -Retrieves the attack history of the last 24 hours. - -**Request:** - -```bash -# All attacks of the last 24h -curl http://127.0.0.1:8081/api/attacks/history - -# Attacks for a specific IP -curl http://127.0.0.1:8081/api/attacks/history?ip=77.90.25.153 -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ---------------------------------------------------- | -| `ip` | string | No | Filtert die Ausgabe nach einer spezifischen Destination-IP. | - -**Response (200 OK):** - -```json -{ - "success": true, - "attacks": [ - { - "attack_type": "TCP (SYN)", - "target_ip": "77.90.25.153", - "peak_pps": 596000, - "peak_gbps": 0.31, - "start": 1737372108, - "end": 1737372144, - "duration": 36, - "protocols": "TCP (SYN)", - "start_iso": "2026-01-20T11:21:48Z", - "end_iso": "2026-01-20T11:22:24Z" - } - ] -} -``` - -**Attack History Schema (Array Items):** - -| Feld | Type | Description | -| ------------- | ------- | -------------------------------------- | -| `attack_type` | string | Attack type | -| `target_ip` | string | Target IP of the attack | -| `peak_pps` | integer | Highest measured packets per second | -| `peak_gbps` | number | Highest measured bandwidth in Gbit/s | -| `start` | integer | Unix timestamp of attack start | -| `end` | integer | Unix timestamp of attack end | -| `duration` | integer | Duration of the attack in seconds | -| `protocols` | string | Identified protocols | -| `start_iso` | string | ISO 8601 timestamp of start | -| `end_iso` | string | ISO 8601 timestamp of end | - ---- - -## 10. Webhooks (Attack Notifications) - -### GET /api/webhook/add - -Registers a webhook for attack notifications. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/webhook/add?target=10.0.0.1&url=https%3A%2F%2Fhooks.example%2Fattack' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | --------------------------------------- | -| `target` | string | Yes | Target IP, CIDR block, or `*` (for all) | -| `url` | string | Yes | Webhook-URL (URL-encoded) | - -**Response (200 OK) - Neuer Webhook:** - -```json -{ - "success": true, - "message": "Webhook added" -} -``` - -**Response (200 OK) - Webhook existiert bereits:** - -```json -{ - "success": true, - "message": "Webhook already present" -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to add webhook" -} -``` - ---- - -### GET /api/webhook/list - -Lists all registered webhooks. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/webhook/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "webhooks": { - "10.0.0.1": ["https://hooks.example/attack"], - "10.0.0.0/24": ["https://internal.example/notification"], - "*": ["https://hooks.example/global"] - } -} -``` - -**Response Schema:** - -| Feld | Type | Description | -| ---------- | ------ | ------------------------------- | -| `webhooks` | object | Webhooks grouped by target IP | - ---- - -### GET /api/webhook/delete - -Removes a registered webhook. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/webhook/delete?target=10.0.0.1&url=https%3A%2F%2Fhooks.example%2Fattack' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------ | ------------ | ------------------------- | -| `target` | string | Yes | Destination-IP, CIDR oder `*` | -| `url` | string | Yes | Webhook-URL (URL-encoded) | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Webhook deleted" -} -``` - -**Response (404 Not Found):** - -```json -{ - "success": false, - "error": "Webhook not found" -} -``` - ---- - -## 11. Service Ports - -### GET /api/service_ports/add - -Adds a service port to all interfaces. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/service_ports/add?port=8443' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | Range | -| --------- | ------- | ------------ | ------------ | ------------ | -| `port` | integer | Yes | Port number | 1-65535 | - -**Response (200 OK):** - -```json -{ - "success": true, - "added_on": 1, - "message": "Port added to all interfaces" -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to add port" -} -``` - ---- - -### GET /api/service_ports/remove - -Entfernt einen Service-Port von allen Interfaces. - -**Request:** - -```bash -curl 'http://127.0.0.1:8081/api/service_ports/remove?port=8443' -``` - -**Query Parameter:** - -| Parameter | Typ | Required | Description | -| --------- | ------- | ------------ | ------------ | -| `port` | integer | Yes | Port number | - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "Port removed", - "removed_on": 1 -} -``` - -**Response (400 Bad Request):** - -```json -{ - "success": false, - "error": "failed to remove port" -} -``` - ---- - -### GET /api/service_ports/list - -Lists all service ports by interface. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/service_ports/list -``` - -**Parameter:** None - -**Response (200 OK):** - -```json -{ - "success": true, - "interfaces": [ - { - "name": "eth0", - "ports": [22, 80, 443, 8443] - }, - { - "name": "eth1", - "ports": [22, 80, 443] - } - ] -} -``` - -**Response Schema (Interface Items):** - -| Feld | Type | Description | -| ------- | -------------- | ---------------------- | -| `name` | string | Interface-Name | -| `ports` | array[integer] | Array of port numbers | - ---- - -# REST API v2 Specification - -## Overview - -The TMW Shield REST API v2 implements proper REST principles with: -- **Resource-based URLs** using nouns instead of verbs -- **Proper HTTP methods** (GET, POST, DELETE) for different operations -- **JSON request/response bodies** instead of query parameters for state changes -- **Appropriate HTTP status codes** (200, 201, 204, 400, 404, 401) -- **Consistent error handling** with structured JSON responses - -## Base URL - -``` -http://{instance_ip}:8081/api/v2 -``` - -## Authentication - -All endpoints require Bearer token authentication: - -``` -Authorization: Bearer YOUR_API_KEY -``` - -## Common Response Format - -**Success Response:** -```json -{ - "success": true, - "message": "Operation completed successfully", - "data": { ... } // Only for GET requests -} -``` - -**Error Response:** -```json -{ - "success": false, - "error": "Error description" -} -``` - -## Endpoints - -### 1. Blacklist Management - -#### POST /api/v2/blacklists -Creates a new blacklist entry. - -**Request Body:** -```json -{ - "src": "1.2.3.4", - "dst": "5.6.7.8", - "direction": "both" // optional: "src", "dst", "both" (default: "both") -} -``` - -**Response (201 Created):** -```json -{ - "success": true, - "message": "Blacklist entry created" -} -``` - -#### GET /api/v2/blacklists -Lists all blacklist entries. - -**Response (200 OK):** -```json -{ - "success": true, - "data": [ - { - "interface": "eth0", - "entries": [ - { - "src": "1.2.3.4", - "dst": "5.6.7.8", - "direction": 2 - } - ] - } - ] -} -``` - -#### DELETE /api/v2/blacklists -Removes a blacklist entry. - -**Request Body:** -```json -{ - "src": "1.2.3.4", - "dst": "5.6.7.8" -} -``` - -**Response (204 No Content):** -```json -{ - "success": true, - "message": "Blacklist entry deleted" -} -``` - ---- - -### 2. Whitelist Management - -#### POST /api/v2/whitelists -Creates a new whitelist entry. - -**Request Body:** -```json -{ - "src": "1.2.3.4", - "dst": "5.6.7.8", - "direction": "both" // optional: "src", "dst", "both" (default: "both") -} -``` - -**Response (201 Created):** -```json -{ - "success": true, - "message": "Whitelist entry created" -} -``` - -#### GET /api/v2/whitelists -Lists all whitelist entries. - -**Response (200 OK):** -```json -{ - "success": true, - "data": [ - { - "interface": "eth0", - "entries": [ - { - "src": "1.2.3.4", - "dst": "5.6.7.8", - "direction": 2 - } - ] - } - ] -} -``` - -#### DELETE /api/v2/whitelists -Removes a whitelist entry. - -**Request Body:** -```json -{ - "src": "1.2.3.4", - "dst": "5.6.7.8" -} -``` - -**Response (204 No Content):** -```json -{ - "success": true, - "message": "Whitelist entry deleted" -} -``` - ---- - -### 3. Protocol Management - -#### POST /api/v2/protocols -Creates a protocol allow entry. - -**Request Body:** -```json -{ - "dst": "5.6.7.8", - "protocol": 17 // protocol number (e.g., 17 for UDP) -} -``` - -**Response (201 Created):** -```json -{ - "success": true, - "message": "Protocol allow entry created" -} -``` - -#### GET /api/v2/protocols -Lists all protocol allow entries. - -**Response (200 OK):** -```json -{ - "success": true, - "data": [ - { - "interface": "eth0", - "entries": [ - { - "dst": "5.6.7.8", - "protocol": 17 - } - ] - } - ] -} -``` - -#### DELETE /api/v2/protocols -Removes a protocol allow entry. - -**Request Body:** -```json -{ - "dst": "5.6.7.8", - "protocol": 17 -} -``` - -**Response (204 No Content):** -```json -{ - "success": true, - "message": "Protocol allow entry deleted" -} -``` - ---- - -### 4. Service Ports Management - -#### POST /api/v2/service-ports -Adds a service port. - -**Request Body:** -```json -{ - "port": 8080 -} -``` - -**Response (201 Created):** -```json -{ - "success": true, - "message": "Service port added" -} -``` - -#### GET /api/v2/service-ports -Lists all service ports. - -**Response (200 OK):** -```json -{ - "success": true, - "data": [ - { - "interface": "eth0", - "ports": [22, 80, 443, 8080] - } - ] -} -``` - -#### DELETE /api/v2/service-ports -Removes a service port. - -**Request Body:** -```json -{ - "port": 8080 -} -``` - -**Response (204 No Content):** -```json -{ - "success": true, - "message": "Service port removed" -} -``` - ---- - -### 5. VLAN Management - -#### POST /api/v2/vlans -Adds a VLAN bypass entry. - -**Request Body:** -```json -{ - "vlan": 100 -} -``` - -**Response (201 Created):** -```json -{ - "success": true, - "message": "VLAN bypass added" -} -``` - -#### GET /api/v2/vlans -Lists all VLAN bypass entries. - -**Response (200 OK):** -```json -{ - "success": true, - "data": [ - { - "interface": "eth0", - "vlans": [100, 200, 300] - } - ] -} -``` - -#### DELETE /api/v2/vlans -Removes a VLAN bypass entry. - -**Request Body:** -```json -{ - "vlan": 100 -} -``` - -**Response (204 No Content):** -```json -{ - "success": true, - "message": "VLAN bypass removed" -} -``` - ---- - -## AbuseIPDB Integration API (v2) - -### POST /api/v2/abuseipdb - -Adds an IP to the AbuseIPDB blocklist. - -**Request Body:** - -```json -{ - "src": "198.51.100.7" -} -``` - -**Response (201 Created):** - -```json -{ - "success": true, - "message": "IP added to AbuseIPDB blocklist" -} -``` - ---- - -### GET /api/v2/abuseipdb - -Lists all AbuseIPDB blocklist entries. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/v2/abuseipdb -``` - ---- - -### DELETE /api/v2/abuseipdb - -Removes an IP from the AbuseIPDB blocklist. - -**Request Body:** - -```json -{ - "src": "198.51.100.7" -} -``` - -**Response (204 No Content):** - -```json -{ - "success": true, - "message": "IP removed from AbuseIPDB blocklist" -} -``` - ---- - -### POST /api/v2/abuseipdb/config - -Enables or disables AbuseIPDB check for a destination IP. - -**Request Body:** - -```json -{ - "dst": "10.0.0.1", - "enable": true -} -``` - -**Response (200 OK):** - -```json -{ - "success": true, - "message": "AbuseIPDB check enabled" -} -``` - ---- - -### GET /api/v2/abuseipdb/config - -Lists all configured AbuseIPDB destinations. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/v2/abuseipdb/config -``` - ---- - -### DELETE /api/v2/abuseipdb/config - -Disables AbuseIPDB check for a destination IP. - -**Request Body:** - -```json -{ - "dst": "10.0.0.1" -} -``` - ---- - -## Webhooks API (v2) - -### POST /api/v2/webhooks - -Adds a new webhook. - -**Request Body:** - -```json -{ - "target": "192.168.1.100", - "url": "https://example.com/webhook" -} -``` - ---- - -### GET /api/v2/webhooks - -Lists all webhooks. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/v2/webhooks -``` - ---- - -### DELETE /api/v2/webhooks - -Deletes a webhook. - -**Request Body:** - -```json -{ - "target": "192.168.1.100", - "url": "https://example.com/webhook" -} -``` - ---- - -## Email Notifications API (v2) - -### POST /api/v2/emails - -Adds an email notification. - -**Request Body:** - -```json -{ - "target": "192.168.1.100", - "email": "admin@example.com" -} -``` - ---- - -### GET /api/v2/emails - -Lists all email notifications. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/v2/emails -``` - ---- - -### DELETE /api/v2/emails - -Deletes an email notification. - -**Request Body:** - -```json -{ - "target": "192.168.1.100", - "email": "admin@example.com" -} -``` - ---- - -## SMTP Configuration API (v2) - -### POST /api/v2/smtp - -Konfiguriert den SMTP-Server. - -**Request Body:** - -```json -{ - "server": "smtp.example.com", - "port": 587, - "user": "smtp_user", - "pass": "smtp_password", - "from": "shield@example.com" -} -``` - ---- - -### GET /api/v2/smtp - -Zeigt die SMTP-Konfiguration an. - -**Request:** - -```bash -curl http://127.0.0.1:8081/api/v2/smtp -``` - ---- - -## IP Check API (v2) - -### POST /api/v2/check-ip - -Checks an IP address for threats. - -**Request Body:** - -```json -{ - "ip": "198.51.100.7" -} -``` - -**Response (200 OK):** - -```json -{ - "ip": "198.51.100.7", - "blocked": false, - "source": "local" -} -``` - ---- - -## Cluster API (v2) - -Endpoints for managing TMW Shield cluster in ECMP deployments. - -### GET `/api/v2/cluster/status` - -Get current cluster membership status and statistics. - -**Response (in cluster):** -```json -{ - "in_cluster": true, - "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "status": "ONLINE", - "active_nodes": 3, - "messages_sent": 15432, - "messages_received": 15098 -} -``` - -**Response (not in cluster):** -```json -{ - "in_cluster": false, - "status": "NOT_IN_CLUSTER" -} -``` - ---- - -### GET `/api/v2/cluster/nodes` - -List all nodes in the cluster. - -**Response:** -```json -{ - "in_cluster": true, - "total_nodes": 3, - "nodes": [ - { - "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", - "address": "0.0.0.0", - "port": 5555, - "status": "ONLINE", - "is_local": true - }, - { - "node_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", - "address": "192.168.1.11", - "port": 5555, - "status": "ONLINE", - "is_local": false - } - ] -} -``` - ---- - -### POST `/api/v2/cluster/join` - -Join a cluster via a seed node. - -**Request Body:** -```json -{ - "seed": "192.168.1.10:5555" -} -``` - -**Response:** -```json -{ - "success": true, - "message": "Joined cluster successfully", - "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" -} -``` - ---- - -### POST `/api/v2/cluster/leave` - -Leave the current cluster. - -**Response:** -```json -{ - "success": true, - "message": "Left cluster successfully" -} -``` - ---- - -### POST `/api/v2/cluster/sync` - -Request full state synchronization from all nodes or a specific node. - -**Request Body (optional):** -```json -{ - "node": "b2c3d4e5-f6a7-8901-bcde-f23456789012" -} -``` - -**Response:** -```json -{ - "success": true, - "message": "Sync requested from all nodes" -} -``` - ---- \ No newline at end of file +``` \ No newline at end of file