https://api.bitsighttech.com/ratings/v1/companies/company_guid/observations
Retrieve detailed information (observations) about the risk category data of companies in your portfolio.
The information is similar to what is shown on the Forensics view of a security rating report, but includes Compromised Systems, Diligence, and User Behavior. Observations do not all necessarily impact the company’s rating.
Events and Observations
The Bitsight platform normally displays events in groups so that the relation between individual events is obvious, especially if they span several days. This endpoint shows the individual events that comprise the ones shown in the platform.
Example: An event shown in the platform that spans 8 days may show up as 8 or more separate observations in the API.
Parameters
Observations can be filtered with query parameters to make it easier to pick out relevant items from our data stores.
* Required.
Parameter | Values |
---|---|
company_guid * [Path] Identify the company to query. |
[String] Company unique identifier [entity_guid ]. See GET: Portfolio Details. |
domain_name [Query] Filter by domain name. Not all observations are associated with a domain. |
[String] Domain name.
Example:
|
end_date [Query] Filter by the observation’s end date. |
[String] YYYY-MM-DD
|
grades [Query] Filter by finding grade. |
[String] Comma-separated finding grades. |
ip_address [Query] Filter by IP address. Not all observations are associated with an IP address. |
[String] Any IPv4 address in dotted notation or an IPv6 address. Examples: |
limit [Query] Set the maximum number of results. The results will include fewer records (even zero), but not more. |
[Integer] Any number from
Default: ↻
|
port [Query] Filter observations on a particular network port. |
[Integer] The port number, up to 65535 . |
risk_types [Query] Filter by observation risk type. Access to some risk types is dependent on the subscription type. |
[String] Comma-separated risk types. |
start_date [Query] Filter by the observation’s starting date. |
[String] YYYY-MM-DD
|
Example Request
Use a company’s unique identifier (GUID) to look up its observations. You may opt to specify one or more risk types to return. See the query parameters or refer to the pagination recommendations.
curl 'https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/observations?risk_types=risk_type' -u api_token:
Example Response
If you specified more than one risk type in the risk_types
parameter of your request, the server will respond with an array of individual records from all the risk types you requested.
{ { "data":[ { "risk_type":"botnet_infections", "observation_id":"AAAAA1CH3qvE2t7jAAAAAHBXFvY=", "collection_date":"2020-08-05", "event_date":"2020-08-05", "forensics":{ ⊕ See Event Forensic Details }, "details":{ ⊕ See Observation Details } } ], "cursors":{ "next":"AAAAAAAAAGQKl0_OUZg4Yw==", "next_url":"https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/observations?cursor=AAAAAAAAAGQKl0_OUZg4Yw%3D%3D" } } }
Response Attributes
Observations are sorted by date, with the most recent first.
If the system returns a “Detail not found” message, please try using query parameters. No results matched the specified query parameters. Double check to make sure the specified parameters are spelled correctly or see the full list of parameters.
Observations will be returned as JSON and cannot be returned as XML. A JSON object is returned by the API with a data
array field. Separate objects of individual observations are within the data
array, with the following attributes:
Field | Description | |||
---|---|---|---|---|
dataArray |
Observations for the queried company. | |||
risk_typeString |
The slug name of this observation’s risk type. | |||
observation_idString |
The unique identifier of this observation. | |||
collection_dateString [ YYYY‑MM‑DD ] |
The date when the observation was collected from the data source. | |||
event_dateString [ YYYY‑MM‑DD ] |
The date when this observation was considered as an event. | |||
forensicsObject |
Fields for conducting network forensics. | |||
domain_nameString |
The host domain. | |||
host_ipString |
The host IP address. | |||
host_portInteger |
The host port number. | |||
detailsObject |
Observation details. | |||
The included details vary depending on the risk vector. See observation details by risk type. | ||||
occurrencesObject |
Occurrence details. | |||
first_seenString [ YYYY‑MM‑DD HH:MM:SS ] |
The starting date and time of this occurrence’s duration. | |||
last_seenString [ YYYY‑MM‑DD HH:MM:SS ] |
The ending date and time of this occurrence’s duration. | |||
representative_timestampString [ YYYY‑MM‑DD HH:MM:SS ] |
The representative date and time of this occurrence. | |||
countInteger |
The number of times this observation was counted. | |||
cursorsObject |
An opaque base64-encoded string that allows you to get the next or previous page of results, which is included with select endpoints with large datasets. If a query matches very few observations and the response contains a cursor but no data, the cursor can then be used to ask the server to continue searching. | |||
nextString |
The unique identifier of the next observation. | |||
next_urlString |
The URL to navigate to the next page of results. |
-
March 23, 2021: Filter (
grades
) by Compromised Systems and User Behavior finding grades. - August 18, 2020: Linked to observation details.
Feedback
4 comments
I have a question about the Filter Keywords. Do we have any additional keywords that are not in this list? I am doing some mappings and I get the feeling there are a few keyword filters missing here. Specifically mobile application security. (I see "endpoint_mobile" but want to know if there is another one for "application_security_mobile" for example.)
Thanks for bringing this to our attention, David. The filter keywords have been updated to include all risk types.
Under response attributes, the dns query_type and error_code lists are not linked. I tried searching for these but can't find them either.
The links to the DNS query types and response codes have been fixed.
Please sign in to leave a comment.