GET: Finding Details – Bitsight Knowledge Base

⇤ Companies

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
Example Request
Example Response
Response Attributes

Parameters

Recommendations

The return is limited to 100 results per page by default. Use the limit and offset 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 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 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 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.
assets.tag_details = Tag details associated with each asset that relates to the finding.
tag_details = Tag details associated with the finding.

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

true = Enable unsampled findings.
↻ false = 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",
          "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	`true` = The asset is being monitored. β 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 [`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			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 [`tag_guid`]	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 [`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 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 [`entity_guid`]		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 and assets.tag_details query parameters.

Feedback

4 comments

Anthony Pinto

January 22, 2021 18:47
How do we include unsampled findings in the results?
1
Ingrid

January 22, 2021 19:16
This endpoint is limited to 100 results per page by default. You can use the limit and offset parameters to change this default. Refer to the pagination fields (links, previous, next) to navigate multiple pages of results. Be sure the affects_rating parameter, which filters findings that have an impact on the letter grade, is set to false.
1
Jehad Negem

August 09, 2021 06:11
Hi guys. Is the JSON response for the GET-Finding_Details available as a JSON schema?
0
Ingrid

August 10, 2021 13:48
It is available as a JSON schema by default, even on a browser.
-1

Please sign in to leave a comment.

Parameters

Recommendations

Risk Category Parameter

Risk Vector Parameter

Compromised Systems

Diligence

User Behavior (File Sharing)

Query Parameters

Example Request

Example Response

Response Attributes

Related articles