openapi: 3.1.0
info:
  title: Quadrant v2 alerts API
  description: "The Quadrant API currently allows users to retrieve alert data by their client ID.\n\n## Sign-up and credentials \n\nTo start using the Quadrant API, sign into your customer console, navigate to the Quadrant API page in company settings, and generate your API credentials.\nYou will retrieve a client ID and API key. You may regenerate the API key at any time.\n\n## Root domain:\n\nThe root domain is api.qis.io.\n\n## Authentication:\n\nAn API-Key header must be included on requests to all API endpoints. \n`API-Key: {api_key}`\n\nOtherwise, the user will receive a 401 response, which indicates that they need to provide credentials.\n\n## Alerts API\n\n### Endpoints\n\n- `GET /v2/alerts/{client_id}`\n\n### Alert Category\n\nAlerts may be retrieved according to one of the following categories. To specify a category, provide the \"category\" query parameter. The default category is \"escalated.\"\n\n**Example:** `GET /v2/alerts/{client_id}?category=critical`  \nwill request all critical alerts\n\n#### Descriptions\n- **reportable:** all alerts triggered for a customer\n- **benign:** all auto-answered alerts (note: these may include some escalated alerts)\n- **investigated:** alerts investigated by our soc\n- **resolved:** alerts resolved by our soc and not escalated to the customer\n- **escalated:** alerts emailed to the customer\n- **noncritical:** alerts emailed to the customer that are noncritical\n- **critical:** alerts emailed to the customer that are critical\n\n### Filtering\n\nAlerts may be filtered by providing a query parameter corresponding to a field in the alert body. Each parameter may be suffixed with `__lt`, `__gt`, `__lte`, and `__gte` to compare the field value with a date, number, or string.  \n  \n**Example:** `GET /v2/alerts/{client_id}?timestamp__gte=2022-01-01T00:00:00&timestamp__lt=2023-01-01T00:00:00`  \nrequests all escalated alerts for 2022\n\n**Example:** `GET /v2/alerts/{client_id}?analyst_final_response.name=John+Smith`  \nrequests all escalated alerts investigated by John Smith\n\n**Example:** `GET /v2/alerts/{client_id}?alert.category=Attempted+User+Privilege+Gain`  \nrequests all escalated alerts categorized as \"Attempted User Privilege Gain\"  \n\n### Sorting\n\nAn optional sort definition may be provided by using the \"sort\" query parameter. It should be formatted as a comma-separated sequence of \\<field\\>:\\<direction\\> pairs. The direction should be \"asc\" or \"desc\".  \n  \nIf not part of the sort definition, results will be additionally ordered by timestamp and snort id. This is necessary for pagination and to prevent missing or duplicate records across pages or in stream.  \n  \n**Example:** `GET /v2/alerts/{client_id}?sort=timestamp:desc`  \nrequests all escalated alerts in reverse chronological order  \n  \n**Example:** `GET /v2/alerts/{client_id}?sort=alert.category:asc`  \nrequests all escalated alerts ordered alphabetically by alert category  \n\n### Pagination\n\nData is delivered in pages by default. Each page contains a `next` section with a URL that points to the next page. If there are no further pages, `url` will be `null`.  \nPage size defaults to 10,000. This is also the maximum page size.  \nTo specify a smaller size, provide the \"size\" query parameter.  \n  \n**Example**: `GET /v2/alerts/{client_id}?size=1000`  \nreturns the first 1000 of all escalated alerts\n  \n**Example Implementation:** &nbsp;&nbsp;&nbsp; <span style=\"background:Black; color:LightGreen; border:4px solid black;\">&nbsp;Python&nbsp;</span>\n\n\turl = f'https://api.qis.io/v2/alerts/{CLIENT_ID}?category=reportable'\n\tauth_header = {'API-Key': API_KEY}\n\ts = requests.Session()\n\twhile url:\n\t\tresp = s.get(url, headers=auth_header)\n\t\tif resp.status_code != 200:\n\t\t\tbreak\n\t\tdata = resp.json()\n\t\tfor alert in data['alerts']:\n\t\t\t# do something with alert\n\t\t\tpass\n\t\turl = data['next']['url']\n\nwill process all alerts in pages of 10000, executing a per-alert action!  \n\n### Streaming\n\nTo request data as a stream response, set the \"stream\" query parameter to true. Each alert in the stream is delimited by a newline.  \n  \n**Example**: `GET /v2/alerts/{client_id}?stream=true`  \nrequests a stream of all escalated alerts\n  \n**Example Implementation:** &nbsp;&nbsp;&nbsp; <span style=\"background:Black; color:LightGreen; border:4px solid black;\">&nbsp;Python&nbsp;</span>\n\n\turl = f'https://api.qis.io/v2/alerts/{CLIENT_ID}?category=reportable&stream=true'\n\tauth_header = {'API-Key': API_KEY}\n\tresp = requests.get(url, headers=auth_header, stream=True)\n\tfor alert in resp.iter_lines(chunk_size=2**16):\n\t\t# do something with alert\n\t\tpass\n\nwill process a stream of all alerts, executing a per-alert action!\n"
  contact:
    name: Quadrant Information Security
    url: https://www.quadrantsec.com/
    email: soc@quadrantsec.com
  version: 2.0.3
