GET: Assets – Bitsight Knowledge Base

⇤ Companies

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
Attack Surface Analytics Parameters
Example Request
Example Response
Response Attributes

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

Parameter Values

asset

[Query] Filter by asset name.

[String] Domain name.

combined_overrides.importance

[Query] Filter by asset importance, regardless of whether its importance is calculated or user-assigned.

[String] Comma-separated asset importance.

Example: "combined_overrides.importance=medium,none"

company_guid

* [Path] Identify the company to query.

[String] Company unique identifier [entity_guid]. See GET: Portfolio Details.

expand

[Query] Include additional information.

[String] tag_details, delegated_security_controls

Findings Count

Filter by finding counts.

[Integer]

findings.total_count

[Query] Filter assets by a set number of findings.

findings.total_count_lt

[Query] Filter assets by less than a set number of findings.

findings.total_count_gt

[Query] Filter assets by more than a set number of findings.

findings.total_count_lte

[Query] Filter assets by less than or equal to a set number of findings.

findings.total_count_gte

[Query] Filter assets by more than or equal to a set number of findings.

hosted_by_isnull

[Query] Filter by assets associated with a hosting provider.

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

[String] Comma-separated asset importance.

importance_overrides

[Query] Filter assets by those with user-assigned asset importance.

[String] Comma-separated asset importance.

Example: "importance_overrides=medium,none"

ip_address

[Query] Filter by IP address.

[String] IP address.

is_ip

[Query] Filter by asset type (domain or IP address).

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

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

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

[Array] List of strings, one for each tag.

tags_isnull

[Query] Filter assets that have any tags or no tags assigned.

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

Parameter	Values
countries [Query] Filter by countries.	[String] Comma-separated country names.
country_codes [Query] Filter by countries.	[String] Comma-separated country codes.
hosted_by.guid [Query] Filter by hosting providers.	[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.	[String] Comma-separated company unique identifiers [`entity_guid`] of subsidiaries. See GET: Ratings Tree.
product.name-version [Query] Filter by product name and version.	[String] Comma-separated product names and version pairings [`product:version`]. See `products`>`product` and `products`>`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.	[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.	[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.	[String] Comma-separated service names.
threat.evidence_certainty [Query] Filter by evidence certainty.	[String] Evidence certainty slug name.
threat.exposure_detection [Query] Filter by exposure status.	[String] Exposure detection status.
threat.guid [Query] Filter by vulnerabilities.	[String] Comma-separated vulnerability unique identifiers [`vuln_guid`].
threat.severity_level [Query] Filter by severity level.	[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 [`entity_guid`]		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. Values: `true` = IP Address `false` = Domain
	services ⌘ Array			Running services that require an open port.
	origin_subsidiary ⌘ Object			Details of the subsidiary attributed to the asset.
		guid String [`entity_guid`]		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 [`tag_guid`]	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			Indicates whether or not 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 and tags_isnull.
November 30, 2023: New expand parameter to get tag details.

Feedback

2 comments

ALBERTO MARZIALI

April 26, 2024 12:11
Hi, the response does not contain the field “origin_subsidiary”. It used to have it, but now it's missing it since 2 months.
0
Ingrid

April 26, 2024 18:14
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.
0

Please sign in to leave a comment.

Parameters

Attack Surface Analytics Parameters

Example Request

Example Response

Response Attributes

Related articles