Skip to content

API: Scan

Jump to bottom
elsif2 edited this page Apr 2, 2024 · 8 revisions

Scan API

An API to interact with the scan project. Please refer to the API: Documentation pages for testing details and examples.

Each of the methods in this API require special authorization.

Methods

  • network - Returns a list of CIDR blocks Shadowserver uses for network scans.
  • ssl - Query the collected data from the daily SSL scans.
  • target-update - Update the domain target list for an organization.

scan/network

Returns a list of CIDR blocks Shadowserver uses for network scans.

Fields:

apikey : string : your api key

Example:

$ ./call-api.py scan/network '{}' pretty
[
    "2001:470:1:c84::/64",
    "64.62.197.0/24",
    "184.105.237.192/26"
]

scan/ssl

Query the collected data from the daily SSL scans.

Fields:

apikey : string : your api key
query : dictionary : query parameters
date : string : date (YYYY-MM-DD) or range (YYYY-MM-DD:YYYY-MM-DD) 'now' may be used in place of a date
page : number : default is 1; used to obtain additional pages of results

Help

$ ./call-api.py scan/ssl '{"help":true}' pretty
[
    "algorithm",
    "asn",
    "asn_name",
    "auth_ssl_response",
    "auth_tls_response",
    "available_ciphers",
    "available_compression",
    "available_kex",
    "available_mac",
    "banner",
    "bluekeep_vulnerable",
    "browser_error",
    "browser_trusted",
    "cert_expiration_date",
    "cert_expired",
    "cert_issue_date",
    "cert_length",
    "cert_serial_number",
    "cert_valid",
    "cipher_suite",
    "city",
    "content_length",
    "content_type",
    "county_fips",
    "county_name",
    "cve20190708_vulnerable",
    "device_model",
    "device_sector",
    "device_type",
    "device_vendor",
    "device_version",
    "dss_dsa_public_g",
    "dss_dsa_public_p",
    "dss_dsa_public_q",
    "dss_dsa_public_y",
    "dss_generator",
    "dss_generator_length",
    "dss_prime",
    "dss_prime_length",
    "dss_public_key",
    "dss_public_key_length",
    "ecdsa_curve",
    "ecdsa_curve25519",
    "ecdsa_public_key_b",
    "ecdsa_public_key_gx",
    "ecdsa_public_key_gy",
    "ecdsa_public_key_length",
    "ecdsa_public_key_n",
    "ecdsa_public_key_p",
    "ecdsa_public_key_x",
    "ecdsa_public_key_y",
    "ed25519_cert_public_key_bytes",
    "ed25519_cert_public_key_duration",
    "ed25519_cert_public_key_keyid",
    "ed25519_cert_public_key_nonce",
    "ed25519_cert_public_key_principles",
    "ed25519_cert_public_key_raw",
    "ed25519_cert_public_key_serial",
    "ed25519_cert_public_key_sha256",
    "ed25519_cert_public_key_sig_raw",
    "ed25519_cert_public_key_sigkey_bytes",
    "ed25519_cert_public_key_sigkey_raw",
    "ed25519_cert_public_key_sigkey_sha256",
    "ed25519_cert_public_key_sigkey_value",
    "ed25519_cert_public_key_type_id",
    "ed25519_cert_public_key_type_name",
    "ed25519_cert_public_key_valid_after",
    "ed25519_cert_public_key_valid_before",
    "ed25519_curve25519",
    "freak_cipher_suite",
    "freak_vulnerable",
    "geo",
    "handshake",
    "hostname",
    "http_code",
    "http_connection",
    "http_date",
    "http_info",
    "http_ipv4",
    "http_ipv6",
    "http_name",
    "http_port",
    "http_ptr",
    "http_reason",
    "http_response_type",
    "http_target",
    "ip",
    "isp_name",
    "issuer_business_category",
    "issuer_common_name",
    "issuer_country",
    "issuer_email_address",
    "issuer_given_name",
    "issuer_locality_name",
    "issuer_organization_name",
    "issuer_organization_unit_name",
    "issuer_postal_code",
    "issuer_serialnumber",
    "issuer_state_or_province_name",
    "issuer_street_address",
    "issuer_surname",
    "jarm",
    "key_algorithm",
    "latitude",
    "longitude",
    "md5_fingerprint",
    "mdns_ipv4",
    "mdns_ipv6",
    "mdns_name",
    "naics",
    "port",
    "protocol",
    "public_key_md5",
    "public_key_sha1",
    "public_key_sha256",
    "public_key_sha512",
    "rdp_protocol",
    "region",
    "rsa_exponent",
    "rsa_generator",
    "rsa_generator_length",
    "rsa_length",
    "rsa_modulus",
    "rsa_prime",
    "rsa_prime_length",
    "rsa_public_key",
    "rsa_public_key_length",
    "rsubject_email_address",
    "sector",
    "selected_cipher",
    "selected_compression",
    "selected_kex",
    "selected_mac",
    "self_signed",
    "server_cookie",
    "server_host_key",
    "server_host_key_sha256",
    "server_signature_raw",
    "server_signature_value",
    "server_type",
    "serverid_comment",
    "serverid_raw",
    "serverid_software",
    "serverid_version",
    "services",
    "set_cookie",
    "sha1_fingerprint",
    "sha256_fingerprint",
    "sha512_fingerprint",
    "signature_algorithm",
    "source",
    "ssl_version",
    "sslv3_supported",
    "subject_business_category",
    "subject_common_name",
    "subject_country",
    "subject_email_address",
    "subject_given_name",
    "subject_locality_name",
    "subject_organization_name",
    "subject_organization_unit_name",
    "subject_postal_code",
    "subject_serial_number",
    "subject_state_or_province_name",
    "subject_street_address",
    "subject_surname",
    "sysdesc",
    "sysname",
    "tag",
    "timestamp",
    "tlsv13_cipher",
    "tlsv13_support",
    "transfer_encoding",
    "type",
    "userauth_methods",
    "validation_level",
    "version",
    "workstation_info",
    "workstation_ipv4",
    "workstation_ipv6",
    "workstation_name",
    "www_authenticate"
]

