GET: National Cybersecurity Observation Counts – Bitsight Knowledge Base

https://api.bitsighttech.com/sovereign/observations/counts

Retrieve the total count of all observed findings throughout all risk vectors that were observed in companies attributed to a country.

This includes observation details on the following data sets:

Infections
Open Ports
User Behavior
Compromised Systems
Diligence
File Sharing
Vulnerabilities

This endpoint is only available for users with access to the National Cybersecurity app. It only returns information for countries you subscribe to.

Sections:

Parameters
Example Request
Example Response
Response Attributes

Parameters

Scope Filtering

Parameter Values

country_code

Filter by country.

[String] 2-letter country code.

country_codes

Filter by multiple country codes.

[Array] Comma-separated 2-letter country codes.

Date

Filter by dates.

To get historical data between two dates, ensure the history parameter is set to true (history=true).

end_date

Filter by end date.

[String] YYYY-MM-DD

start_date

Filter by start date.

[String] YYYY-MM-DD

history

Allow the retrieval of historical data between two dates (start_date & end_date).

[Boolean] true = Allow date parameters.

date_interval

Filter by date interval.

[String]

↻ 7d
30d

industries

[Query] Filter by multiple industries.

[String] Comma-separated industry names. Use GET: Industries with the show_all parameter set to true [/v1/industries?show_all=true].

industry

Filter by industry.

[String] Comma-separated industry name. Use GET: Industries with the show_all parameter set to true [/v1/industries?show_all=true].

ip

Filter by IPV4 or IPV6 address.

[String]

IPv4 Address (Dotted Notation)
IPv6 Address

ips

Filter by multiple IPV4 or IPV6 addresses.

[Array] Comma-separated IP addresses.

IPv4 Address (Dotted Notation)
IPv6 Address

period

Filter by time period.

[String]

↻ daily
monthly

Output Options

Parameter Values

normalize_counts

Normalize based on 100K habitants.

[Boolean] true = Normalize

Data Filtering

Parameter	Values
categories Filter by file sharing category (User Behavior).	[Array] Comma-separated File Sharing category names.
infections Filter by infections.	[Array] Comma-separated infection names. See `infections` in GET: National Cybersecurity Observation Details by Risk Type.
open_ports Filter by network services.	[Array] Comma-separated port numbers or service names. See `service` in GET: National Cybersecurity Observation Details by Risk Type. This is case-sensitive.
risk_types [Query] Filter by risk types.	[Array] Comma-separated risk type slug names. See risk types.
vulnerabilities [Query] Filter by vulnerabilities.	[String] Comma-separated vulnerability names or CVE ID.
vulnerability_classification [Query] Filter by vulnerability confidence level. Only applicable with the `vulnerabilities` parameter.	[String] `Potential` = Low confidence/potential vulnerabilities. `Confirmed` = High confidence or confirmed vulnerabilities. ↻ `All` = All vulnerabilities, regardless of confidence level.

Aggregating Results

Parameter Values

agg

Contain aggregated values for a particular category. Categories:

risk_types
infections
categories
vulnerabilities
open_ports

[String]

Example:
open_ports=agg

Results by Category

Parameter Values

all

Retrieves all values of a particular category. Categories:

risk_types
infections
categories
vulnerabilities
open_ports

[String]

Example:
risk_types=all

Default: All categories.

Example Request

curl 'https://api.bitsighttech.com/sovereign/observations/counts?country_code=AA' -u api_token:

Example Response

{
  "scope": {
    "date_interval": "7d",
    "type": "country",
    "end_date": "2020-07-09",
    "value": "AA"
  },
  "counts": {
    "infections": [
      […]
      {
        "count": 1,
        "country_name": "Example Country",
        "name": "Locky",
        "country_code": "AA"
      }
    ],
    "open_ports": [
      […]
      {
        "count": 1,
        "country_name": "Example Country",
        "name": "Port 8112",
        "country_code": "AA"
      }
    ],
    "risk_vectors": {
      "user_behavior": [
        {
          "count": 123,
          "country_name": "Example Country",
          "name": "file_sharing",
          "country_code": "AA"
        }
      ],
      "compromised_systems": [
        […]
        {
          "count": 123,
          "country_name": "Example Country",
          "name": "malware_servers",
          "country_code": "AA"
        }
      ],
      "diligence": [
        […]
        {
          "count": 123,
          "country_name": "Example Country",
          "name": "application_security",
          "country_code": "AA"
        }
      ]
    },
    "categories": [
      […]
      {
        "count": 123,
        "country_name": "Example Country",
        "name": "Other",
        "country_code": "AA"
      }
    ],
    "vulnerabilities": [
      […]
      {
        "count": 123,
        "country_name": "Example Country",
        "name": "CVE-2018-11766",
        "country_code": "AA"
      }
    ]
  }
}

Response Attributes

Field					Description
scope Object					Observation details of the requested country.
	type String				For internal Bitsight use.
	value String				The 2-letter country code of the requested country.
	date_interval String				The date interval (7 days or 30 days).
	end_date String [`YYYY‑MM‑DD`]				The ending date of the interval.
	period String				The time period.
counts Object					Details of the requested country grouped by data set.
	Data Sets				`risk_vectors` Compromised Systems Diligence User Behavior `infections` = Infections `categories` = File Sharing `vulnerabilities` = Vulnerabilities `open_ports` = Open Ports
		risk_vectors Object			Risk type details of the requested country.
			Risk Category Slug Name Array		Risk category details of this country. `compromised_systems` `diligence` `user_behavior`
		infections Array			Infection details of the requested country.
		categories Array			File Sharing category details of the requested country.
		vulnerabilities Array			Vulnerability details of the requested country.
		open_ports Array			Open port details of the requested country.
		Details			Details for each data set object.
			Object		A data set and its details.
				name String	Risk Category Slug Name = The slug name of the risk vector. `infections` = The name of the infection family. `categories` = The name of the file sharing category. `vulnerabilities` = The name or CVE ID of the vulnerability.
				count Integer	Risk Category Slug Name = The amount of findings for the risk vector present in the country. `infections` = The amount of infections present in the country. `categories` = The number of files shared in the country. `vulnerabilities` = The amount of vulnerabilities present in the country.
				country_code String	The country code.
				country_name String	The name of the country.
				industry_guid String [`industry_guid`]	If either the `industry` or `industries` parameter is used, this industry unique identifier is displayed within the details.
				industry_sector String	If either the `industry` or `industries` parameter is used, this industry name is displayed within the details.
				type String	For internal Bitsight use. `COUNTRY` `COUNTRY-INDUSTRY`

December 5, 2023: How to get the industry name.
November 8, 2021: Organized parameters by parameter types (Scope Filtering, Output Options, Data Filtering, Aggregating Results, Results by Category); Added shortcuts to sections.
July 13, 2020: Get industry_guid and industry_sector details when using the industry parameter.

Parameters

Scope Filtering

Output Options

Data Filtering

Aggregating Results

Results by Category

Example Request

Example Response

Response Attributes

Related articles