GET: Finding Details

https://api.bitsighttech.com/ratings/v1/companies/entity_guid/findings

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

Parameters

* Required.

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

affects_rating

[Query] Filter by findings that have an impact on the letter grade.

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

Value:

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

Value: [String]

• Domain
• IP Address

assets.category

[Query] Filter by asset importance.

Value: [String] See asset importance.

assets.combined_importance

[Query] Filter by combined asset importance.

Value: [String] Comma-separated asset importance.

assets.hosted_by

[Query] Filter by the hosting provider.

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

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

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

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.

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.

Value: [String] Finding grade.

details.grade_gt

[Query] Include a range starting from the selected Diligence finding grade to GOOD.

Incompatible with grade.

Value: [String] Finding grade.

details.grade_lt

[Query] Include a range from the selected Diligence finding grade to BAD.

Incompatible with grade.

Value: [String] Finding grade.

details.infection.family

[Query] Filter by infections.

Value: [String] Comma-separated infection names.

Example: Gamarue

details.observed_ips_contains

[Query] Include findings from a particular IP address.

Value: [String] IP address.

details.vulnerabilities.severity

[Query] Filter by vulnerability severity.

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

Value: [String]

• Domain
• IP Address

expand

[Query] Include additional information.

Value: [String]

• attributed_companies = 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.

Value: [String] Date [YYYY‑MM‑DD]

first_seen_gt

[Query] Include findings that were first seen after this date.

Incompatible with first_seen.

Value: [String] Date [YYYY‑MM‑DD]

first_seen_gte

[Query] Include findings that were first seen on and after this date.

Incompatible with first_seen.

Value: [String] Date [YYYY‑MM‑DD]

first_seen_lt

[Query] Include findings that were first seen prior to this date.

Incompatible with first_seen.

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

Value: [String] Date [YYYY‑MM‑DD]

guid

* Required.

[Path] Identify the company to query.

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

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

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

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

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

Value: [String] Date [YYYY‑MM‑DD]

last_remediation_status_label

[Query] Filter by the current remediation status of the finding.

Value: [String] The remediation status of the finding.

last_seen

[Query] Include findings that were last seen on this date.

Incompatible with last_seen_lt and last_seen_gt.

Value: [String] Date [YYYY‑MM‑DD

last_seen_gt

[Query] Include findings that were last seen after this date.

Incompatible with last_seen.

Value: [String] Date [YYYY‑MM‑DD]

last_seen_gte

[Query] Include findings that were last seen on and after this date.

Incompatible with last_seen.

Value: [String] Date [YYYY‑MM‑DD]

last_seen_lt

[Query] Include findings that were last seen prior to this date.

Incompatible with last_seen.

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

Value: [String] Date [YYYY‑MM‑DD

remediation_assignments

[Query] Filter by users assigned to the findings.

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

Value: [String] Comma-separated risk vector slug names. See risk types.

severity

[Query] Filter by finding severity.

Value: [Decimal] Severity. See range values.

severity_gt

[Query] Include finding severity that are of greater severity.

Value: [Decimal] Severity. See range values.

severity_gte

[Query] Include finding severity that are of greater or equal severity.

Value: [Decimal] Severity. See range values.

severity_lt

[Query] Include finding severity that are of lesser severity.

Value: [Decimal] Severity. See range values.

severity_lte

[Query] Include finding severity that are of lesser or equal severity.

Value: [Decimal] Severity. See range values.

severity_category

[Query] Filter by finding severity.

Value: [Decimal] Severity. See severities.

tags_contains

[Query] Filter by infrastructure tags.

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

Value: [Boolean]

• true = Enable unsampled findings.
• ↻ false = Sample findings.

vulnerabilities

[Query] Filter by vulnerability.

Value: [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_status_reason": "asset_not_found",
            "last_refresh_reason_code":"asset unreachable",
            "last_refresh_requester": "1e10564d-fawa-4331-0000-6f7588b55a98",
          "result_finding_date": null
        },
        "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

links

previous

next

count

results

temporary_id

affects_rating

assets

asset

identifier

category

importance

is_ip

asset_type

is_monitored

details

cvss

base

check_pass

evidence_key

first_seen

last_seen

related_findings

risk_category

risk_vector

risk_vector_label

rolledup_observation_id

severity

severity_category

tags

tag_details

guid

name

is_inherited

is_public

remediation_history

last_requested_refresh_date

last_refresh_status_date

last_refresh_status_label

last_refresh_status_reason

last_refresh_reason_code

last_refresh_requester

result_finding_date

asset_overrides

asset

importance

override_importance

duration

comments

remaining_decay

remediated

impacts_risk_vector_details

attributed_companies

guid

name