https://api.bitsighttech.com/ratings/v1/companies/entity_guid/findings
Get an organization’s finding details.
- This includes the finding details of risk types that affect or will affect security ratings; Compromised Systems, Diligence (except Domain Squatting), and User Behavior (File Sharing).
Does not include Domain Squatting, Security Incidents, and Other Disclosures.
- This does not include Domain Squatting and Public Disclosures (Security Incidents and Other Disclosures), as their findings cannot be queried via the API.
Parameters
Recommendations
- The return is limited to
100
results per page by default. Use thelimit
andoffset
parameters to modify this limit. - To view all findings, ensure the
affects_rating
parameter is not included. It is used to filter findings that have an impact on the letter grade. - Refer to the pagination fields (
links
,previous
,next
) to navigate multiple pages of results.
Risk Category Parameter
To get details on specific risk categories, use the risk_category
parameter along with the following comma-separated values [String]:
Compromised Systems
Diligence
User Behavior
Risk Vector Parameter
To get details on specific risk vectors, use the risk_vector
parameter along with the following comma-separated values [String]:
Compromised Systems
-
Botnet Infections =
botnet_infections
-
Spam Propagation =
spam_propagation
-
Malware Servers =
malware_servers
-
Unsolicited Communications =
unsolicited_comm
-
Potentially Exploited =
potentially_exploited
Diligence
-
SPF Domains =
spf
-
DKIM Records =
dkim
-
TLS/SSL Certificates =
ssl_certificates
-
TLS/SSL Configurations =
ssl_configurations
-
Open Ports =
open_ports
-
Web Application Headers =
application_security
-
Patching Cadence =
patching_cadence
-
Insecure Systems =
insecure_systems
-
Server Software =
server_software
-
Desktop Software =
desktop_software
-
Mobile Software =
mobile_software
-
DNSSEC Records =
dnssec
-
Mobile Application Security =
mobile_application_security
-
Web Application Security =
web_appsec
-
DMARC =
dmarc
- Domain Squatting - Findings for this risk vector cannot be queried via the findings API.
User Behavior (File Sharing)
User Behavior = file_sharing
Query Parameters
See query parameters for details on the following parameters:
fields
format
-
limit
(default: ↻100
) -
offset
(default: ↻100
) q
sort
Parameter | Values |
---|---|
affects_rating [Query] Filter by findings that have an impact on the letter grade. |
[Boolean] true = Include only the findings that have an impact on the letter grade. |
affects_rating_details [Query] Filter the result by the value of |
[String] Values may be used in combination.
|
assets.asset [Query] Filter by asset. |
[String]
|
assets.category [Query] Filter by asset importance. |
[String] See asset importance. |
assets.combined_importance [Query] Filter by combined asset importance. |
[String] Comma-separated asset importance. |
assets.hosted_by [Query] Filter by the hosting provider. |
[String] Hosting provider’s unique identifier [entity_guid ]. See GET: Portfolio Details. |
attributed_companies.guid [Query] Filter by companies in your Ratings Tree that are attributed to the finding. |
[Array] Comma-separated My Company or My Subsidiary unique identifiers [entity_guid ]. See GET: Portfolio Details. |
attributed_companies.name [Query] Filter by companies in your Ratings Tree that are attributed to the finding. |
[Array] Comma-separated company names. |
details.cvss.base_gte [Query] Include findings with vulnerabilities with a CVSS score greater than or equal to this value. |
[Decimal] 1 to 10
|
details.cvss.base_lte [Query] Include findings with vulnerabilities with a CVSS score less than or equal to this value. |
[Decimal] 1 to 10
|
details.grade [Query] Filter by Diligence finding grade or N/A for Compromised Systems and User Behavior findings. Incompatible with |
[String] Finding grades:
|
details.grade_gt [Query] Include a range from the selected Diligence finding grade to GOOD. Incompatible with |
[String] NEUTRAL < BAD < WARN < FAIR < GOOD
|
details.grade_lt [Query] Include a range from the selected Diligence finding grade to BAD. Incompatible with |
[String] NEUTRAL < BAD < WARN < FAIR < GOOD
|
details.infection.family [Query] Filter by infections. |
[String] Comma-separated infection names.
Example:
|
details.observed_ips_contains [Query] Include findings from a particular IP address. |
[String] IP Address |
details.vulnerabilities.severity [Query] Filter by vulnerability severity. |
[String] The Bitsight severity of vulnerabilities. |
evidence_key [Query] Filter by the company’s asset (domain or IP address) that’s attributed to the finding. |
[String]
|
expand [Query] Include additional information. |
[String]
|
first_seen [Query] Include findings that were first seen on this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
first_seen_gt [Query] Include findings that were first seen after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
first_seen_gte [Query] Include findings that were first seen on and after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
first_seen_lt [Query] Include findings that were first seen prior to this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
first_seen_lte [Query] Include findings that were first seen on and prior to this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
guid * [Path] Identify the company to query. |
[String] Portfolio company’s unique identifier [entity_guid ]. See GET: Portfolio Details. |
last_remediation_status_date [Query] Include findings that last had a remediation status change on this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_remediation_status_date_gt [Query] Include findings that last had a remediation status change after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_remediation_status_date_gte [Query] Include findings that last had a remediation status change on and after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_remediation_status_date_lt [Query] Include findings that last had a remediation status change prior to this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_remediation_status_date_lte [Query] Include findings that last had a remediation status change prior to and on this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_remediation_status_label [Query] Filter by the current remediation status of the finding. |
[String] The remediation status of the finding:
|
last_seen [Query] Include findings that were last seen on this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_seen_gt [Query] Include findings that were last seen after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_seen_gte [Query] Include findings that were last seen on and after this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_seen_lt [Query] Include findings that were last seen prior to this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
last_seen_lte [Query] Include findings that were last seen on and prior to this date. Incompatible with |
[String] Date [YYYY‑MM‑DD ] |
remediation_assignments [Query] Filter by users assigned to the findings. |
[String] Comma-separated user unique identifier [user_guid ]. See GET: Users. |
risk_vector_label [Query] Filter by particular risk vectors. Does not include Domain Squatting, Security Incidents, and Other Disclosures. |
[String] Comma-separated risk vector slug names. See risk types. |
severity [Query] Filter by finding severity. |
[Decimal] Severity. See range values. |
severity_gt [Query] Include finding severity that are of greater severity. |
[Decimal] Severity. See range values. |
severity_gte [Query] Include finding severity that are of greater or equal severity. |
[Decimal] Severity. See range values. |
severity_lt [Query] Include finding severity that are of lesser severity. |
[Decimal] Severity. See range values. |
severity_lte [Query] Include finding severity that are of lesser or equal severity. |
[Decimal] Severity. See range values. |
severity_category [Query] Filter by finding severity. |
[Decimal] Severity. See severities. |
tags_contains [Query] Filter by infrastructure tags. |
[String] Infrastructure tags, which are defined by the company to identify assets that belong to them. |
unsampled [Query] If you have Unsampled Findings [beta] enabled, get your My Company’s or My Subsidiary’s unsampled findingsdata. |
[Boolean]
|
vulnerabilities [Query] Filter by vulnerability. |
[String] Comma-separated vulnerability name. |
Example Request
curl https://api.bitsighttech.com/ratings/v1/companies/A9Jq47BBjea129322347d12e29c54b488752b3b71e/findings -u api_token:
Example Response
{ "links":{ "previous":null, "next":null }, "count":1, "results":[ { "temporary_id":"A9Jq47BBjea129322347d12e29c54b488752b3b71e", "affects_rating":false, "assets":[ { "asset":"11.111.111.111", "identifier":null, "category":"high", "importance":0.09, "is_ip":true, "asset_type":"IP", "is_monitored":false } ], "details":{ "cvss": { "base": [ 10.0 ] }, "check_pass":"", ⊕ Details Vary by Risk Vector "evidence_key":"11.111.111.111:23", "first_seen":"2019-05-29", "last_seen":"2019-12-20", "related_findings":[ ], "risk_category":"Diligence", "risk_vector":"open_ports", "risk_vector_label":"Open Ports", "rolledup_observation_id":"_aAAa1AA_a1aAA1A1aaAAa==", "severity":10.0, "severity_category":"severe", "tags":[ "Remote Office" ], "tag_details":[ { "guid":"4f99d64c-c3d8-4e08-b346-14f042e97116", "name":"Corporate Infra", "is_inherited":false, "is_public":false } ], "remediation_history":{ "last_requested_refresh_date":"2024-06-19", "last_refresh_status_date":"2024-06-23", "last_refresh_status_label":"failed", "last_refresh_reason_code":"asset unreachable" }, "asset_overrides":[ { "asset":"11.111.111.111", "importance":"high", "override_importance":null } ], "duration":"7 days", "comments":"User from Actors Films said: \"Look at this finding\" at 2018-11-29 20:30 UTC;\nArnold Brown said: \"I changed the remediation status.\" at 2020-08-18 18:38 UTC", "remaining_decay":90, "remediated":false, "impacts_risk_vector_details":"AFFECTS_RATING" "attributed_companies":[ { "guid":"44444444-cccc-4444-cccc-444444444444", "name":"Actors Film Studio" } ] }, } ] }
Response Attributes
Field | Description | |||
---|---|---|---|---|
links Object |
Navigation for multiple pages of results. See pagination. | |||
previous String |
The URL to navigate to the previous page of results. | |||
next String |
The URL to navigate to the next page of results. | |||
count Integer |
The number of findings. | |||
results Array |
Findings and their details. | |||
temporary_id String |
A temporary identifier for this finding. | |||
affects_rating Boolean |
Indicates if this finding has an impact on the letter grade. | |||
assets Array |
Details on assets attributed to the findings data. | |||
Object | An asset and its details. | |||
asset String |
The asset name. | |||
identifier String |
For internal Bitsight use. | |||
category String |
The Bitsight-calculated asset importance. | |||
importance Decimal |
The Bitsight-calculated asset importance. | |||
is_ip Boolean |
true = This asset is an IP address. |
|||
asset_type String |
The type of asset. | |||
is_monitored Boolean |
β This field is currently part of a beta feature. |
|||
details Object |
Details of this finding. The included keys vary, depending on the risk type. | |||
cvss Object |
If the finding has an associated vulnerability, the CVSS score is listed below. | |||
base Array |
The list of CVSS scores of vulnerabilities associated with this finding. | |||
check_pass String |
For internal Bitsight use. | |||
evidence_key String |
The company’s asset (domain or IP address) that’s attributed to the finding. The IP addresses of other companies are masked, in accordance with our responsible disclosure policy. Please review our terms and conditions, and then update your IP Visibility configurations accordingly. |
|||
first_seen String [ |
The date of the first observation. | |||
last_seen String [ |
The date of the most recent observation. | |||
related_findings Array |
Details of related findings. | |||
risk_category String |
The risk category associated with this finding. | |||
risk_vector String |
The slug name of the risk vector associated with this finding. | |||
risk_vector_label String |
The name of the risk vector associated with this finding. | |||
rolledup_observation_id String |
A stable and randomized identifier for findings. It is assigned to a finding when one or more observations with largely similar key properties occur in close succession. | |||
severity Decimal |
The severity of the finding, which is the measured risk that this finding introduces. | |||
severity_category String |
The slug name of the finding severity. | |||
tags Array |
Infrastructure tags that help identify this asset. | |||
tag_details Array |
If the expand parameter is set to tag_details (?expand=tag_details ), infrastructure tag information is included. |
|||
Object | The tag details. | |||
guid String [ |
The tag unique identifier. | |||
name String |
The tag name and value. | |||
is_inherited Boolean |
true = The tag is inherited. |
|||
is_public Boolean |
true = The tag is publicly visible. |
|||
remediation_history Object |
If ?expand=remediation_history parameter is set, the remediation history of the finding is included. |
|||
last_requested_refresh_date String [ |
The date when a finding refresh that included this finding was last requested. | |||
last_refresh_status_date String [ |
The date when a refresh of the remediation status of this finding was last requested. | |||
last_refresh_status_label String |
The current refresh status of this finding. | |||
last_refresh_reason_code String |
The reason code for the refresh status. | |||
asset_overrides Array |
User-assigned asset importance details. | |||
asset String |
The domain or IP address. | |||
importance String |
The user-assigned asset importance. | |||
override_importance Null |
For internal Bitsight use. | |||
duration Null |
For internal Bitsight use. | |||
comments String |
A thread of finding comments. | |||
remaining_decay Integer |
The remaining number of days for the finding to decay. | |||
remediated Boolean |
true = This finding is remediated. |
|||
impacts_risk_vector_details String |
This finding’s impact on the rating. | |||
attributed_companies Array |
If the expand parameter is set to attributed_companies (?expand=attributed_companies ), attributed company details are included. |
|||
guid String [ |
The unique identifier of this company. | |||
name String |
The name of this company. |
-
August 1, 2024: Added
is_monitored
field. - March 29, 2024: DMARC findings.
-
January 31, 2024:
tag_details
field,tag_details
andassets.tag_details
query parameters.
Feedback
4 comments
How do we include unsampled findings in the results?
This endpoint is limited to 100 results per page by default. You can use the
limit
andoffset
parameters to change this default. Refer to the pagination fields (links
,previous
,next
) to navigate multiple pages of results. Be sure theaffects_rating
parameter, which filters findings that have an impact on the letter grade, is set tofalse
.Hi guys. Is the JSON response for the GET-Finding_Details available as a JSON schema?
It is available as a JSON schema by default, even on a browser.
Please sign in to leave a comment.