GET: Detailed Company Observations

Ingrid

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.

company_guid

* Required.

[Path] Identify the company to query.

Value: [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.

Value: [String] Domain name.

Example: www.example.com
end_date

[Query] Filter by the observation’s end date.

Value: [String] YYYY-MM-DD

grades

[Query] Filter by finding grade.

Value: [String] Comma-separated finding grades.

ip_address

[Query] Filter by IP address.

Not all observations are associated with an IP address.

Value: [String] Any IPv4 address in dotted notation or an IPv6 address.

Examples:

  • IPv4 address = 192.0.2.0
  • IPv6 address = 2001:DB8::
limit

[Query] Set the maximum number of results. The results will include fewer records (even zero), but not more.

Value: [Integer] Any number from 1 to 1000.

Default: ↻ 100
port

[Query] Filter observations on a particular network port.

Value: [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.

Value: [String] Comma-separated risk types.

start_date

[Query] Filter by the observation’s starting date.

Value: [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 
data

Array

 Observations for the queried company.
  
risk_type

String

 The slug name of this observation’s risk type. 
observation_id

String

 The unique identifier of this observation. 
collection_date

String [YYYY‑MM‑DD]

 The date when the observation was collected from the data source. 
event_date

String [YYYY‑MM‑DD]

 The date when this observation was considered as an event. 
forensics

Object

 Fields for conducting network forensics.
  
domain_name

String

 The host domain. 
host_ip

String

 The host IP address. 
host_port

Integer

 The host port number. 
details

Object

 Observation details.
  The included details vary depending on the risk vector. See observation details by risk type. 
occurrences

Object

 Occurrence details.
  
first_seen

String [YYYY‑MM‑DD HH:MM:SS]

 The starting date and time of this occurrence’s duration. 
last_seen

String [YYYY‑MM‑DD HH:MM:SS]

 The ending date and time of this occurrence’s duration. 
representative_timestamp

String [YYYY‑MM‑DD HH:MM:SS]

 The representative date and time of this occurrence. 
count

Integer

 The number of times this observation was counted. 
cursors

Object

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

String

 The unique identifier of the next observation. 
next_url

String

 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.
Was this article helpful?
2 out of 2 found this helpful

Comments

4 comments
Date Votes
  • Avatar
    David
    (Edited )

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

    0
  • Avatar
    Ingrid

    Thanks for bringing this to our attention, David. The filter keywords have been updated to include all risk types.

    0
  • Avatar
    Alejandro Sauter

    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. 

    0
  • Avatar
    Ingrid

    The links to the DNS query types and response codes have been fixed.

    1

Please sign in to leave a comment.