GET: National Cybersecurity Observation Counts – Bitsight Knowledge Base

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.

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		Description	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` (Default) `30d`
industries Query		Filter by multiple industries.	[String] Comma-separated industry names. See industries.
industry		Filter by industry.	[String] Comma-separated industry name. See industries.
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` (Default) `monthly`

Output Options

Parameter	Description	Values
normalize_counts	Normalize based on 100K habitants.	[Boolean] `true` = Normalize

Data Filtering

Parameter	Description	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` (Default) = All vulnerabilities, regardless of confidence level.

Aggregating Results

Parameter	Description	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 Description 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`

Articles in this section