tags:
- name: v2 alerts
paths:
  /v2/alerts/{client_id}/:
    get:
      tags:
      - v2 alerts
      summary: Get Alerts
      operationId: get_alerts_v2_alerts__client_id___get
      security:
      - APIKeyHeader: []
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Client Id
      - name: category
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/AlertCategory'
          default: escalated
      - name: size
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          exclusiveMinimum: 0
          default: 10000
          title: Size
      - name: sort
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort
      - name: stream
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Stream
      - name: next_page_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Page Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SaganAlert:
      properties:
        alert:
          $ref: '#/components/schemas/AlertInfo'
        analyst:
          items:
            $ref: '#/components/schemas/AnalystResponse'
          type: array
          title: Analyst
        analyst_final_response:
          $ref: '#/components/schemas/AnalystResponse'
        auto_answer:
          type: string
          title: Auto Answer
        auto_answer_id:
          type: string
          title: Auto Answer Id
        auto_emailed:
          type: string
          title: Auto Emailed
        bluedot:
          $ref: '#/components/schemas/BluedotInfo'
        critical:
          type: string
          title: Critical
        cust_id:
          type: string
          title: Cust Id
        dest_dns:
          type: string
          title: Dest Dns
        dest_ip:
          type: string
          title: Dest Ip
        dest_port:
          type: string
          title: Dest Port
        emailed:
          type: string
          title: Emailed
        es_index:
          type: string
          title: Es Index
        event_type:
          type: string
          title: Event Type
        flow_id:
          type: string
          title: Flow Id
        geoip:
          $ref: '#/components/schemas/GeoIPInfo'
        geoip_dest:
          $ref: '#/components/schemas/GeoIPLocation'
        geoip_src:
          $ref: '#/components/schemas/GeoIPLocation'
        host:
          type: string
          title: Host
        in_iface:
          type: string
          title: In Iface
        proto:
          type: string
          title: Proto
        sensor_description:
          type: string
          title: Sensor Description
        snort_cid:
          type: string
          title: Snort Cid
        snort_id:
          type: string
          title: Snort Id
        snort_sid:
          type: string
          title: Snort Sid
        src_dns:
          type: string
          title: Src Dns
        src_ip:
          type: string
          title: Src Ip
        src_port:
          type: string
          title: Src Port
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        facility:
          type: string
          title: Facility
        level:
          type: string
          title: Level
        normalize:
          $ref: '#/components/schemas/NormalizationInfo'
        payload:
          type: string
          title: Payload
        priority:
          type: string
          title: Priority
        program:
          type: string
          title: Program
        sensor_type:
          type: string
          title: Sensor Type
          default: lae
        stream:
          type: string
          title: Stream
        tag:
          type: string
          title: Tag
        xff:
          type: string
          title: Xff
      type: object
      required:
      - alert
      - analyst
      - analyst_final_response
      - auto_answer
      - auto_answer_id
      - auto_emailed
      - bluedot
      - critical
      - cust_id
      - dest_dns
      - dest_ip
      - dest_port
      - emailed
      - es_index
      - event_type
      - flow_id
      - geoip
      - geoip_dest
      - geoip_src
      - host
      - in_iface
      - proto
      - sensor_description
      - snort_cid
      - snort_id
      - snort_sid
      - src_dns
      - src_ip
      - src_port
      - timestamp
      - facility
      - level
      - normalize
      - payload
      - priority
      - program
      - stream
      - tag
      - xff
      title: SaganAlert
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BluedotSrc:
      properties:
        api_user:
          type: string
          title: Api User
        category:
          type: string
          title: Category
        code:
          type: integer
          title: Code
        comments:
          type: string
          title: Comments
        counter:
          type: integer
          title: Counter
        ctime:
          type: string
          format: date-time
          title: Ctime
        ctime_epoch:
          type: integer
          title: Ctime Epoch
        last_seen:
          type: string
          format: date-time
          title: Last Seen
        mtime:
          type: string
          format: date-time
          title: Mtime
        mtime_epoch:
          type: integer
          title: Mtime Epoch
        query:
          type: string
          title: Query
        query_counter:
          type: integer
          title: Query Counter
        query_timestamp:
          type: string
          format: date-time
          title: Query Timestamp
        query_type:
          type: string
          title: Query Type
        source:
          type: string
          title: Source
      type: object
      required:
      - api_user
      - category
      - code
      - comments
      - counter
      - ctime
      - ctime_epoch
      - last_seen
      - mtime
      - mtime_epoch
      - query
      - query_counter
      - query_timestamp
      - query_type
      - source
      title: BluedotSrc
    HitFilter:
      properties:
        terms:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Terms
        ranges:
          items:
            additionalProperties:
              additionalProperties:
                anyOf:
                - type: string
                  format: date-time
                - type: integer
                - type: string
              propertyNames:
                $ref: '#/components/schemas/RangeQueryOperator'
              type: object
            type: object
          type: array
          title: Ranges
      type: object
      required:
      - terms
      - ranges
      title: HitFilter
    BluedotInfo:
      properties:
        src:
          $ref: '#/components/schemas/BluedotSrc'
      type: object
      required:
      - src
      title: BluedotInfo
    SuricataAlert:
      properties:
        alert:
          $ref: '#/components/schemas/AlertInfo'
        analyst:
          items:
            $ref: '#/components/schemas/AnalystResponse'
          type: array
          title: Analyst
        analyst_final_response:
          $ref: '#/components/schemas/AnalystResponse'
        auto_answer:
          type: string
          title: Auto Answer
        auto_answer_id:
          type: string
          title: Auto Answer Id
        auto_emailed:
          type: string
          title: Auto Emailed
        bluedot:
          $ref: '#/components/schemas/BluedotInfo'
        critical:
          type: string
          title: Critical
        cust_id:
          type: string
          title: Cust Id
        dest_dns:
          type: string
          title: Dest Dns
        dest_ip:
          type: string
          title: Dest Ip
        dest_port:
          type: string
          title: Dest Port
        emailed:
          type: string
          title: Emailed
        es_index:
          type: string
          title: Es Index
        event_type:
          type: string
          title: Event Type
        flow_id:
          type: string
          title: Flow Id
        geoip:
          $ref: '#/components/schemas/GeoIPInfo'
        geoip_dest:
          $ref: '#/components/schemas/GeoIPLocation'
        geoip_src:
          $ref: '#/components/schemas/GeoIPLocation'
        host:
          type: string
          title: Host
        in_iface:
          type: string
          title: In Iface
        proto:
          type: string
          title: Proto
        sensor_description:
          type: string
          title: Sensor Description
        snort_cid:
          type: string
          title: Snort Cid
        snort_id:
          type: string
          title: Snort Id
        snort_sid:
          type: string
          title: Snort Sid
        src_dns:
          type: string
          title: Src Dns
        src_ip:
          type: string
          title: Src Ip
        src_port:
          type: string
          title: Src Port
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        flow:
          $ref: '#/components/schemas/FlowStats'
        packet:
          type: string
          title: Packet
        packet_info:
          $ref: '#/components/schemas/PacketInfo'
        sensor_type:
          type: string
          title: Sensor Type
          default: pie
        stream:
          type: integer
          title: Stream
      type: object
      required:
      - alert
      - analyst
      - analyst_final_response
      - auto_answer
      - auto_answer_id
      - auto_emailed
      - bluedot
      - critical
      - cust_id
      - dest_dns
      - dest_ip
      - dest_port
      - emailed
      - es_index
      - event_type
      - flow_id
      - geoip
      - geoip_dest
      - geoip_src
      - host
      - in_iface
      - proto
      - sensor_description
      - snort_cid
      - snort_id
      - snort_sid
      - src_dns
      - src_ip
      - src_port
      - timestamp
      - flow
      - packet
      - packet_info
      - stream
      title: SuricataAlert
    CurrentPageInfo:
      properties:
        size:
          type: integer
          title: Size
        number:
          type: integer
          title: Number
      type: object
      required:
      - size
      - number
      title: CurrentPageInfo
    AlertInfo:
      properties:
        action:
          type: string
          title: Action
        category:
          type: string
          title: Category
        gid:
          type: integer
          title: Gid
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        rev:
          type: string
          title: Rev
        rule:
          type: string
          title: Rule
        severity:
          type: integer
          title: Severity
        signature:
          type: string
          title: Signature
        signature_id:
          type: string
          title: Signature Id
      type: object
      required:
      - action
      - category
      - gid
      - metadata
      - rev
      - rule
      - severity
      - signature
      - signature_id
      title: AlertInfo
    FlowStats:
      properties:
        bytes_toclient:
          type: string
          title: Bytes Toclient
        bytes_toserver:
          type: string
          title: Bytes Toserver
        pkts_toclient:
          type: string
          title: Pkts Toclient
        pkts_toserver:
          type: string
          title: Pkts Toserver
        start:
          type: string
          format: date-time
          title: Start
      type: object
      required:
      - bytes_toclient
      - bytes_toserver
      - pkts_toclient
      - pkts_toserver
      - start
      title: FlowStats
    AnalystResponse:
      properties:
        critical:
          type: string
          title: Critical
        long_description:
          type: string
          title: Long Description
        name:
          type: string
          title: Name
        priority:
          type: integer
          title: Priority
        short_description:
          type: string
          title: Short Description
        short_description_id:
          type: integer
          title: Short Description Id
        timestamp:
          type: string
          format: date-time
          title: Timestamp
      type: object
      required:
      - critical
      - long_description
      - name
      - priority
      - short_description
      - short_description_id
      - timestamp
      title: AnalystResponse
    SortDirection:
      type: string
      enum:
      - asc
      - desc
      title: SortDirection
    GeoIPInfo:
      properties:
        dest:
          $ref: '#/components/schemas/GeoIPLocation'
        src:
          $ref: '#/components/schemas/GeoIPLocation'
      type: object
      required:
      - dest
      - src
      title: GeoIPInfo
    GeoIPLocation:
      properties:
        city:
          type: string
          title: City
        country:
          type: string
          title: Country
        latitude:
          type: number
          title: Latitude
        longitude:
          type: number
          title: Longitude
        postal:
          type: string
          title: Postal
        subdivision:
          type: string
          title: Subdivision
        timezone:
          type: string
          title: Timezone
      type: object
      required:
      - city
      - country
      - latitude
      - longitude
      - postal
      - subdivision
      - timezone
      title: GeoIPLocation
    PacketInfo:
      properties:
        linktype:
          type: integer
          title: Linktype
      type: object
      required:
      - linktype
      title: PacketInfo
    AlertCategory:
      type: string
      enum:
      - reportable
      - benign
      - investigated
      - resolved
      - escalated
      - noncritical
      - critical
      title: AlertCategory
    AlertResponse:
      properties:
        total:
          type: integer
          title: Total
        page:
          $ref: '#/components/schemas/CurrentPageInfo'
        next:
          $ref: '#/components/schemas/NextPageInfo'
        category:
          $ref: '#/components/schemas/AlertCategory'
        filter:
          $ref: '#/components/schemas/HitFilter'
        sort:
          items:
            additionalProperties:
              $ref: '#/components/schemas/SortDirection'
            type: object
          type: array
          title: Sort
        alerts:
          items:
            anyOf:
            - $ref: '#/components/schemas/SaganAlert'
            - $ref: '#/components/schemas/SuricataAlert'
          type: array
          title: Alerts
      type: object
      required:
      - total
      - page
      - next
      - category
      - filter
      - sort
      - alerts
      title: AlertResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    NextPageInfo:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        expires_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Expires At
      type: object
      required:
      - url
      - expires_at
      title: NextPageInfo
    NormalizationInfo:
      properties:
        src-ip:
          type: string
          title: Src-Ip
        src-port:
          type: string
          title: Src-Port
        username:
          type: string
          title: Username
      type: object
      required:
      - src-ip
      - src-port
      - username
      title: NormalizationInfo
    RangeQueryOperator:
      type: string
      enum:
      - lt
      - gt
      - lte
      - gte
      title: RangeQueryOperator
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: API-Key