GET: National Cybersecurity Observations

Ingrid

⇤ Sovereign

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

Use this endpoint to retrieve 1,000 of the most recent observations within your primary country.

This endpoint is only available for users with access to the National Cybersecurity app. It only returns information for your primary country.

Parameters

See query parameters for details on the cursor parameter.

Scope Filtering

Parameter Values 
country_codes

[Query] Filter by multiple countries.

 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

[Query] Filter by end date.

 [String] YYYY-MM-DD 
start_date

[Query] Filter by start date.

 [String] YYYY-MM-DD 
date_interval

[Query] Filter by date interval.

[String]

  • ↻ 7d
  • 30d
 
industries

[Query] Filter by multiple industries.

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

[Query] Filter by industry.

 [String] Industry name. Use GET: Industries with the show_all parameter set to true [/v1/industries?show_all=true]. 
ip

[Query] Filter by IP address.

Not all observations will necessarily be associated with an IP address.

 [String] IPV4 (Dotted Notation) or IPV6 IP address. 
ips

[Query] Filter by multiple IP addresses.

[Array] Comma-separated IP addresses.

  • IPv4 Address (Dotted Notation)
  • IPv6 Address
 
limit

[Query] Set the maximum number of results.

[Integer] A number greater than 0 (zero).

Default: 1000

Data Filtering

Parameter Values 
categories

[Query] Filter by file sharing category (User Behavior).

 [Array] Comma-separated File Sharing category names. 
infections

[Query] Filter by infections.

 [Array] Comma-separated infection names. See infections in GET: National Cybersecurity Observation Details by Risk Type. 
open_ports

[Query] 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.

Example Request

curl 'https://api.bitsighttech.com/sovereign/observations' -u api_token:

Example Response

{
  "has_more_observations": true,
  "links": {
    "next": "https://api.bitsighttech.com/sovereign/observations/?cursor=TkVYVCwxNjEwMjM2ODAwMDAwLDE2MTAzMTk3NzgwMDAsQUFBQUZYV0p0bkhsR0NxQkFBQUFBQmRqTnRKUWFIQkdhVzVuWlhKd2NtbHVkRFV1TlM0ek9BPT0%3D"
  },
  "included_observations": 1000,
  "observations": [
    {
      "risk_type": "insecure_systems",
      "observation_id": "AAAAFD5oh6zNVnIYAAAAABerK6tUb3JyZW50VHJhY2tlcjp0b3JyZW50X3RyYWNrZXJfZXhwaXJlZA==",
      "collection_date": "2021-06-26",
      "event_date": "2021-06-26",
      "occurrences": {
        "event_date": "2021-06-26",
        "representative_timestamp": "2021-06-26 23:54:56",
        "last_seen": "2021-06-26 23:54:56",
        "first_seen": "2021-06-26 00:18:11",
        "count": 108
      },
      "forensics": {
        "host_ip": "83.38.12.221"
        "host_port": 8443
      },
      "country": {
        "name": "Valencia (Spain)",
        "code": "ES-VC"
      },
      "entities": [
        {
          "name": "Anon Telecomm, Inc.",
          "guid": "12345678-abcd-efgh-1234-abcdefghijkl",
          "industry_sector": "Telecommunications",
          "in_portfolio": false,
          "has_parent": true,
          "is_service_provider": true,
          "sub_industry": "Telecommunications"
        }
      ],
      "details": {

        ⊕ See Details by Risk Type

      }
    }
  ],
  "cursors": {
    "next": "TkVYVCwxNjEwMjM2ODAwMDAwLDE2MTAzMTk3NzgwMDAsQUFBQUZYV0p0bkhsR0NxQkFBQUFBQmRqTnRKUWFIQkdhVzVuWlhKd2NtbHVkRFV1TlM0ek9BPT0="
  },
  "scope": {
    "date_interval": "7d",
    "type": "country",
    "end_date": "2021-01-10",
    "value": "US"
  }
}

Response Attributes

Field Description 
scope
Object		 Details of this request.
  
type
String		 For internal Bitsight use. 
value
String		 The two-letter country code. 
date_interval
String		 The date interval in the number of days. 
end_date
String [YYYY‑MM‑DD]		 The end date of the date interval. 
included_observations
Integer		 The number of observations included in the results. 
has_more_observations
Boolean		 true = Additional observations are available. 
cursors
Object		 Navigation for multiple pages of results. See pagination.
  
next
String		 The URL to navigate to the next page of results. 
observations
Array		 Observation details.
  Object A unique observation.
  
risk_type
String		 The slug name of the associated risk vector. 
observation_id
String		 An identifier for this observation. 
collection_date
String [YYYY-MM-DD]		 The date when findings were observed. 
event_date
String [YYYY-MM-DD]		 The date when the observations rolled up into a finding. 
occurrences
Object		 Unique occurrences.
  
event_date
String [YYYY-MM-DD]		 The date of this occurrence. 
representative_timestamp
String [YYYY-MM-DD HH:MM:SS]		 The date and time of this occurrence. 
last_seen
String [YYYY-MM-DD HH:MM:SS]		 The most recent date and time when this observation occurred. 
first_seen
String [YYYY-MM-DD HH:MM:SS]		 The first date and time when this observation occurred. 
count
Integer		 The total count of this unique occurrence. 
forensics
Object		 Forensic details.
  
host_ip
String		 The host IP address. 
host_port
Integer		 The host port number. 
country
Object		 The country of origin.
  
name
String		 The name of this country. 
code
String		 The country code. 
entities
Array		 Companies in the Bitsight inventory.
  Object A company.
  
name
String		 The name of this company. 
guid
String [entity_guid]		 The unique identifier of this company. 
industry_sector
String		 The industry of this company. 
in_portfolio
Boolean		 true = This company is in your portfolio. 
has_parent
Boolean		 true = This company is a child subsidiary of another company within the organization. 
is_service_provider
Boolean		 true = This company is a service provider. 
sub_industry
String		 The sub-industry of this company. 
details
Object		 Observation details. The details vary, depending on the risk type [risk_type]. See observation details by risk type. 
links
Object		 Navigation for multiple pages of results. See pagination.
  
next
String		 The URL to navigate to the next page of results.
  • December 5, 2023: How to get the industry name.
  • November 8, 2021: Organized parameters by scope filtering or data filtering parameters; Added shortcuts to sections.
  • July 7, 2021: Expanded on observations field.
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.