GET: National Cybersecurity Observations – Bitsight Knowledge Base

November 8, 2021: Organized parameters by scope filtering or data filtering parameters; Added shortcuts to sections.
July 7, 2021: Expanded on observations field.
January 11, 2021: Clarification on accepted values for using the open_ports parameter; added date_interval.

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
- Scope Filtering
- Data Filtering
Example Request
Example Response
Response Attributes

Parameters

See query parameters for details on the cursor parameter.

Scope Filtering

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

Articles in this section