GET: Assets

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

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.

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

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.

links

next

previous

count

results

temporary_id

asset

asset_type

identifier

app_grade

ip_addresses

country_code

country

hosted_by

guid

name

importance

importance_category

longitude

latitude

is_ip

services

origin_subsidiary

guid

name

findings

total_count

counts_by_severity

severe

material

moderate

minor

threats

rolledup_observation_ids

evidence_keys

tags

tag_details

guid

name

is_inherited

is_public

delegated_security_controls

has_delegated_security_controls

findings

{ total_count: [number] }

types

{ name: [String], slug: [String] }

overrides

importance

combined_overrides

importance

products

type

vendor

product

version

support

is_monitored