- 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
andindustry_sector
details when using theindustry
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
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]
|
|
industriesQuery |
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]
|
|
ips |
Filter by multiple IPV4 or IPV6 addresses. | [Array] Comma-separated IP addresses.
|
|
period |
Filter by time period. | [String]
|
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_typesQuery |
Filter by risk types. | [Array] Comma-separated risk type slug names. See risk types. |
vulnerabilitiesQuery |
Filter by vulnerabilities. | [String] Comma-separated vulnerability names or CVE ID. |
vulnerability_classificationQuery |
Filter by vulnerability confidence level.
Only applicable with the |
[String]
|
Aggregating Results
Parameter | Description | Values |
---|---|---|
agg |
Contain aggregated values for a particular category. Categories:
|
[String]
Example:
|
Results by Category
Parameter | Description | Values |
---|---|---|
all |
Retrieves all values of a particular category. Categories:
|
[String]
Example:
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 | ||||
---|---|---|---|---|---|
scopeObject |
Observation details of the requested country. | ||||
typeString |
For internal Bitsight use. | ||||
valueString |
The 2-letter country code of the requested country. | ||||
date_intervalString |
The date interval (7 days or 30 days). | ||||
end_dateString [ YYYY‑MM‑DD ] |
The ending date of the interval. | ||||
periodString |
The time period. | ||||
countsObject |
Details of the requested country grouped by data set. | ||||
Data Sets |
|
||||
risk_vectorsObject |
Risk type details of the requested country. | ||||
Risk Category Slug Name Array |
Risk category details of this country.
|
||||
infectionsArray |
Infection details of the requested country. | ||||
categoriesArray |
File Sharing category details of the requested country. | ||||
vulnerabilitiesArray |
Vulnerability details of the requested country. | ||||
open_portsArray |
Open port details of the requested country. | ||||
Details | Details for each data set object. | ||||
Object | A data set and its details. | ||||
nameString |
|
||||
countInteger |
|
||||
country_codeString |
The country code. | ||||
country_nameString |
The name of the country. | ||||
industry_guidString [ industry_guid ] |
If either the industry or industries parameter is used, this industry unique identifier is displayed within the details. |
||||
industry_sectorString |
If either the industry or industries parameter is used, this industry name is displayed within the details. |
||||
typeString |
For internal Bitsight use.
|