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:
* Required.
fields
-
format
(Default: ↻json
)csv
json
xml
-
limit
(Default: ↻100
) -
offset
(Default: ↻100
) q
sort
asset
-
[Query] Filter by asset name.
Value: [String] Domain name.
combined_overrides.importance
-
[Query] Filter by asset importance, regardless of whether its importance is calculated or user-assigned.
Value: [String] Comma-separated asset importance.
Example:
"combined_overrides.importance=medium,none"
company_guid
-
* Required.
[Path] Identify the company to query.
Value: [String] Company unique identifier [
entity_guid
]. See GET: Portfolio Details. expand
-
[Query] Include additional information.
Value: [String]
tag_details
,delegated_security_controls
- [Findings Count]
findings.total_count
-
[Query] Filter assets by a set number of findings.
Value: [Integer]
- [Findings Count]
findings.total_count_lt
-
[Query] Filter assets by less than a set number of findings.
Value: [Integer]
- [Findings Count]
findings.total_count_gt
-
[Query] Filter assets by more than a set number of findings.
Value: [Integer]
- [Findings Count]
findings.total_count_lte
-
[Query] Filter assets by less than or equal to a set number of findings.
Value: [Integer]
- [Findings Count]
findings.total_count_gte
-
[Query] Filter assets by more than or equal to a set number of findings.
Value: [Integer]
hosted_by_isnull
-
[Query] Filter by assets associated with a hosting provider.
Value: [Boolean]
-
true
= Include only the assets with an associated hosting provider. -
false
= Include all assets, regardless of a known hosting provider.
-
importance_categories
-
[Query] Filter by asset importance.
Value: [String] Comma-separated asset importance.
importance_overrides
-
[Query] Filter assets by those with user-assigned asset importance.
Value: [String] Comma-separated asset importance.
Example:
"importance_overrides=medium,none"
ip_address
-
[Query] Filter by IP address.
Value: [String] IP address.
is_ip
-
[Query] Filter by asset type (domain or IP address).
Value: [Boolean]
-
true
= Include only the assets that are IP addresses. -
false
= Include only the assets that are domains.
-
origin_subsidiary_isnull
-
[Query] Filter by assets that are attributed to a subsidiary.
Value: [Boolean]
-
true
= Include only the assets that are attributed to a subsidiary. -
false
= Include all assets, regardless of an attributed subsidiary.
-
overrides_isnull
-
[Query] Filter assets with calculated or user-assigned asset importance.
Value: [Boolean]
-
true
= Include only the assets with calculated importance. -
false
= Include only the assets with user-assigned importance.
-
tags_contains
-
[Query] Filter by assets that include tags.
Value: [Array] List of strings, one for each tag.
tags_isnull
-
[Query] Filter assets that have any tags or no tags assigned.
Value: [Boolean]
-
true
= Include only the assets with no tags assigned. -
false
= Include only the assets with at least one tag, which can be any tag.
-
Attack Surface Analytics Parameters
The following parameters are also available if you have Attack Surface Analytics.
Requirements
- Attack Surface Analytics
- The queried entity must be your My Company or My Subsidiary.
countries
-
[Query] Filter by countries.
Value: [String] Comma-separated country names.
country_codes
-
[Query] Filter by countries.
Value: [String] Comma-separated country codes.
hosted_by.guid
-
[Query] Filter by hosting providers.
Value: [String] Comma-separated company unique identifiers [
entity_guid
] of service providers. See GET: Service Providers. origin_subsidiary.guid
-
[Query] Filter by subsidiaries attributed to assets.
Value: [String] Comma-separated company unique identifiers [
entity_guid
] of subsidiaries. See GET: Ratings Tree. product.name-version
-
[Query] Filter by product name and version.
Value: [String] Comma-separated product names and version pairings [
product:version
]. Seeproducts
>product
andproducts
>version
in the response.Versions can also be set to:
-
null
= Unspecified version. - Empty = Include all versions.
Example:
?product.name-version=product:version
-
product.support
-
[Query] Filter by product support status.
Value: [String] Comma-separated support status.
current-package
current-version
incomplete-version
obsolete-os-release
obsolete-package
obsolete-version
possible-backports
unknown
unknown-patch-status
product.vendor
-
[Query] Filter by vendors of identified products.
Value: [String] Comma-separated company unique identifiers [
entity_guid
] of service providers. See GET: Service Providers. services
-
[Query] Filter by services that require an open port.
Value: [String] Comma-separated service names. See finding messages: detected services, typical services, potentially vulnerable.
threat.evidence_certainty
-
[Query] Filter by evidence certainty.
Value: [String] Evidence certainty slug name.
threat.exposure_detection
-
[Query] Filter by exposure status.
Value: [String] Exposure detection status.
threat.guid
-
[Query] Filter by vulnerabilities.
Value: [String] Comma-separated vulnerability unique identifiers [
vuln_guid
]. threat.severity_level
-
[Query] Filter by severity level.
Value: [String] Vulnerability severity slug name.
Example Request
curl https://api.bitsighttech.com/ratings/v1/companies/a940bb61-33c4-42c9-9231-c8194c305db3/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":[ […] { "temporary_id":"tN0i7cUlKZ2e3df1d478e1f9d6da100069f0740915e3896db99bdd2f029566e140671c1683", "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==" ], "evidence_keys":[ "Android 10 / Chrome Mobile WebView 113.0.5672", […] ] }, "tags":[ "Guest WiFi", "Corporate Network" ], "tag_details":[ { "guid":"ae87bc30-a3ab-45f7-809f-61ec36978685", "name":"Data Center 1", "is_inherited":false, "is_public":true } ], "overrides":{ "importance":null }, "combined_overrides":{ "importance":"low" }, "products":[ { "type":"application", "vendor":"blackhillstech", "product":"productname", "version":null, "support":"unknown" } ], "is_monitored":false } ] }
Response Attributes
⌘ Can only be used for your MyCompany or My Subsidiary and requires Attack Surface Analytics.
Field | Description | |||
---|---|---|---|---|
links Object |
Navigation for paginated results. | |||
next String |
The URL to navigate to the next page of the results. | |||
previous String |
The URL to navigate to the previous page of the results. | |||
count Integer |
The number of assets. | |||
results Array |
Asset details. | |||
temporary_id String |
A temporary identifier for this asset. | |||
asset String |
The asset name. | |||
asset_type String |
The type of asset. | |||
identifier Null |
For internal Bitsight use. | |||
app_grade Decimal |
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_addresses String |
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. | |||
guid String [ |
The unique identifier of the service provider. | |||
name String |
The name of the service provider. | |||
importance Decimal |
The numeric importance of the asset to the organization. See asset importance. | |||
importance_category String |
The asset's importance. | |||
longitude ⌘ Decimal |
The east-west geographic coordinate of the asset’s origin. | |||
latitude ⌘ Decimal |
The north-south geographic coordinate of the asset’s origin. | |||
is_ip Boolean |
The asset type.
|
|||
services ⌘ Array |
Running services that require an open port. | |||
origin_subsidiary ⌘ Object |
Details of the subsidiary attributed to the asset. | |||
guid String [ |
The unique identifier of the subsidiary. | |||
name String |
The name of the subsidiary. | |||
findings Object |
Finding details in this asset. | |||
total_count Integer |
The number of findings in this asset. | |||
counts_by_severity Object |
Finding counts in this asset, grouped by finding severity. | |||
severe Integer |
The number of severe findings. | |||
material Integer |
The number of material findings. | |||
moderate Integer |
The number of moderate findings. | |||
minor Integer |
The number of minor findings. | |||
threats ⌘ Object |
Threat details. | |||
rolledup_observation_ids Array |
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. | |||
evidence_keys Array |
Threat evidence. | |||
tags Array |
Infrastructure tags assigned to this asset. | |||
tag_details Array |
If the expand parameter is set to tag_details (&expand=tag_details ), these additional details on tags are included. |
|||
Object |
Tag details. | |||
guid String [ |
This tag’s unique identifier. | |||
name String |
This tag’s name. | |||
is_inherited Boolean |
true = This tag is inherited from the parent company. |
|||
is_public Boolean |
true = This tag is publicly visible. |
|||
delegated_security_controls Array |
If the expand parameter is set to delegated_security_controls (&expand=delegated_security_controls ), these additional details on delegated security controls are included. |
|||
Object |
Delegated security control details. | |||
has_delegated_security_controls Boolean |
If the asset has delegated security controls. | |||
findings Object |
Findings counts related to delegated security controls. { total_count: [number] } |
|||
types Array |
Array of delegated type object { name: [String], slug: [String] } |
|||
overrides Object |
User-assigned asset importance details. | |||
importance String |
The level of asset importance. | |||
combined_overrides Object |
User-assigned and calculated asset importance. | |||
importance String |
The level of asset importance. | |||
products ⌘ Array |
Details of products used within this asset. | |||
type String |
The type of product. | |||
vendor String |
The service provider of this product. | |||
product String |
The name of this product. | |||
version String |
The version of this product. | |||
support String |
The support status of this product. | |||
is_monitored Boolean |
true = The asset is being monitored. This field is currently part of a beta feature. |
-
July 31, 2024: Added
is_monitored
field. -
January 29, 2024: Added
tags_contains
andtags_isnull
. -
November 30, 2023: New
expand
parameter to get tag details.
Feedback
2 comments
Hi, the response does not contain the field “origin_subsidiary”. It used to have it, but now it's missing it since 2 months.
origin_subsidiary
(along with all other fields identified with the ⌘ icon) is available if you have Attack Surface Analytics. Also, they can only be used for your MyCompany or My Subsidiary.Please sign in to leave a comment.