openapi.yml

openapi: 3.1.0
info:
  title: "sipPROT"
  version: "5.3"
  description: "Documentation for the sipPROT API."
  
externalDocs:
  description: "sipPROT wiki"
  url: "https://wiki.bicomsystems.com/en/home/sipPROT"

servers:
  - url: "/sipprot/api"

tags:
  - name: "hosts"
  - name: "attack logs"
  - name: "allowlist"
  - name: "denylist"
  - name: "dynamic denylist"

paths:
  '/attack-logs':
    get:
      tags:
        - attack logs
      summary: "Get all attack logs data"
      responses:
        '200':
          $ref: "#/components/responses/AttackLogsResponse"
        '500':
          description: "Failed to fetch blocked SIP attacks."
      security:
        - apiKey: []

  '/denylist':
    get:
      tags:
        - denylist
      summary: "Get SipPROT deny list"
      parameters:
        - $ref: "#/components/parameters/Export"
      responses:
        "200":
          $ref: "#/components/responses/DenyListResponse"
        "500":
          description: "Failed to fetch deny list"
      security:
        - apiKey: []
    post:
      tags:
        - denylist
      summary: "Add deny list entry"
      description: |
       **Notes**:
        
        To import deny list entries from CSV:
          - *set import parameter to csv*
          - *choose multipart/form-data request body and upload csv file*       
      parameters:
        - $ref: "#/components/parameters/Import"
      requestBody:
        $ref: "#/components/requestBodies/DenyListEntryBody"
      responses:
        "200":
          $ref: "#/components/responses/DenyListEntryResponse"
        "400":
          description: |
                    Failed to add deny list entry
                      - invalid payload
                      - cannot block yourself
                      - IPv6 address not supported 

                    Failed to add deny list entries:
                      - File exceeds 2MB
                      - Unable to open provided file
                      - Unsupported file extension for file
                      - cannot block yourself                    
        "422":
          description: "Failed to add deny list entry/entries (maximum number of IPs has been reached)"
        "500":
          description: |
                      Failed to add deny list entry:
                        - failed to import from CSV                      
      security:
        - apiKey: []

  '/denylist/{ip}':
    delete:
      tags:
        - denylist
      summary: "Delete deny list entry by IP address"
      parameters:
        - $ref: "#/components/parameters/IPAddress"
      responses:
        "204":
          description: "No content"
        "400":
          description: "Failed to delete deny list entry (invalid IP address)"
        "500":
          description: "Failed to delete IP address from the denylist"
      security:
        - apiKey: []
    patch:
      tags:
        - denylist
      summary: "Update note for deny list entry"
      parameters:
        - $ref: "#/components/parameters/IPAddress"
      requestBody:
        $ref: '#/components/requestBodies/NoteBody'
      responses:
        "200":
          $ref: "#/components/responses/DenyListPatchResponse"
        "400":
          description: |
                      Failed to update deny list entry:
                        - invalid IP address
                        - invalid payload
        "500":
          description: |
                      Failed to update deny list entry:
                        - unable to get IP address record
      security:
        - apiKey: []

  '/denylist/bulk-delete':
    post:
      tags:
        - denylist
      summary: "Bulk delete deny list entries"
      requestBody:
        $ref: "#/components/requestBodies/IpBody"
      responses:
        "204":
          description: "No content"
        "400":
          description: |
           Failed to bulk delete deny list entries
           - invalid payload
           - no provided IP addresses           
        "500":
          description: "Failed to remove IP address from deny list"
      security:
        - apiKey: []

  '/hosts':
    get:
      tags:
        - hosts
      summary: "Get all hosts info"
      responses:
        "200":
          $ref: "#/components/responses/HostsResponse"
        "500":
          description: "Failed to fetch registered host information."
      security:
        - apiKey: []

  '/hosts/{uuid}':
    parameters:
      - $ref: "#/components/parameters/HostUUID"
    delete:
      tags:
        - hosts
      summary: "Remove host"
      responses:
        "204":
          description: "No content"
        "500":
          description: "Failed to remove host."
      security:
        - apiKey: []

  '/allowlist':
    get:
      tags:
        - allowlist
      summary: "Get SipPROT allowlist"
      parameters:
        - $ref: "#/components/parameters/Export"
      responses:
        "200":
          $ref: "#/components/responses/AllowListResponse"
        "500":
          description: "Failed to fetch allowlist"
      security:
        - apiKey: []
    post:
      tags:
        - allowlist
      summary: "Create allowlist entry"
      description: |
       **Notes**:
        
        To import allowlist entries from CSV:
          - *set import parameter to csv*
          - *choose multipart/form-data request body and upload csv file*       
      parameters:
        - $ref: "#/components/parameters/Import"
      requestBody:
        $ref: "#/components/requestBodies/AllowListEntryBody"
      responses:
        "200":
          $ref: "#/components/responses/AllowListEntryResponse"
        "400":
          description: |
           Failed to add allowlist entry
            - invalid payload
            - file exceeds 2MB
            - failed to import csv
            - failed to import from csv
            - unsupported file extension
            - IPv6 address not supported           
        "422":
          description: "Failed to add allowlist entry (maximum number of IPs has been reached"
        "500":
          description: "Failed to add allowlist entry"
      security:
        - apiKey: []

  '/allowlist/{ip}':
    delete:
      tags:
        - allowlist
      summary: "Delete allowlist entry by IP address"
      parameters:
        - $ref: "#/components/parameters/IPAddress"
      responses:
        "204":
          description: "No content"
        "400":
          description: "Failed to delete allowlist entry (invalid IP address)"
        "500":
          description: "Failed to delete allowlist entry"
      security:
        - apiKey: []
    patch:
      tags:
        - allowlist
      summary: "Update note for allowlist entry"
      parameters:
        - $ref: "#/components/parameters/IPAddress"
      requestBody:
        $ref: '#/components/requestBodies/NoteBody'
      responses:
        "200":
          $ref: "#/components/responses/AllowListPatchResponse"
        "400":
          description: |
           Failed to update allowlist entry
            - invalid payload
            - invalid IP address
        "404":
          description: "Failed to update allowlist entry (entry not found)"
        "500":
          description: "Failed to update allowlist entry"
      security:
        - apiKey: []

  '/allowlist/bulk-delete':
    post:
      tags:
        - allowlist
      summary: "Bulk delete allowlist entries"
      requestBody:
        $ref: "#/components/requestBodies/IpBody"
      responses:
        "204":
          description: "No content"
        "400":
          description: |
           Failed to bulk delete allowlist entries
           - invalid payload
           - no provided IP addresses           
        "500":
          description: "Failed to bulk delete allowlist entries"
      security:
        - apiKey: []

  '/dyn-denylist':
    get:
      tags:
        - dynamic denylist
      summary: "Get dynamic denylist"
      responses:
        "200":
          $ref: "#/components/responses/DynamicDenyListResponse"
        "500":
          description: "Failed to fetch dynamic denylist"
      security:
        - apiKey: []

  '/dyn-denylist/{ip}':
    delete:
      tags:
        - dynamic denylist
      summary: "Delete dynamic denylist entry by IP address"
      parameters:
        - $ref: "#/components/parameters/IPAddress"
      responses:
        "204":
          description: "No content"
        "400":
          description: "Failed to delete dynamic denylist entry (invalid IP address)"
        "500":
          description: "Failed to delete dynamic denylist entry"
      security:
        - apiKey: []

  '/dyn-denylist/bulk-delete':
    post:
      tags:
        - dynamic denylist
      summary: "Bulk delete dynamic denylist entries"
      requestBody:
        $ref: "#/components/requestBodies/IpBody"
      responses:
        "204":
          description: "No content"
        "400": 
          description: |
            Failed to bulk delete dynamic denylist entries
              - invalid payload
              - no provided IP addresses            
        "500":
          description: "Failed to bulk delete dynamic denylist entries"
      security:
        - apiKey: []

