# TMW Shield On-Prem API Documentation

## Api Authentication

All API endpoints require authentication using a Bearer token

**Header:**
```
Authorization: Bearer YOUR_API_KEY
```

Invalid or missing tokens will result in a `401 Unauthorized` response 

---

## Swagger

[Swagger Editor](https://editor.swagger.io/)

## Base URL

```
http://{instance_ip}:8081/api/v2
```

```yaml
openapi: 3.0.0
info:
  title: TMW Shield REST API v2
  version: "2.0.0"

servers:
  - url: http://{instance_ip}:8081/api/v2
    variables:
      instance_ip:
        default: 127.0.0.1
        description: IP address of the TMW Shield instance.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication (use Authorization header with Bearer <token>)
  
  schemas:
    GenericError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "Invalid request parameters"
    GenericSuccess:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Operation completed successfully"
    BlacklistEntry:
      type: object
      properties:
        src:
          type: string
          description: Source IP address or subnet
          example: "192.168.1.100"
        dst:
          type: string
          description: Destination IP address or subnet
          example: "10.0.0.5"
        direction:
          type: string
          enum: ["src", "dst", "both"]
          description: Traffic direction to filter
          example: "both"
        type:
          type: string
          enum: ["IP", "Subnet"]
          description: Entry type
          example: "IP"
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp when entry was added
          example: 1705900000
    BlacklistResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Blacklist entry created"
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlacklistEntry'
    WhitelistEntry:
      type: object
      properties:
        src:
          type: string
          description: Source IP address or subnet
          example: "192.168.1.100"
        dst:
          type: string
          description: Destination IP address or subnet
          example: "10.0.0.5"
        direction:
          type: string
          enum: ["src", "dst", "both"]
          description: Traffic direction to filter
          example: "both"
        type:
          type: string
          enum: ["IP", "Subnet"]
          description: Entry type
          example: "IP"
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp when entry was added
          example: 1705900000
    WhitelistResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Whitelist entry created"
        data:
          type: array
          items:
            $ref: '#/components/schemas/WhitelistEntry'
    ProtocolEntry:
      type: object
      properties:
        dst:
          type: string
          description: Destination IP address
          example: "10.0.0.5"
        protocol:
          type: integer
          minimum: 0
          maximum: 255
          description: Protocol number (e.g., 6 for TCP, 17 for UDP)
          example: 17
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp when entry was added
          example: 1705900000
    ProtocolResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Protocol allow entry created"
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolEntry'
    ServicePortEntry:
      type: object
      properties:
        interface:
          type: string
          description: Network interface name
          example: "eth0"
        ports:
          type: array
          items:
            type: integer
            minimum: 1
            maximum: 65535
          description: List of service ports
          example: [22, 80, 443, 8080]
    ServicePortResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Service port added"
        data:
          type: array
          items:
            $ref: '#/components/schemas/ServicePortEntry'
    VLANEntry:
      type: object
      properties:
        interface:
          type: string
          description: Network interface name
          example: "eth0"
        vlans:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 4095
          description: List of VLAN IDs
          example: [100, 200, 300]
    VLANResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "VLAN bypass added"
        data:
          type: array
          items:
            $ref: '#/components/schemas/VLANEntry'
    StatsLiveResponse:
      type: object
      properties:
        counters:
          type: object
        current:
          type: object
        validated:
          type: object
    StatsPerIPResponse:
      type: object
      properties:
        list:
          type: array
          items:
            type: object
    StatsAggregatedResponse:
      type: object
      properties:
        range:
          type: string
        allowed:
          type: array
          items:
            type: integer
        dropped:
          type: array
          items:
            type: integer
        validated:
          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:
        success:
          type: boolean
        attacks:
          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:
        success:
          type: boolean
        attacks:
          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:
        success:
          type: boolean
        activeProtections:
          type: array
          items:
            type: object
        sentProtections:
          type: array
          items:
            type: object
    StatusResponse:
      type: object
      properties:
        status:
          type: string
          example: "ok"
        version:
          type: string
          example: "2.0.0"
    WebhookEntry:
      type: object
      properties:
        target:
          type: string
          example: "192.168.1.100"
        url:
          type: string
          example: "https://example.com/webhook"
    WebhookResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        webhooks:
          type: object
    EmailEntry:
      type: object
      properties:
        target:
          type: string
          example: "192.168.1.100"
        email:
          type: string
          example: "admin@example.com"
    EmailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailEntry'
    SMTPConfig:
      type: object
      properties:
        server:
          type: string
          example: "smtp.example.com"
        port:
          type: integer
          example: 587
        user:
          type: string
          example: "smtp_user"
        pass:
          type: string
          example: "smtp_password"
        from:
          type: string
          example: "shield@example.com"
    SMTPResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
    CheckIPRequest:
      type: object
      required:
        - ip
      properties:
        ip:
          type: string
          example: "198.51.100.7"
    CheckIPResponse:
      type: object
      properties:
        ip:
          type: string
        blocked:
          type: boolean
        source:
          type: string
    ClusterStatusResponse:
      type: object
      properties:
        in_cluster:
          type: boolean
        node_id:
          type: string
        status:
          type: string
        active_nodes:
          type: integer
        messages_sent:
          type: integer
        messages_received:
          type: integer
    ClusterNodesResponse:
      type: object
      properties:
        in_cluster:
          type: boolean
        total_nodes:
          type: integer
        nodes:
          type: array
          items:
            type: object
    ClusterJoinRequest:
      type: object
      properties:
        seed:
          type: string
          example: "192.168.1.10:5555"
    ClusterSyncRequest:
      type: object
      properties:
        node:
          type: string
    AbuseIPDBResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
    AbuseIPDBListResponse:
      type: object
      properties:
        success:
          type: boolean
        blocked_ips:
          type: array
          items:
            type: object
        enabled_destinations:
          type: array
          items:
            type: object
    SessionEntry:
      type: object
      properties:
        src:
          type: string
        dst:
          type: string
        connections:
          type: integer
        age_sec:
          type: number
        src_port:
          type: integer
          nullable: true
        dst_port:
          type: integer
          nullable: true
        validated:
          type: boolean
          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:
    - BearerAuth: []

paths:
  /blacklists:
    get:
      summary: List Blacklist Entries
      description: Retrieves all blacklist entries across all interfaces
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Blacklist entries retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlacklistResponse'
        "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'
    
    post:
      summary: Create Blacklist Entry
      description: Creates a new blacklist entry for blocking traffic
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
                - dst
              properties:
                src:
                  type: string
                  description: Source IP address or subnet
                  example: "192.168.1.100"
                dst:
                  type: string
                  description: Destination IP address or subnet
                  example: "10.0.0.5"
                direction:
                  type: string
                  enum: ["src", "dst", "both"]
                  default: "both"
                  description: Traffic direction to filter
                  example: "both"
      responses:
        "201":
          description: Blacklist entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Blacklist Entry
      description: Removes a blacklist entry
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
                - dst
              properties:
                src:
                  type: string
                  description: Source IP address or subnet
                  example: "192.168.1.100"
                dst:
                  type: string
                  description: Destination IP address or subnet
                  example: "10.0.0.5"
      responses:
        "204":
          description: Blacklist entry removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Entry does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /whitelists:
    get:
      summary: List Whitelist Entries
      description: Retrieves all whitelist entries across all interfaces
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Whitelist entries retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhitelistResponse'
        "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'
    
    post:
      summary: Create Whitelist Entry
      description: Creates a new whitelist entry for allowing traffic
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
                - dst
              properties:
                src:
                  type: string
                  description: Source IP address or subnet
                  example: "192.168.1.100"
                dst:
                  type: string
                  description: Destination IP address or subnet
                  example: "10.0.0.5"
                direction:
                  type: string
                  enum: ["src", "dst", "both"]
                  default: "both"
                  description: Traffic direction to filter
                  example: "both"
      responses:
        "201":
          description: Whitelist entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Whitelist Entry
      description: Removes a whitelist entry
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
                - dst
              properties:
                src:
                  type: string
                  description: Source IP address or subnet
                  example: "192.168.1.100"
                dst:
                  type: string
                  description: Destination IP address or subnet
                  example: "10.0.0.5"
      responses:
        "204":
          description: Whitelist entry removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Entry does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /protocols:
    get:
      summary: List Protocol Allow Entries
      description: Retrieves all protocol allow entries across all interfaces
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Protocol allow entries retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtocolResponse'
        "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'
    
    post:
      summary: Create Protocol Allow Entry
      description: Creates a new protocol allow entry for specific destination
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dst
                - protocol
              properties:
                dst:
                  type: string
                  description: Destination IP address
                  example: "10.0.0.5"
                protocol:
                  type: integer
                  minimum: 0
                  maximum: 255
                  description: Protocol number (e.g., 6 for TCP, 17 for UDP)
                  example: 17
      responses:
        "201":
          description: Protocol allow entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Protocol Allow Entry
      description: Removes a protocol allow entry
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dst
                - protocol
              properties:
                dst:
                  type: string
                  description: Destination IP address
                  example: "10.0.0.5"
                protocol:
                  type: integer
                  minimum: 0
                  maximum: 255
                  description: Protocol number (e.g., 6 for TCP, 17 for UDP)
                  example: 17
      responses:
        "204":
          description: Protocol allow entry removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Entry does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /service-ports:
    get:
      summary: List Service Ports
      description: Retrieves all service ports across all interfaces
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Service ports retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServicePortResponse'
        "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'
    
    post:
      summary: Add Service Port
      description: Adds a new service port for monitoring
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - port
              properties:
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  description: Port number to add
                  example: 8080
      responses:
        "201":
          description: Service port added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Service Port
      description: Removes a service port
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - port
              properties:
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  description: Port number to remove
                  example: 8080
      responses:
        "204":
          description: Service port removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Port does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /vlans:
    get:
      summary: List VLAN Bypass Entries
      description: Retrieves all VLAN bypass entries across all interfaces
      security:
            - BearerAuth: []
      responses:
        "200":
          description: VLAN bypass entries retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VLANResponse'
        "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'
    
    post:
      summary: Add VLAN Bypass Entry
      description: Adds a new VLAN bypass for traffic
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vlan
              properties:
                vlan:
                  type: integer
                  minimum: 0
                  maximum: 4095
                  description: VLAN ID to bypass
                  example: 100
      responses:
        "201":
          description: VLAN bypass added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove VLAN Bypass Entry
      description: Removes a VLAN bypass entry
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - vlan
              properties:
                vlan:
                  type: integer
                  minimum: 0
                  maximum: 4095
                  description: VLAN ID to remove
                  example: 100
      responses:
        "204":
          description: VLAN bypass removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - VLAN does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /stats/live:
    get:
      summary: Get Live Traffic Statistics
      description: Retrieves current live traffic statistics and counters
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Live statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsLiveResponse'
        "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'

  /stats/per-ip:
    get:
      summary: Get Per-IP Statistics
      description: Retrieves traffic statistics for specific IP addresses
      security:
            - BearerAuth: []
      parameters:
        - name: ip
          in: query
          description: Filter for a specific IP address
          required: false
          schema:
            type: string
            example: "203.0.113.5"
      responses:
        "200":
          description: Per-IP statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsPerIPResponse'
        "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'

  /stats/aggregated:
    get:
      summary: Get Aggregated Historical Statistics
      description: Retrieves aggregated historical traffic statistics
      security:
            - BearerAuth: []
      parameters:
        - name: range
          in: query
          description: Time range for aggregated data
          required: false
          schema:
            type: string
            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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsAggregatedResponse'
        "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'

  /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:
            - BearerAuth: []
      responses:
        "200":
          description: Active attacks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttacksResponse'
        "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/history:
    get:
      summary: Get Attack History
      description: Retrieves historical attack data for specific IP
      security:
            - BearerAuth: []
      parameters:
        - name: ip
          in: query
          description: Filter for a specific IP address
          required: false
          schema:
            type: string
            example: "203.0.113.5"
      responses:
        "200":
          description: Attack history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttacksHistoryResponse'
        "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'



  /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:
            - BearerAuth: []
      responses:
        "200":
          description: System logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogsResponse'
        "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'

  /status:
    get:
      summary: Get System Status
      description: Retrieves current TMW Shield system status and configuration
      security:
            - BearerAuth: []
      responses:
        "200":
          description: System status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        "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'

  /abuseipdb:
    get:
      summary: List AbuseIPDB Blocked IPs
      description: Retrieves all AbuseIPDB blocklist entries
      security:
            - BearerAuth: []
      responses:
        "200":
          description: AbuseIPDB list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBListResponse'
        "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'
    
    post:
      summary: Add IP to AbuseIPDB Blocklist
      description: Adds an IP to the AbuseIPDB blocklist
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
              properties:
                src:
                  type: string
                  description: Source IP address to block
                  example: "198.51.100.7"
      responses:
        "201":
          description: IP added to blocklist successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBResponse'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove IP from AbuseIPDB Blocklist
      description: Removes an IP from the AbuseIPDB blocklist
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - src
              properties:
                src:
                  type: string
                  description: Source IP address to unblock
                  example: "198.51.100.7"
      responses:
        "204":
          description: IP removed from blocklist successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBResponse'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - IP does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /abuseipdb/config:
    get:
      summary: List AbuseIPDB Enabled Destinations
      description: Retrieves all destinations with AbuseIPDB check enabled
      security:
            - BearerAuth: []
      responses:
        "200":
          description: AbuseIPDB config retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBListResponse'
        "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'
    
    post:
      summary: Enable AbuseIPDB Check for Destination
      description: Enables AbuseIPDB check for a destination IP
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dst
                - enable
              properties:
                dst:
                  type: string
                  description: Destination IP address
                  example: "10.0.0.1"
                enable:
                  type: boolean
                  description: Enable or disable check
                  example: true
      responses:
        "201":
          description: AbuseIPDB check configured successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBResponse'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Disable AbuseIPDB Check for Destination
      description: Disables AbuseIPDB check for a destination IP
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dst
              properties:
                dst:
                  type: string
                  description: Destination IP address
      responses:
        "204":
          description: AbuseIPDB check disabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AbuseIPDBResponse'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Destination not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /webhooks:
    get:
      summary: List Webhooks
      description: Retrieves all configured webhooks
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Webhooks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        "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'
    
    post:
      summary: Add Webhook
      description: Adds a new webhook for attack notifications
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEntry'
      responses:
        "201":
          description: Webhook added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Webhook
      description: Removes a webhook (accepts query parameters or JSON body with identical fields)
      security:
            - 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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                target:
                  type: string
                url:
                  type: string
      responses:
        "204":
          description: Webhook removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Webhook does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /emails:
    get:
      summary: List Email Notifications
      description: Retrieves all configured email notifications
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Email notifications retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        "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'
    
    post:
      summary: Add Email Notification
      description: Adds a new email notification for attacks
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEntry'
      responses:
        "201":
          description: Email notification added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
    
    delete:
      summary: Remove Email Notification
      description: Removes an email notification
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target
                - email
              properties:
                target:
                  type: string
                  description: Target IP or CIDR
                  example: "192.168.1.100"
                email:
                  type: string
                  description: Email address to remove
                  example: "admin@example.com"
      responses:
        "204":
          description: Email notification removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "404":
          description: Not found - Email notification does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /smtp:
    get:
      summary: Get SMTP Configuration
      description: Retrieves the SMTP server configuration
      security:
            - BearerAuth: []
      responses:
        "200":
          description: SMTP configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMTPConfig'
        "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'
    
    post:
      summary: Configure SMTP
      description: Configures the SMTP server settings
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - server
                - port
                - user
                - pass
                - from
              properties:
                server:
                  type: string
                  description: SMTP server hostname
                  example: "smtp.example.com"
                port:
                  type: integer
                  description: SMTP port
                  example: 587
                user:
                  type: string
                  description: SMTP username
                  example: "smtp_user"
                pass:
                  type: string
                  description: SMTP password
                  example: "smtp_password"
                from:
                  type: string
                  description: From email address
                  example: "shield@example.com"
      responses:
        "201":
          description: SMTP configured successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMTPResponse'
        "400":
          description: Bad request - Invalid parameters
          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'

  /check-ip:
    post:
      summary: Check IP Threat
      description: Checks an IP address for threats
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
              properties:
                ip:
                  type: string
                  description: IP address to check
                  example: "198.51.100.7"
      responses:
        "200":
          description: IP check completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckIPResponse'
        "400":
          description: Bad request - Invalid parameters
          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'

  /cluster/status:
    get:
      summary: Get Cluster Status
      description: Retrieves current cluster membership status and statistics
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Cluster status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterStatusResponse'
        "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'

  /cluster/nodes:
    get:
      summary: List Cluster Nodes
      description: Retrieves all nodes in the cluster
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Cluster nodes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterNodesResponse'
        "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'

  /cluster/join:
    post:
      summary: Join Cluster
      description: Joins the node to an existing cluster via a seed node
      security:
            - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterJoinRequest'
            example:
              seed: "192.168.1.10:5555"
      responses:
        "200":
          description: Successfully joined cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "401":
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "409":
          description: Conflict - Already in a cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'

  /cluster/leave:
    post:
      summary: Leave Cluster
      description: Gracefully leaves the current cluster
      security:
            - BearerAuth: []
      responses:
        "200":
          description: Successfully left cluster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Not in a cluster
          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'

  /cluster/sync:
    post:
      summary: Trigger Cluster Sync
      description: Requests full state synchronization from all nodes or a specific node
      security:
            - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClusterSyncRequest'
            example:
              node: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
      responses:
        "200":
          description: Sync requested successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        "400":
          description: Bad request - Invalid parameters
          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'
```