Response:

array of up to 1,000 matching records

Example:

$ ./call-api.py scan/ssl '{"port":443, "limit":1, "date":"2020-12-21"}' pretty
[
    {
        "issuer_given_name": "",
        "city": "ASHBURN",
        "subject_business_category": "",
        "transfer_encoding": "",
        "browser_trusted": "Y",
        "subject_serial_number": "",
        "hostname": "bst-2e1af4ee-dee0-4779-b1fd-6741ae72053d.bastion.azure.com",
        "subject_surname": "",
        "issuer_surname": "",
        "sic": null,
        "issuer_business_category": "",
        "public_key_sha512": "68:DD:8C:32:A0:D3:2A:EB:06:48:5F:CC:F5:C3:AF:83:A5:3A:1C:BC:A5:E5:68:0B:D7:2A:9B:14:3E:43:24:A1:01:11:F6:0C:5D:6F:74:41:10:2C:E1:75:04:B0:E8:4E:00:49:2E:12:D5:87:45:D7:BD:7B:DD:3C:E9:7B:DE:67",
        "issuer_organization_unit_name": "",
        "inet": null,
        "cipher_suite": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
        "geo": "US",
        "cert_length": "2048",
        "subject_locality_name": "Redmond",
        "server_type": "",
        "public_key_md5": "9F:30:13:7B:19:8B:D4:5E:2D:7A:B6:E9:72:D6:C1:97",
        "county_fips": "51107",
        "cert_serial_number": "33000562A66FC02BB3CE2C1C670000000562A6",
        "validation_level": "OV",
        "set_cookie": "JSESSIONID=F1177189F27A64A5C4880923655FF3CB; Path=/; Secure; Http",
        "browser_error": "",
        "issuer_organization_name": "Microsoft Corporation",
        "subject_state_or_province_name": "WA",
        "protocol": "tcp",
        "jarm": "2ad2ad0002ad2ad0002ad2ad2ad2adf05f3b95c2927ff44a7871306bfc5465",
        "key_algorithm": "rsaEncryption",
        "asn": "8075",
        "handshake": "TLSv1.2",
        "http_connection": "",
        "content_length": "4280",
        "issuer_country": "US",
        "signature_algorithm": "sha384WithRSAEncryption",
        "isp_name": "MICROSOFT CORP",
        "cert_issue_date": "2020-12-14 23:16:55",
        "www_authenticate": "",
        "source": null,
        "issuer_street_address": "",
        "content_type": "text/html",
        "type": "ssl",
        "subject_common_name": "bst-2e1af4ee-dee0-4779-b1fd-6741ae72053d.bastion.azure.com",
        "sslv3_supported": "N",
        "ip": "20.49.8.233",
        "freak_vulnerable": "N",
        "sector": "Defense Industrial Base",
        "naics": "334111",
        "subject_postal_code": "",
        "tlsv13_support": "N",
        "freak_cipher_suite": "",
        "county_name": "LOUDOUN",
        "issuer_serial_number": null,
        "subject_organization_name": "Microsoft Corporation",
        "tag": [
            "ssl"
        ],
        "subject_street_address": "",
        "http_date": "Mon, 21 Dec 2020 00:43:55 GMT",
        "cert_expired": "N",
        "http_reason": "",
        "port": "443",
        "http_response_type": "HTTP/1.1",
        "public_key_sha256": "82:1D:AE:D6:D8:F6:2A:76:B1:ED:11:70:8F:88:C1:0A:1D:DA:B5:F0:99:50:D2:CB:5D:76:78:2F:13:D9:17:87",
        "md5_fingerprint": "95:87:03:4A:E5:B6:2C:C1:E7:BE:0E:93:EB:38:DC:B7",
        "latitude": "39.03",
        "sha512_fingerprint": "C5:C0:1D:E6:2C:EB:80:1D:3C:71:5A:41:56:70:80:5B:6B:AE:FB:8E:FA:CE:A6:20:C0:25:EE:E1:E2:2E:86:3A:70:16:5C:96:18:07:E9:01:00:12:26:6C:25:5E:04:88:67:73:50:BD:5A:79:5F:55:74:E7:5E:10:D7:23:1B:AF",
        "issuer_common_name": "Microsoft Azure TLS Issuing CA 02",
        "subject_email_address": "",
        "sha1_fingerprint": "B1:5F:12:E6:5F:81:84:F4:CE:E0:9F:2A:4A:F5:69:20:AB:7B:42:16",
        "longitude": "-77.49",
        "issuer_locality_name": "",
        "http_code": "200",
        "issuer_email_address": "",
        "tlsv13_cipher": "",
        "asn_name": "MICROSOFT-CORP-MSN-A",
        "public_key_sha1": "8A:A6:48:32:FC:63:7C:B7:69:B2:6E:4B:F9:84:12:D3:99:02:40:97",
        "issuer_serialnumber": "",
        "issuer_postal_code": "",
        "subject_organization_unit_name": "",
        "issuer_state_or_province_name": "",
        "region": "VIRGINIA",
        "subject_given_name": "",
        "cert_valid": "Y",
        "timestamp": "2020-12-21 00:43:52Z",
        "sha256_fingerprint": "AE:34:9F:8F:EA:91:0F:06:05:39:5D:A7:23:C2:46:34:BB:A3:C7:F1:56:94:7D:13:44:EC:48:54:F5:D8:4B:96",
        "subject_country": "US",
        "self_signed": "N",
        "cert_expiration_date": "2021-12-09 23:16:55",
        "ssl_version": "2"
    }
]

scan/target-update

Update the domain target list for an organization.

Required Fields:

apikey : string : Your API key
data   : string : target contents

Response:

JSON object containing result details

The data must contain one or more fully qualified domain names separated by any combination of commas, spaces, or newlines.

Successful Example:

$ ./call-api.py scan/target-update '{"data":"www.example.com mail.example.com"}' pretty

{
  "accepted":
        { "count": 2 }
}

Error Example:

$ ./call-api.py scan/target-update {} pretty
{
  "error": "Access denied"
}

A call-api-json.py script is available to send large updates as a JSON file:

$ python3 call-api-json.py scan/target-update update.json

Sample update.json:

{
    "data": "www.example.com
    mail.example.com"
}
Clone this wiki locally