- August 3, 2023: New parameters –
threat.guid
,threat.severity_level
,threat.evidence_certainty
,threat.exposure_detection
; New fieldrolled_up_observation_ids
. - June 7, 2023: Added
findings.total_count
,findings.total_count_lt
,findings.total_count_gt
,findings.total_count_lte
,findings.total_count_gte
parameters. - December 2, 2021: Added
asset_type
&app_grade
.
https://api.bitsighttech.com/ratings/v1/companies/company_guid/assets
Get a company’s asset information (domains and IP addresses), including asset importance and the number of findings.
Parameters
See query parameters for details on the following parameters:
fields
format
(Default:json
)csv
json
xml
limit
(Default:100
)offset
(Default:100
)q
sort
Parameter | Description | Values | |
---|---|---|---|
assetQuery |
Filter by asset name. | [String] Domain name. | |
combined_overrides.importanceQuery |
Filter by asset importance, regardless of whether its importance is calculated or user-assigned. | [String] Comma-separated asset importance.
Example:
|
|
company_guidPath |
Identify the company to query. | [String] Company unique identifier [entity_guid ]. See GET: Portfolio Details. |
|
Findings Count | Filter by finding counts. | [Integer] | |
findings.total_countQuery |
Filter assets by a set number of findings. | ||
findings.total_count_ltQuery |
Filter assets by less than a set number of findings. | ||
findings.total_count_gtQuery |
Filter assets by more than a set number of findings. | ||
findings.total_count_lteQuery |
Filter assets by less than or equal to a set number of findings. | ||
findings.total_count_gteQuery |
Filter assets by more than or equal to a set number of findings. | ||
hosted_by_isnullQuery |
Filter by assets associated with a hosting provider. | [Boolean]
|
|
importance_categoriesQuery |
Filter by asset importance. | [String] Comma-separated asset importance. | |
importance_overridesQuery |
Filter assets by those with user-assigned asset importance. | [String] Comma-separated asset importance.
Example:
|
|
ip_addressQuery |
Filter by IP address. | [String] IP address. | |
is_ipQuery |
Filter by asset type (domain or IP address). | [Boolean]
|
|
origin_subsidiary_isnullQuery |
Filter by assets that are attributed to a subsidiary. | [Boolean]
|
|
overrides_isnullQuery |
Filter assets with calculated or user-assigned asset importance. | [Boolean]
|
Attack Surface Analytics Parameters
The following parameters are also available if you have Attack Surface Analytics.
Parameter | Description | Values |
---|---|---|
countriesQuery |
Filter by countries. | [String] Comma-separated country names. |
country_codesQuery |
Filter by countries. | [String] Comma-separated country codes. |
hosted_by.guidQuery |
Filter by hosting providers. | [String] Comma-separated company unique identifiers [entity_guid ] of service providers. See GET: Service Providers. |
origin_subsidiary.guidQuery |
Filter by subsidiaries attributed to assets. | [String] Comma-separated company unique identifiers [entity_guid ] of subsidiaries. See GET: Ratings Tree. |
product.name-versionQuery |
Filter by product name and version. |
[String] Comma-separated product names and version pairings [ Versions can also be set to:
Example: |
product.supportQuery |
Filter by product support status. | [String] Comma-separated support status.
|
product.vendorQuery |
Filter by vendors of identified products. | [String] Comma-separated company unique identifiers [entity_guid ] of service providers. See GET: Service Providers. |
servicesQuery |
Filter by services that require an open port. | [String] Comma-separated service names. |
threat.evidence_certaintyQuery |
Filter by evidence certainty. | [String] Evidence certainty slug name. |
threat.exposure_detectionQuery |
Filter by exposure status. | [String] Exposure detection status. |
threat.guidQuery |
Filter by vulnerabilities. | [String] Comma-separated vulnerability unique identifiers [vuln_guid ]. |
threat.severity_levelQuery |
Filter by severity level. | [String] Vulnerability severity slug name. |
Example Request
curl https://api.bitsighttech.com/ratings/v1/companies/entity_guid/assets -u api_token:
Example Response
{ "links":{ "next":"https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/assets?limit=100&offset=100", "previous":null }, "count":4015, "results":[ […] { "asset":"12.3.456.789", "asset_type":"IP", "identifier":null, "app_grade":null, "ip_addresses":[ "11.2.333.444" ], "country_code":"A1", "country":"Demo Country 1", "hosted_by":{ "guid":"a5e23bf0-38d4-4cea-aa50-19ee75da481d", "name":"Black Hills Technologies" }, "importance":0.0, "importance_category":"low", "longitude":-123.1234, "latitude":12.1234, "is_ip":true, "services":[ "HTTP", "HTTPS" ], "origin_subsidiary":{ "guid":"13b3c162-e597-46da-bac9-7dde651a9b2c", "name":"Saperix, Inc - Wifi testing" }, "findings":{ "total_count":3, "counts_by_severity":{ "severe":0, "material":0, "moderate":0, "minor":3 } }, "threats":{ "rolledup_observation_ids":[ "12345AAbA6Abb_bAAAA7bb==", "AAAAbA12bAbAAAbAAbbbbb==" ] }, "tags":[ "Guest WiFi", "Corporate Network" ], "overrides":{ "importance":null }, "combined_overrides":{ "importance":"low" }, "products":[ { "type":"application", "vendor":"blackhillstech", "product":"productname", "version":null, "support":"unknown" } ] } ] }
Response Attributes
⌘Requires Attack Surface Analytics.
Field | Description | |||
---|---|---|---|---|
linksObject |
Navigation for paginated results. | |||
nextString |
The URL to navigate to the next page of the results. | |||
previousString |
The URL to navigate to the previous page of the results. | |||
countInteger |
The number of assets. | |||
resultsArray |
Asset details. | |||
assetString |
The asset name. | |||
asset_typeString |
The type of asset. | |||
identifierNull |
For internal Bitsight use. | |||
app_grade |
If the asset is a mobile application ["asset_type":"Android" or "asset_type":"iOS" ], this is quantified using the Common Vulnerability Scoring System (CVSS). Learn more… |
|||
ip_addressesString |
The associated IP address. | |||
country_code⌘
String |
The originating country code of this asset. | |||
country⌘
String |
The originating country of this asset. | |||
hosted_by⌘
Object |
The service provider hosting this asset. | |||
guidString [ entity_guid ] |
The unique identifier of the service provider. | |||
nameString |
The name of the service provider. | |||
importanceDecimal |
The numeric importance of the asset to the organization. See asset importance. | |||
importance_categoryString |
The asset's importance. | |||
longitudeDecimal |
The east-west geographic coordinate of the asset’s origin. | |||
latitudeDecimal |
The north-south geographic coordinate of the asset’s origin. | |||
is_ipBoolean |
The asset type.
Values: |
|||
services⌘
Array |
Running services that require an open port. | |||
origin_subsidiary⌘
Object |
Details of the subsidiary attributed to the asset. | |||
guidString [ company_guid ] |
The unique identifier of the subsidiary. | |||
nameString |
The name of the subsidiary. | |||
findingsObject |
Finding details in this asset. | |||
total_countInteger |
The number of findings in this asset. | |||
counts_by_severityObject |
Finding counts in this asset, grouped by finding severity. | |||
severeInteger |
The number of severe findings. | |||
materialInteger |
The number of material findings. | |||
moderateInteger |
The number of moderate findings. | |||
minorInteger |
The number of minor findings. | |||
threats⌘
Object |
Threat details. | |||
rolledup_observation_idsArray |
An identifier for findings. | |||
tagsArray |
Infrastructure tags assigned to this asset. | |||
overridesObject |
User-assigned asset importance details. | |||
importanceString |
The level of asset importance. | |||
combined_overridesObject |
User-assigned and calculated asset importance. | |||
importanceString |
The level of asset importance. | |||
products⌘
Array |
Details of products used within this asset. | |||
typeString |
The type of product. | |||
vendorString |
The service provider of this product. | |||
productString |
The name of this product. | |||
versionString |
The version of this product. | |||
supportString |
The support status of this product. |