GET: National Cybersecurity Observation Counts

Ingrid

⇤ Sovereign

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

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.
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.