openapi: 3.0.0
info:
  title: HYAS Protect API
  description: >
    # Endpoint


    The base endpoint is `https://apps.hyas.com/api/protect/ext`, which all of the following REST routes will follow.



    # Authentication


    Authentication is performed using X-API-Key header with provided PSK API key on each request


    # cURL Example


    ```curl --header "X-API-Key: <your API key>" https://apps.hyas.com/api/protect/ext/reports```
  contact: {}
  version: '1.0.0'
servers:
- url: https://apps.hyas.com/api/protect/ext
  variables: {}
paths:
  /aggregates:
    post:
      tags:
      - Overview
      summary: newcastle.protect.top_charts.aggregates
      description: Get count aggregates for the top charts
      operationId: newcastle.protect.top_charts.aggregates
      parameters: []
      requestBody:
        description: The filter used to perform aggregate queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/aggregate_params'
              - description: The filter used to perform aggregate queries
        required: true
      responses:
        '200':
          description: Top Charts
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatesResponse'
      deprecated: false
  /bar:
    post:
      tags:
      - Overview
      summary: newcastle.protect.bar_charts.bar
      description: Get bar chart data
      operationId: newcastle.protect.bar_charts.bar
      parameters: []
      requestBody:
        description: The filter used to perform bar chart queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/bar_params'
              - description: The filter used to perform bar chart queries
        required: true
      responses:
        '200':
          description: Bar Chart
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarResponse1'
      deprecated: false
  /histogram:
    post:
      tags:
      - Overview
      summary: newcastle.protect.histograms.histogram
      description: Get histogram data for the real time charts
      operationId: newcastle.protect.histograms.histogram
      parameters: []
      requestBody:
        description: The filter used to perform histogram queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/histogram_params'
              - description: The filter used to perform histogram queries
        required: true
      responses:
        '200':
          description: Historgram
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistogramResponse1'
      deprecated: false
  /summary:
    post:
      tags:
      - Overview
      summary: newcastle.protect.summaries.summary
      description: Get request summaries
      operationId: newcastle.protect.summaries.summary
      parameters: []
      requestBody:
        description: The filter used to perform summary queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/summary_params'
              - description: The filter used to perform summary queries
        required: true
      responses:
        '200':
          description: Summary
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse1'
      deprecated: false
  /histogram/artifact:
    post:
      tags:
      - Logs
      summary: newcastle.protect.histograms.histogram_artifact
      description: Get histogram data for the pop out panel timeline chart
      operationId: newcastle.protect.histograms.histogram_artifact
      parameters: []
      requestBody:
        description: The filter used to perform histogram queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/histogram_artifact_params'
              - description: The filter used to perform histogram queries
        required: true
      responses:
        '200':
          description: Flyout Panel Artifact Historgram
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistogramArtifactResponse1'
      deprecated: false
  /logs:
    post:
      tags:
      - Logs
      summary: newcastle.protect.logs.logs
      description: Get logs
      operationId: newcastle.protect.logs.logs
      parameters: []
      requestBody:
        description: The filter used to perform log queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/log_params'
              - description: The filter used to perform log queries
        required: true
      responses:
        '200':
          description: Logs
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogsResponse'
      deprecated: false
  /passthrough:
    post:
      tags:
      - Passthrough
      summary: newcastle.protect.passthrough.passthrough
      description: Get passthrough records
      operationId: newcastle.protect.passthrough.passthrough
      parameters: []
      requestBody:
        description: The filter used to perform passthrough queries
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/passthrough_params'
              - description: The filter used to perform passthrough queries
        required: true
      responses:
        '200':
          description: Logs
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PassthroughResponse1'
      deprecated: false
  /report:
    post:
      tags:
      - Reports
      summary: newcastle.protect.reports.get_report
      description: Get executive report
      operationId: newcastle.protect.reports.get_report
      parameters: []
      requestBody:
        description: The filter used to generate the report
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/report_params'
              - description: The filter used to generate the report
        required: true
      responses:
        '200':
          description: A report in pdf format
          headers: {}
          content:
            application/pdf:
              schema: {}
      deprecated: false
  /reports:
    post:
      tags:
      - Reports
      summary: newcastle.protect.reports.get_reports
      description: Get list of executive reports
      operationId: newcastle.protect.reports.get_reports
      parameters: []
      responses:
        '200':
          description: Bar Chart
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsResponse1'
      deprecated: false
