ASI Assets: Find

get

https://api.securitytrails.com/v2/projects/{project_id}/assets

List and filter project assets using query-parameter-based criteria with OR logic.

Path Params

project_id

string

required

Query Params

cursor

string

Opaque string provided in next_cursor of previous results

limit

integer

1 to 1000

Defaults to 50

The number of assets to return

sort_by

string

enum

Defaults to exposure_score

The field to sort by

Allowed:

sort_direction

string

enum

Defaults to desc

The direction to sort by, either asc or desc.

Allowed:

asset_type

string

The type of asset, one of: ip, domain and host(where domain and host represent the same asset type).

custom_tags

string

Filter by custom tags placed on your assets. strict version will return a validation error if any of the tags have not been defined on your project.

custom_tags_strict

string

Filter by custom tags placed on your assets. strict version will return a validation error if any of the tags have not been defined on your project.

has_custom_tags

boolean

Filter for assets that have at least one custom tag applied. Overrides any other custom tag filtering specified.

added_to_project_before

date

Filter on the date (Y-m-d) the asset was added to the project. This may be different than when the asset was discovered.

added_to_project_after

date

Filter on the date (Y-m-d) the asset was added to the project. This may be different than when the asset was discovered.

discovered_before

date

Filter on the date (Y-m-d) the asset was discovered by Recorded Future ASI. This may be different than when the asset was added to the project. IPv4 addresses will have a fixed point in the past for their discovery date.

discovered_after

date

apex

string

Filter on the apex domain of the assets. Only makes sense for domain asset types. Example: example.com

referenced_ip

string

Filter on an A or CNAME record pointing to the IP address. Use eq or in for exact IP matching. Use contains with a trailing . for CIDR range matching, or without for prefix matching.

referenced_ip_before

date

If filtering on a referenced_ip, include additional criteria that the record existed during a date range. In this case, the reference must have started before this date.

referenced_ip_after

date

If filtering on a referenced_ip, include additional criteria that the record existed during a date range. In this case, the referenced must have existing after this date.

has_dns_record_type

string

Filter for assets that have this DNS record type, e.g. A,CNAME,MX.

dns_resolves

boolean

Filter for assets that in the end resolve to a valid IP currently, either via an A or CNAME. IP-assets is included when filtering for assets that resolve.

asn

integer

Filter for assets which either are, or point to, an IP address announced by the provided ASN (e.g. 16509).

cname_reference

string

Filter on a domain that is referenced by a CNAME record. Only makes sense for domain asset types. Treated as a wildcard, so example.com will match www.example.com.

geo_country_iso

string

Filter for assets which either are, or point to, an IP address located in the provided ISO country code (e.g. US).

ip_owner

string

Filter for assets which either are, or point to, an IP address owned by the provided organization. This will often be an ISP or hosting provider or simply the name of the AS owning the IP.

whois_email

string

Filter for assets where the WHOIS email address matches the provided value. For subdomains the parent record will be partially used. The current variant will only return results where the email is on the current (rather than historical) versions of the WHOIS.

whois_email_current

string

open_port_number

integer

Filter for assets which have an open port with the provided number (e.g. 80).

open_port_protocol

string

Filter for assets which have an open port on the provided protocol (e.g. tcp, udp).

open_port_service

string

Filter for assets which have an open port that appears to support the provided protocol (e.g. http, rdp, ftp).

open_port_technology

string

Filter for assets which have a specific product listening on an open port (e.g. nginx, apache httpd)

technology_name

string

Filter for the name of a technology found on the asset. Could be directly attached to the port (nginx, etc) or a web technology (e.g. 'jQuery', 'Wordpress')

web_technology_name

string

Filter for the name of a technology specifically associated with 'web' resources, such as jQuery or Wordpress). NOTE: In some cases where a port has been closed we may still report findings of web technologies that we previously saw on those ports.

certificate_issuer

string

Filter where the certificate (or in the chain) issuer's common name or organization matches the provided value

certificate_expires_before

date

Filter where the certificate expiration matches the provided value Use this to find potentially expired certificates.

certificate_expires_after

date

Filter where the certificate expiration matches the provided value use this to find certificates that likely haven't expired yet.

certificate_issued_before

date

Filter where the certificate issuance date matches the provided value

certificate_issued_after

date

Filter where the certificate issuance date matches the provided value

certificate_subject

string

Filter where certificate subject or organizationName matches the provided value

certificate_subject_alt_name

string

Filter here the certificate Subject Alternate Names section matches the provided value

certificate_sha256

string

Filter where the certificate public key sha256 value matches the provided value

certificate_covers_domain

string

Filter where the certificate's subject common name domain or one of the Subject Alternate Names exactly matches or is a wildcard covering the provided value

waf_detected

boolean

Filter for assets where a WAF (Web Application Firewall) is detected.

waf_name

string

Filter for assets where a specific WAF is detected. Will attempt to match both vendor and product, e.g. Cloudflare.

is_responsive

boolean

Filter for assets that are unresponsive over ICMP and no ports are open. This is a boolean filter, so it will return assets that are either responsive or not responsive.

exposure_score_gte

integer

Filter for assets which have an exposure score within the provided range. This is a score from 0-100 that indicates the potential risk of the asset based on various factors. You may specify only one 'end' based on your needs.

exposure_score_lte

integer

exposure_severity

string

enum

Filter for assets which have an exposure severity matching or higher than the provided value. Acceptable values: unknown, informational, moderate, critical.

Allowed:

exposure_id

string

Filter for assets which have an exposure with the provided ASI Signature ID. Note that some signatures line up with CVEs, but this should not be relied upon. Examples: cve-2024-6387, cve-OpenSSH.

additional_fields

array of strings

A list of additional fields to include in the response from the following. You may specify this field multiple times or pass a comma-separated list from: custom_tags, dns_records, whois, ip_metadata, open_tcp_ports, open_udp_ports, web_technologies, certificates, certificate_chain, defenses, exposures, exposure_instance_details. By default the custom tags will be returned.

Additional Fields

Responses

200Successful Response

422Validation Error