GET: National Cybersecurity Observations – Bitsight Knowledge Base

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 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.