components:
  schemas:
    aggregate_params:
      title: aggregate_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters9'
    aggregate_response:
      title: aggregate_response
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: fqdn
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem'
          description: Top items
      description: Aggregate response
    bar_params:
      title: bar_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters12'
    bar_response:
      title: bar_response
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: no_answer_queries
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem1'
          description: Top items
      description: Bar chart response
    histogram_artifact_params:
      title: histogram_artifact_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters22'
    histogram_artifact_response:
      title: histogram_artifact_response
      type: object
      properties:
        days:
          type: integer
          description: The number of days the histogram is for
          format: int32
        query_type:
          type: string
          description: The query type that the histogram is for
      description: Histogram response
    histogram_params:
      title: histogram_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters32'
    histogram_response:
      title: histogram_response
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: queries
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem'
          description: Top items
      description: Histogram response
    log_params:
      title: log_params
      type: object
      properties:
        applied_filters:
          type: array
          items:
            $ref: '#/components/schemas/AppliedFilters4'
          description: ''
    log_params_query_type_values:
      title: log_params_query_type_values
      enum:
      - A
      - A6
      - AAAA
      - AFSDB
      - AMTRELAY
      - ANY
      - APL
      - ATMA
      - AVC
      - AXFR
      - CAA
      - CDS
      - CDNSKEY
      - CERT
      - CNAME
      - CSYNC
      - DHCID
      - DLV
      - DNAME
      - DNSKEY
      - DOA
      - DS
      - EID
      - EUI48
      - EUI64
      - GID
      - GPOS
      - HINFO
      - HIP
      - HTTPS
      - IPSECKEY
      - ISDN
      - IXFR
      - KEY
      - KX
      - L32
      - L64
      - LP
      - LOC
      - MAILA
      - MAILB
      - MB
      - MD
      - MF
      - MG
      - MINFO
      - MR
      - MX
      - NAPTR
      - NID
      - NIMLOC
      - NINFO
      - NS
      - NSAP
      - NSAP-PTR
      - NSEC
      - NSEC3
      - NSEC3PARAM
      - NXT
      - OPENPGPKEY
      - OPT
      - PTR
      - PX
      - RKEY
      - RP
      - RRSIG
      - RT
      - RV
      - SIG
      - SINK
      - SMIMEA
      - SOA
      - SPF
      - SSHFP
      - SVCB
      - TA
      - TALINK
      - TKEY
      - TLSA
      - TSIG
      - TXT
      - UID
      - UINFO
      - Unassigned
      - UNSPEC
      - URI
      - WKS
      - X25
      - ZONEMD
      type: string
    log_params_reputation_values:
      title: log_params_reputation_values
      enum:
      - blocked
      - malicious
      - suspicious
      - permitted
      type: string
    log_response:
      title: log_response
      type: object
      properties:
        aggregates:
          $ref: '#/components/schemas/Aggregates2'
        total_count:
          type: integer
          description: total count of records without pagination
          format: int32
          example: 197
      description: Summary response
    passthrough_params:
      title: passthrough_params
      type: object
      properties:
        applied_filters:
          type: array
          items:
            $ref: '#/components/schemas/AppliedFilters5'
          description: ''
    passthrough_response:
      title: passthrough_response
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/Log'
          description: Collection of passthrough records
        total_count:
          type: integer
          description: total count of records without pagination
          format: int32
          example: 197
      description: Passthrough response
    query:
      title: query
      type: object
      properties:
        applied_filters:
          type: object
          description: A filter object specific to the query endpoint.
    report_params:
      title: report_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters62'
    reports_response:
      title: reports_response
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
          description: Collection of reports
        total_count:
          type: integer
          description: The total report count
          format: int32
      description: List of reports and count
    summary_params:
      title: summary_params
      type: object
      properties:
        applied_filters:
          $ref: '#/components/schemas/AppliedFilters72'
    summary_response:
      title: summary_response
      type: object
      properties:
        day_count:
          type: integer
          format: int32
          example: 1
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: blocked
        total_count:
          type: integer
          format: int32
          example: 0
      description: Summary response
    Aggregates:
      title: Aggregates
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/Query2'
          description: Collection of query type codes and counts
        responses:
          type: array
          items:
            $ref: '#/components/schemas/Response'
          description: Collection of response codes and counts
      description: Aggregates for the filter drop downs
    AppliedFilters:
      title: AppliedFilters
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType'
        top_count:
          type: integer
          description: How many aggregate values to get
          format: int32
          example: 25
      description: A filter object specific to the query endpoint.
    AppliedFilters1:
      title: AppliedFilters1
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType1'
      description: A filter object specific to the query endpoint.
    AppliedFilters2:
      title: AppliedFilters2
      type: object
      properties:
        artifact:
          type: string
          description: The artifact
          example: google.com
        artifact_type:
          $ref: '#/components/schemas/ArtifactType'
        end_date:
          type: string
          description: The end window
          example: 2021-09-29
        interval:
          type: string
          description: The optional interval for the aggregate
          example: 1d
        query_type:
          $ref: '#/components/schemas/QueryType2'
        start_date:
          type: string
          description: The start window
          example: 2021-09-22
      description: A filter object specific to the query endpoint.
    AppliedFilters3:
      title: AppliedFilters3
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType3'
      description: A filter object specific to the query endpoint.
    AppliedFilters4:
      title: AppliedFilters4
      type: object
      properties:
        exclude:
          type: boolean
          description: Flag to indicate if the filter value should be excluded
          example: false
        id:
          $ref: '#/components/schemas/Id'
        isRange:
          type: boolean
          description: Flag to indicate if the filter value is a range
          example: false
        partial:
          type: boolean
          description: If the filter should do partial matching
          example: true
        rangeValue: {}
        value:
          type: string
          description: The filter value
          nullable: true
          example: google
    AppliedFilters5:
      title: AppliedFilters5
      type: object
      properties:
        exclude:
          type: boolean
          description: Flag to indicate if the filter value should be excluded
          example: false
        id:
          $ref: '#/components/schemas/Id1'
        isRange:
          type: boolean
          description: Flag to indicate if the filter value is a range
          example: true
        partial:
          type: boolean
          description: If the filter should do partial matching
          example: false
        rangeValue: {}
        value:
          type: string
          description: The filter value
          nullable: true
    AppliedFilters6:
      title: AppliedFilters6
      type: object
      properties:
        report_id:
          type: string
          description: ID (uuid) of the report
          example: 00000000-00000000-00000000-00000000
      description: A filter object specific to the query endpoint.
    AppliedFilters7:
      title: AppliedFilters7
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType4'
      description: A filter object specific to the query endpoint.
    ArtifactType:
      title: ArtifactType
      enum:
      - domain.keyword
      - domain_2tld.keyword
      - nameserver_tld.keyword
      - nameserver.keyword
      - nameserver_ip.keyword
      - response.a.keyword
      - response.aaaa.keyword
      - response.cname.keyword
      - response.cname_2tld.keyword
      type: string
      description: The artifact type
      example: domain.keyword
    Id:
      title: Id
      enum:
      - domain
      - domain_2tld
      - domain_tld
      - domain_age
      - query_type
      - response_code
      - ttl
      - nameserver
      - nameserver_2tld
      - nameserver_tld
      - nameserver_ip
      - a_record
      - aaaa_record
      - c_name
      - c_name_2tld
      - c_name_tld
      - registrar
      - reputation
      - datetime
      type: string
      description: The filter id
      example: domain
    Id1:
      title: Id1
      enum:
      - last_seen
      - artifact
      - hyas_status
      - alt_status
      - query_count
      type: string
      description: The filter id
      example: last_seen
    Log:
      title: Log
      type: object
      properties:
        alt_status:
          type: string
          description: The status of the request made through ALT [blocked, allow]
          example: allow
        artifact:
          type: string
          description: The artifact looked up
          example: google.com
        hyas_status:
          type: string
          description: The status of the request made through HYAS [blocked, allow]
          example: blocked
        last_seen:
          type: string
          description: The most recent query for the artifact
          example: 2021-11-05T05:00:00
        query_count:
          type: integer
          description: The aggregated count of how many times the artifact was looked up, limited to the current params
          format: int32
          example: 100
    Query2:
      title: Query2
      type: object
      properties:
        count:
          type: integer
          description: Query type count
          format: int32
          example: 2058
        key:
          type: string
          description: Query type key
          example: AAAA
        name:
          type: string
          description: Query type display name
          example: AAAA
      description: Query type
    QueryType:
      title: QueryType
      enum:
      - domain
      - fqdn
      - country
      - tld
      - registrar
      type: string
      description: The type of aggregate query to perform
    QueryType1:
      title: QueryType1
      enum:
      - block_queries
      - no_answer_queries
      - tor_prox_vpn_queries
      - suspicious_nameserver_queries
      type: string
      description: The type of bar chart query to perform
    QueryType2:
      title: QueryType2
      enum:
      - queries
      - queries_over_day
      - queries_over_hour
      type: string
      description: The type of query
      example: queries
    QueryType3:
      title: QueryType3
      enum:
      - queries
      - blocked_queries
      type: string
      description: The type of histogram query to perform
    QueryType4:
      title: QueryType4
      enum:
      - total
      - blocked
      - indicators
      type: string
      description: The type of summary query to perform
    RangeValue:
      title: RangeValue
      type: object
      properties:
        end:
          type: string
          description: The range end value
          example: 2021-09-24T01:21:58.283Z
        start:
          type: string
          description: The range start value
          example: 2021-09-17T01:21:58.283Z
    Report:
      title: Report
      type: object
      properties:
        client_id:
          type: string
          description: Client ID
        datetime:
          type: string
          description: Report generation datetime
        datetime_end:
          type: string
          description: Report end date
        datetime_start:
          type: string
          description: Report start date
        report_id:
          type: string
          description: Report ID
      description: Report
    Response:
      title: Response
      type: object
      properties:
        count:
          type: integer
          description: Response code count
          format: int32
          example: 8980
        key:
          type: string
          description: Response code key
          example: NoError
        name:
          type: string
          description: Response code display name
          example: NoError
      description: Response codes
    TopItem:
      title: TopItem
      type: object
      properties:
        current_doc_count:
          type: integer
          format: int32
          example: 9116
        key:
          type: string
          example: debug.opendns.com
        previous_doc_count:
          type: integer
          format: int32
          example: 7151
    TopItem1:
      title: TopItem1
      type: object
      properties:
        current_doc_count:
          type: integer
          format: int32
          example: 369
        key:
          type: string
          example: 2021-09-20 00:00:00
        previous_doc_count:
          type: integer
          format: int32
          example: 303
        previous_key:
          type: string
          example: 2021-09-13 00:00:00
    AggregatesResponse:
      title: AggregatesResponse
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: fqdn
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem'
          description: Top items
    Aggregates2:
      title: Aggregates2
      type: object
      properties:
        queries:
          type: array
          items:
            $ref: '#/components/schemas/Query2'
          description: Collection of query type codes and counts
        responses:
          type: array
          items:
            $ref: '#/components/schemas/Response'
          description: Collection of response codes and counts
    AppliedFilters9:
      title: AppliedFilters9
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType'
        top_count:
          type: integer
          description: How many aggregate values to get
          format: int32
          example: 25
    AppliedFilters12:
      title: AppliedFilters12
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType1'
    AppliedFilters22:
      title: AppliedFilters22
      type: object
      properties:
        artifact:
          type: string
          description: The artifact
          example: google.com
        artifact_type:
          $ref: '#/components/schemas/ArtifactType'
        end_date:
          type: string
          description: The end window
          example: 2021-09-29
        interval:
          type: string
          description: The optional interval for the aggregate
          example: 1d
        query_type:
          $ref: '#/components/schemas/QueryType2'
        start_date:
          type: string
          description: The start window
          example: 2021-09-22
    AppliedFilters32:
      title: AppliedFilters32
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType3'
    AppliedFilters62:
      title: AppliedFilters62
      type: object
      properties:
        report_id:
          type: string
          description: ID (uuid) of the report
          example: 00000000-00000000-00000000-00000000
    AppliedFilters72:
      title: AppliedFilters72
      type: object
      properties:
        query_type:
          $ref: '#/components/schemas/QueryType4'
    BarResponse1:
      title: BarResponse1
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: no_answer_queries
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem1'
          description: Top items
    HistogramArtifactResponse1:
      title: HistogramArtifactResponse1
      type: object
      properties:
        days:
          type: integer
          description: The number of days the histogram is for
          format: int32
        query_type:
          type: string
          description: The query type that the histogram is for
    HistogramResponse1:
      title: HistogramResponse1
      type: object
      properties:
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: queries
        top_items:
          type: array
          items:
            $ref: '#/components/schemas/TopItem'
          description: Top items
    LogsResponse:
      title: LogsResponse
      type: object
      properties:
        aggregates:
          $ref: '#/components/schemas/Aggregates2'
        total_count:
          type: integer
          description: total count of records without pagination
          format: int32
          example: 197
    PassthroughResponse1:
      title: PassthroughResponse1
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/Log'
          description: Collection of passthrough records
        total_count:
          type: integer
          description: total count of records without pagination
          format: int32
          example: 197
    ReportsResponse1:
      title: ReportsResponse1
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
          description: Collection of reports
        total_count:
          type: integer
          description: The total report count
          format: int32
    SummaryResponse1:
      title: SummaryResponse1
      type: object
      properties:
        day_count:
          type: integer
          format: int32
          example: 1
        query_type:
          type: string
          description: The query type that the aggregate is for
          example: blocked
        total_count:
          type: integer
          format: int32
          example: 0
  securitySchemes:
    external_auth:
      type: apiKey
      name: X-API-Key
      in: header
security:
- external_auth: []
tags:
- name: Overview
- name: Logs
- name: Passthrough
- name: Reports