Security Performance Management
Continuous Monitoring
Cyber Insurance
National Cybersecurity

Articles in this section

See more

GET: Assets

Avatar
Ingrid
Follow
  • August 3, 2023: New parameters – threat.guid, threat.severity_level, threat.evidence_certainty, threat.exposure_detection; New field rolled_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.

⇤ 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

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

Attack Surface Analytics Parameters

The following parameters are also available if you have Attack Surface Analytics.

Parameter Description 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/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 
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.
  
asset
String		 The asset name. 
asset_type
String		 The type of asset. 
identifier
Null		 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_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 [company_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		 An identifier for findings. 
tags
Array		 Infrastructure tags assigned to this asset. 
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.

Related articles