GET: Finding Details – Bitsight Knowledge Base

October 13, 2023: affects_rating_details parameter.
September 27, 2023: Shortcut to individual risk vectors.
January 17, 2023: Added descriptions of cvss parameters and results.

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.

The return is limited to 100 results per page by default. Refer to the pagination fields (links, previous, next) to navigate multiple pages of results. Use the limit and offset parameters to modify this limit. You can also use the affects_rating parameter to filter findings that have an impact on the letter grade by setting it to true or the opposite by setting it to false.

To view all findings, ensure the affects_rating parameter is not included.

Parameters
Example Request
Example Response
Response Attributes

Parameters

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
Domain Squatting - Findings for this risk vector cannot be queried via the 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	Description	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 `does_not_affect_rating_reason`.	[String] Values may be used in combination. `AFFECTS_RATING` - Affects the risk vector grade. `LIFETIME_EXPIRED` - Does not affect the risk vector grade because the finding has reached the end of its lifetime
assets.asset Query	Filter by asset.	[String] Domain IP Address
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 SPM 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 `grade_lt` and `grade_gt`.	[String] Finding grades: `GOOD` `FAIR` `WARN` `BAD` `NEUTRAL` `NA` (N/A)
details.grade_gt Query	Include a range from the selected Diligence finding grade to GOOD. Incompatible with `grade`.	[String] `NEUTRAL` < `BAD` < `WARN` < `FAIR` < `GOOD`
details.grade_lt Query	Include a range from the selected Diligence finding grade to BAD. Incompatible with `grade`.	[String] `NEUTRAL` < `BAD` < `WARN` < `FAIR` < `GOOD`
details.infection.family Query	Filter by infections.	[String] Comma-separated infection names. Example: `Gamarue`
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] Domain IP Address
expand Query	Include additional information.	[String] `attributed_companies` = Include companies that are attributed to the finding. `remediation_history` = Issue tracking history.
first_seen Query	Include findings that were first seen on this date. Incompatible with `first_seen_lt` and `first_seen_gt`.	[String] Date [`YYYY‑MM‑DD`]
first_seen_gt Query	Include findings that were first seen after this date. Incompatible with `first_seen`.	[String] Date [`YYYY‑MM‑DD`]
first_seen_gte Query	Include findings that were first seen on and after this date. Incompatible with `first_seen`.	[String] Date [`YYYY‑MM‑DD`]
first_seen_lt Query	Include findings that were first seen prior to this date. Incompatible with `first_seen`.	[String] Date [`YYYY‑MM‑DD`]
first_seen_lte Query	Include findings that were first seen on and prior to this date. Incompatible with `first_seen`.	[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 `last_remediation_status_date_lt` and `last_remediation_status_date_gt`.	[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 `last_remediation_status_date`.	[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 `last_remediation_status_date`.	[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 `last_remediation_status_date`.	[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 `last_remediation_status_date`.	[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: `No Status` `Open` `To Do` `Work In Progress` `Resolved` `Risk Accepted`
last_seen Query	Include findings that were last seen on this date. Incompatible with `last_seen_lt` and `last_seen_gt`.	[String] Date [`YYYY‑MM‑DD`]
last_seen_gt Query	Include findings that were last seen after this date. Incompatible with `last_seen`.	[String] Date [`YYYY‑MM‑DD`]
last_seen_gte Query	Include findings that were last seen on and after this date. Incompatible with `last_seen`.	[String] Date [`YYYY‑MM‑DD`]
last_seen_lt Query	Include findings that were last seen prior to this date. Incompatible with `last_seen`.	[String] Date [`YYYY‑MM‑DD`]
last_seen_lte Query	Include findings that were last seen on and prior to this date. Incompatible with `last_seen`.	[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] `1` to `3.9` = Minor `4` to `6.9` = Moderate `7` to `8.9` = Material `9` to `10` = Severe
severity_gt Query	Include finding severity that are of greater severity.	[Decimal] `1` to `3.9` = Minor `4` to `6.9` = Moderate `7` to `8.9` = Material `9` to `10` = Severe
severity_gte Query	Include finding severity that are of greater or equal severity.	[Decimal] `1` to `3.9` = Minor `4` to `6.9` = Moderate `7` to `8.9` = Material `9` to `10` = Severe
severity_lt Query	Include finding severity that are of lesser severity.	[Decimal] `1` to `3.9` = Minor `4` to `6.9` = Moderate `7` to `8.9` = Material `9` to `10` = Severe
severity_lte Query	Include finding severity that are of lesser or equal severity.	[Decimal] `1` to `3.9` = Minor `4` to `6.9` = Moderate `7` to `8.9` = Material `9` to `10` = Severe
severity_category Query	Filter by finding severity.	[Decimal] `minor` `moderate` `material` `severe`
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 SPM Subsidiary’s unsampled findings data.	[Boolean] `true` = Enable unsampled findings. `false` (default) = Sample findings.
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",
          "category":"high",
          "importance":0.09,
          "is_ip":true
        }
      ],
      "details":{
        "cvss": {
          "base": [
            10.0
          ]
        },

        ⊕ See Finding Details:

        "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"
        ],
        "remediation_history":{
          "last_requested_refresh_date":null,
          "last_refresh_status_date":null,
          "last_refresh_status_label":null,
          "last_remediation_status_label":"Work In Progress",
          "last_remediation_status_date":"2020-08-18",
          "remediation_assignments":[
            "11111111-aaaa-1111-aaaa-111111111111"
          ],
          "last_remediation_status_updated_by":"Arnold Brown"
        },
        "asset_overrides":[
          {
            "asset":"11.111.111.111",
            "importance":"high",
            "override_importance":null
          }
        ],
        "duration":null,
        "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",
        "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		Asset details.
		asset String	The asset (IP address or domain) associated with this finding.
		category String	The Bitsight-calculated asset importance.
		importance Decimal	For internal Bitsight use.
		is_ip Boolean	`true` = This asset is an IP address.
	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.
	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 [`YYYY‑MM‑DD`]		The date of the first observation.
	last_seen String [`YYYY‑MM‑DD`]		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		An identifier for findings.
	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.
	remediation_history Object		If `expand=remediation_history` parameter is set, the remediation history of the finding is included.
		last_requested_refresh_date String [`YYYY‑MM‑DD`]	The date when a finding refresh that included this finding was last requested.
		last_refresh_status_date String [`YYYY‑MM‑DD`]	The date when a refresh of the remediation status of this finding was last requested.
		last_refresh_status_label String	The current finding refresh status of this finding.
		last_remediation_status_label String	The current remediation status of this finding.
		last_remediation_status_date String [`YYYY‑MM‑DD`]	The date when the remediation status of this finding was last changed.
		remediation_assignments Array [`user_guid`]	The users who are assigned to remediate this finding.
		last_remediation_status_updated_by String	The name of the user who updated the remediation status of this finding.
	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.
	attributed_companies Array		Companies in the Ratings Tree that are attributed to the finding.
		guid String [`entity_guid`]	The unique identifier of this company.
		name String	The name of this company.

Articles in this section