components:
  parameters:
    Export:
      in: query
      name: export
      description: "Export format (csv only)"
      required: false
      schema:
        type: string
        default: "csv"
    Import:
      in: query
      name: import
      description: "Import format (csv only)"
      required: false
      schema:
        type: string
    IPAddress:
      in: path
      name: ip
      description: "IP address"
      required: true
      schema:
        type: string
    HostUUID:
      in: path
      name: uuid
      description: "Host UUID"
      required: true
      schema:
        type: string

  requestBodies:
    DenyListEntryBody:
      description: "Request body for creating deny list entry"
      content:
        application/json:
          schema:
            properties:
              ip:
                type: string
                description: "IP address"
              note:
                type: string
                description: "Additional note"
        multipart/form-data:
          schema:
            type: object
            properties:
              csvFile:
                type: string
                format: binary
                description: "CSV file deny list entries"

    AllowListEntryBody:
      description: "Request body for creating allowlist entry"
      content:
        application/json:
          schema:
            properties:
              ip:
                type: string
                description: "IP address"
              note:
                type: string
                description: "Additional note"
        multipart/form-data:
          schema:
            type: object
            properties:
              csvFile:
                type: string
                format: binary
                description: "CSV file allowlist entries"
    IpBody:
      description: "Request body for bulk delete allowlist entries"
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                ip:
                  type: string
                  description: "IP address"

    NoteBody:
      description: "Request body for note update"
      content:
        application/json:
          schema:
            properties:
              note:
                type: string
                description: "Additional note"

  responses:
    HostsResponse:
      description: "Hosts list response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/Host"

    AttackLogsResponse:
      description: "A list of attack logs retrieved successfully"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/AttackLog"

    AllowListResponse:
      description: "Allowlist response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/AllowListEntry"
                    - $ref: "#/components/schemas/GeoData"

    AllowListEntryResponse:
      description: "Allowlist response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                $ref: "#/components/schemas/AllowListEntry"

    AllowListPatchResponse:
      description: "Allowlist response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                allOf:
                  - $ref: "#/components/schemas/AllowListEntry"
                  - $ref: "#/components/schemas/GeoData"

    DenyListResponse:
      description: "Deny list response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/DenyListEntry"
                    - $ref: "#/components/schemas/GeoData"

    DenyListEntryResponse:
      description: "Deny list response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                $ref: "#/components/schemas/DenyListEntry"

    DenyListPatchResponse:
      description: "Denylist response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                allOf:
                  - $ref: "#/components/schemas/DenyListEntry"
                  - $ref: "#/components/schemas/GeoData"

    DynamicDenyListResponse:
      description: "Dynamic deny list response after successful operation"
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/DynamicDenyListEntry"

  schemas:
    Host:
      type: object
      properties:
        uuid:
          type: string
          description: "Host UUID"
          default: "string"
        host_name:
          type: string
          description: "Host name"
          default: "string"
        kernel_version:
          type: string
          description: "Linux kernel version"
          default: "6.1.112-commsware"
        geo_protection:
          type: boolean
          description: "Geo protection on/off"
          default: true
        sipprot_version:
          type: string
          description: "sipPROT version"
          default: "5.4.0+build.1609.rev.foobar"
        lan_address:
          type: string
          description: "LAN IP address of host"
          default: "1.3.3.7"
        active:
          type: boolean
          description: "Host active status"
          default: true
        firewall_active:
          type: boolean
          description: "Firewall active status"
          default: true

    AttackLog:
      type: object
      properties:
        id:
          type: integer
          description: "Attack ID"
          default: 1
        host_id:
          type: string
          description: "Processing host ID on which the attack occurred"
          default: "string"
        security_group_id:
          type: string
          description: "Security group ID"
          default: "1"
        attacker_ip:
          type: string
          description: "Attacker IP address"
          default: "0.0.0.0"
        victim_ip:
          type: string
          description: "Victim IP addres (VPS being attacked)"
          default: "0.0.0.0"
        attack_type:
          type: string
          description: "Attack type"
          default: "REGISTER"
        user_agent:
          type: string
          description: "User agent used in the attack"
          default: "string"
        scanner:
          type: boolean
          description: ""
          default: false
        timestamp:
          type: integer
          description: "UNIX timestamp when the attack happened"
          default: 1736418197

    AllowListEntry:
      type: object
      properties:
        ip:
          type: string
          description: "The IP address that is allowed"
        note:
          type: string
          description: "Optional note for the allowlist entry"
        time:
          type: integer
          format: int64
          description: "Timestamp when the entry was added"
        added_by:
          type: string
          description: "Details of the user who added the entry"

    DenyListEntry:
      type: object
      properties:
        ip:
          type: string
          description: "The IP address that is denied"
        note:
          type: string
          description: "Optional note for the deny list entry"
        time:
          type: integer
          format: int64
          description: "Timestamp when the entry was added"
          default: 1736753357
        added_by:
          type: string
          description: "Details of the user who added the entry"

    GeoData:
      type: object
      properties:
        geo_data:
          type: object
          description: "Geographical data related to the IP address (if available)"
          properties:
            country_code:
              type: string
              description: "Country code of attackers IP geo location"
              default: "BA"
            country_name:
              type: string
              description: "Country name of attackers IP geo location"
              default: "Bosnia and Herzegovina"

    DynamicDenyListEntry:
      allOf:
        - type: object
          properties:
            ip:
              type: string
              description: IP address of the attacker
              format: ipv4
            unblock_in:
              type: integer
              description: How many seconds until the block is lifted
              default: 3600
            attack_type:
              type: string
              description: Type of the attack
            user_agent:
              type: string
              description: Attacker's reported user-agent string
            time:
              type: integer
              description: Unix timestamp of the attack
        - $ref: "#/components/schemas/GeoData"

  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: SW-API-Token