GET: Threat Impact [v2]

Ingrid

https://api.bitsighttech.com/ratings/v2/threats/threat_guid/companies

Get companies affected by a threat (such as vulnerabilities).

Parameters
Example Request
Example Response
Response Attributes
Response Codes

Parameters

See query parameters for details on the following parameters:

* Required.

❖ Applicable only for threat groups.

format (Default: ↻ json)
limit (Default: ↻ 25)
offset (Default: ↻ 0)
q
sort (Default: ↻ last_seen_date)

evidence_certainty

[Query] Filter by evidence certainty.

Value: [String] See evidence certainty.

evidence_tags

[Query] Filter by evidence.

Value: [String]

LONG_TIME_SINCE_LAST_DETECTION
MITIGATION_APPLIED
RELATIONSHIP_WITH_VULNERABLE_PROVIDER_INDICATED
VULNERABLE_SOFTWARE_OR_CONFIGURATION_IN_USE
VULNERABLE_SOFTWARE_VERSION_IN_USE

expand

[Query] Include additional information.

Value: [String]

sub_threats_count = Include sub-threat counts in summaries and results for each company.
workflow_status = Include questionnaire status details.

exposure_detection

[Query] Filter by exposure detection status.

Value: [String] See exposure detection.

folder

[Query] Filter by folder.

Value: [String] Folder unique identifier [folder_guid]. See GET: Folder Details.

[Date] first_seen_date_gte

[Query] Filter threats first seen on and after a specific date.

Value: [String] YYYY-MM-DD

[Date] first_seen_date_lte

[Query] Filter threats first seen on and before a specific date.

Value: [String] YYYY-MM-DD

[Date] last_seen_date_gte

[Query] Filter threats last seen on and after a specific date.

Value: [String] YYYY-MM-DD

[Date] last_seen_date_lte

[Query] Filter threats last seen on and before a specific date.

Value: [String] YYYY-MM-DD

[Sub-Threat Count] sub_threats_count_gte

❖ Applicable only for threat groups.

❖ [Query] Filter by the number (>e;) of sub-threats.

Value: [Integer] Minimum: 0

[Sub-Threat Count] sub_threats_count_lte

❖ Applicable only for threat groups.

❖ [Query] Filter by the number (<e;) of sub-threats.

Value: [Integer] Minimum: 0

sub_threat_guid

❖ Applicable only for threat groups.

❖ [Query] Filter by companies affected by the identified threat.

Value: [String] Threat unique identifier [threat_guid]. See GET: Portfolio Threats.

threat_guid

* Required.

[Path] Identify the threat to query.

Value: [String] Threat unique identifier [threat_guid]. See GET: Portfolio Threats.

tier

[Query] Filter by tier.

Value: [String] Tier unique identifier [tier_guid]. See GET: Tiers.

Example Request

curl https://api.bitsighttech.com/ratings/v2/threats/threat_guid/companies -u api_token:

Example Response

{
  "links": {
    "previous": null,
    "next": "https://api.bitsighttech.com/ratings/v2/threats/db72416d-454a-4551-a03e-74c749048d46/companies?&limit=10&offset=10"
  },
  "count": 2325,
  "summaries": {
    "exposed_count": 2325,
    "mitigated_count": 0,
    "total_count": 2325,
    "entity_group_size": 13146
  },
  "results": [
    {
      "company_name": "Black Hills Technologies",
      "evidence_certainty": "POSSIBLE",
      "exposure_detection": "EXPOSED",
      "first_seen_date": "2023-10-27",
      "last_seen_date": "2023-10-27",
      "company_guid": "a5e23bf0-38d4-4cea-aa50-19ee75da481d",
      "tier": null,
      "tier_name": null,
      "logo": "https://api.bitsighttech.com/ratings/v1/companies/a5e23bf0-38d4-4cea-aa50-19ee75da481d/logo-image",
      "detection_types": [
        "early_detection"
      ],
      "evidence_tags": [
        {
          "name": "Software from vulnerable provider in use",
          "slug": "SOFTWARE_FROM_VULNERABLE_PROVIDER_IN_USE"
        }
      ]
    },
    […]
  ]
}

Response Attributes

Field					Description
links Object					Navigation for multiple pages of results. See pagination.
	previous String				The URL for navigating to the previous page of results.
	next String				The URL for navigating to the next page of results.
count Integer					The number of companies affected by the threat.
summaries Object					Exposure statistics.
	exposed_count Integer				The number of companies that have been observed to have evidence of exposure (exposure).
	mitigated_count Integer				The number of companies that have evidence of active mitigation (mitigation).
	total_count Integer				The number of threats for companies in your portfolio.
	entity_group_size Integer
results Array					Companies affected by the threat and details.
	Object				A company.
		company_name String			The company name.
		evidence_certainty String			The evidence certainty, which measures the certainty of the detection status.
		exposure_detection String			The company's exposure detection status from threats.
		first_seen_date String [`YYYY-MM-DD`]			The date when the threat was first seen.
		last_seen_date String [`YYYY-MM-DD`]			The date when the threat was last seen.
		company_guid String [`entity_guid`]			The company’s unique identifier.
		tier String			The tier the company is in.
		tier_name String			The tier name.
		logo String			The URL where this company’s logo image file is stored in the Bitsight platform.
		detection_types Array			How the data was collected. `early_detection` = The data was collected from manually loaded sources. `standard` = The data was collected through standard methods.
		evidence_tags Array			The type of evidence seen for this record. `LONG_TIME_SINCE_LAST_DETECTION` `MITIGATION_APPLIED` `RELATIONSHIP_WITH_VULNERABLE_PROVIDER_INDICATED` `VULNERABLE_SOFTWARE_OR_CONFIGURATION_IN_USE` `VULNERABLE_SOFTWARE_VERSION_IN_USE`
			Object		The evidence.
				name String	The name of the evidence.
				slug String	The slug name of the evidence.

Response Codes

200 – Success: Everything worked as expected.
422 – Validation Error: There was a validation error.

October 17, 2024: Published.