--- updatedAt: 2026-03-21T04:09:19.000Z agentTools: projectIndex: https://docs.recordedfuture.com/llms.txt --- # ASI Assets: Search Perform advanced compound asset queries using structured JSON filters with AND logic. ### What this endpoint does Perform advanced, compound searches across all assets in a project using structured JSON filters with boolean operators. Unlike [ASI Assets: Find](https://docs.recordedfuture.com/reference/assets-find), which combines query-parameter filters with OR logic, this endpoint supports AND-based filtering across multiple property groups — asset identity, certificates, exposures, and technologies — each with operators like `eq`, `in`, `range`, `contains`, and `neq`. This makes it suitable for precise queries such as "all domains with expired certificates AND critical exposure severity" or "IPs in a specific ASN running a particular service." Pass an empty filter object to retrieve all assets unfiltered, or use the `quick_search` filter for free-text matching. ### Response data Returns the same attack surface inventory as Find Assets — your project's discovered domains and IPs with their current exposure scores and risk posture — but filtered through the compound query you defined. Use the `additional_fields` query parameter to inline enrichment data (DNS, certificates, ports, exposures, technologies, WHOIS) on each result, avoiding a separate Read Asset call per item. Pagination is cursor-based; the metadata echoes back your applied filter structure alongside the `next_cursor` token for iteration. Asset IDs in the results are usable across all ASI Project API endpoints for tagging, exposure detail retrieval, and further search filtering. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "ASI Project API", "description": "\nThe Attack Surface Intelligence (ASI) Project API is designed to allow you full-featured access\nto all of the `Assets` within all of the `Project`s as well as , most importantly, the `Exposures` that our\nsystem has identified on those assets, including proposed remediations.\n\nYou can create new user-defined `Tags` and apply them to `Assets` either individually or in bulk.\n\nYou can use either the GET-based listing endpoint to find assets or the /_search endpoint which\naccepts a more structured request and, in the future, will allow for even more complex boolean queries.\n\nUsing it only requires a standard Security Trails API access key.\n", "version": "v1.7.0" }, "servers": [ { "url": "https://api.securitytrails.com/v2", "description": "Security Trails API" } ], "paths": { "/projects/{project_id}/assets/_search": { "post": { "tags": [ "Assets" ], "summary": "Search Assets", "description": "Perform advanced compound asset queries using structured JSON filters with AND logic.", "operationId": "Assets-search_assets", "security": [ { "APIKeyHeader": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiListResponse_Asset_" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ApiCount": { "properties": { "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "returned": { "type": "integer", "title": "Returned" } }, "type": "object", "required": [ "returned" ], "title": "ApiCount", "description": "Result count metadata." }, "ApiListResponse_Asset_": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Asset" }, "type": "array", "title": "Data" }, "meta": { "$ref": "#/components/schemas/ApiMeta" } }, "type": "object", "required": [ "data", "meta" ], "title": "ApiListResponse[Asset]", "description": "Paginated list of assets in a project." }, "ApiMeta": { "properties": { "params": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Params" }, "counts": { "anyOf": [ { "$ref": "#/components/schemas/ApiCount" }, { "type": "null" } ] }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/PaginationResponse" }, { "type": "null" } ] }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" } }, "type": "object", "title": "ApiMeta", "description": "Response metadata including pagination, counts, and request parameters." }, "Asset": { "properties": { "project_id": { "type": "string", "title": "Project Id", "description": "Project ID being displayed" }, "id": { "type": "string", "title": "Id", "description": "The asset identifier. Same as `name` currently. In the future this may become a more opaque value.", "examples": [ "foo.example.com", "192.0.2.101" ] }, "name": { "type": "string", "title": "Name", "description": "The asset identifier. Same as `id` currently.", "examples": [ "foo.example.com", "192.0.2.101" ] }, "type": { "type": "string", "title": "Type", "description": "Indicates the type of assets. Currently will be one of `domain` or `ip", "examples": [ "ip", "domain" ] }, "discovered_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Discovered At", "description": "Indicates when Recorded Future ASI first identified this asset on the Internet. For IP assets this is a fixed value" }, "added_to_project_at": { "type": "string", "format": "date-time", "title": "Added To Project At", "description": "Indicates when this asset became part of your project, which may be when it was first discovered or when a rule allowed it in" }, "last_scanned_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Scanned At", "description": "Indicates the last occurrence of some scanning activity on this asset, which could be port or vulnerability scans. On-Demand scans will 'bump' this date." }, "apex_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Apex Domain", "description": "For `domain` assets, the 'top' domain this is a part of. E.g. for `foo.bar.example.com` this would be `example.com`", "examples": [ "example.com" ] }, "exposure_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Exposure Score", "description": "The Recorded Future ASI-calculated score based on the Exposures found on your asset.", "examples": [ 50, 95 ], "gte": 0, "lte": 100 }, "is_static_asset": { "type": "boolean", "title": "Is Static Asset", "description": "Indicates whether this asset was discovered as part of project rules (`false`) or was added manually (`true`).", "default": false }, "custom_tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Custom Tags", "description": "User-defined tags which have been put on this asset. **NOTE**: After calling tagging endpoints, there may be a delay of up to a couple minutes before tags appear." }, "resolved_ips": { "anyOf": [ { "items": { "type": "string", "format": "ipvanyaddress" }, "type": "array" }, { "type": "null" } ], "title": "Resolved Ips", "description": "A convenience list of the IP addresses that A or CNAME records resolve to for this asset, or the aset iself." }, "dns_records": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DNSRecord" }, "type": "array" }, { "type": "null" } ], "title": "Dns Records", "description": "List of DNS records we have queried with" }, "whois": { "anyOf": [ { "$ref": "#/components/schemas/WHOISRecord" }, { "type": "null" } ], "description": "WHOIS or RDAP data for a domain asset, such as contact emails" }, "certificates": { "anyOf": [ { "items": { "$ref": "#/components/schemas/CertificateInstance" }, "type": "array" }, { "type": "null" } ], "title": "Certificates", "description": "The unique certificates found on this asset (when requested). Includes ports and IPs when available. This information will also be contained in `scanned_ips` when requested" }, "defenses": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DefensiveControl" }, "type": "array" }, { "type": "null" } ], "title": "Defenses", "description": "Defensive measures in place for the asset" }, "exposures": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Exposure" }, "type": "array" }, { "type": "null" } ], "title": "Exposures", "description": "Exposures found on this asset. Some information will overlap with tah contained within `scanned_ips`" }, "scanned_ips": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ScannedIP" }, "type": "array" }, { "type": "null" } ], "title": "Scanned Ips", "description": "IP addresses that have been scanned for this asset" } }, "type": "object", "required": [ "project_id", "id", "name", "type", "discovered_at", "added_to_project_at" ], "title": "Asset", "description": "An Asset is a representation of a domain or IP address in the system.\n\nA large number of enrichment fields can be enabled or disabled by the requestor." }, "AssetEnrichment": { "type": "string", "enum": [ "custom_tags", "dns_records", "whois", "ip_metadata", "open_tcp_ports", "open_udp_ports", "web_technologies", "certificates", "certificate_chain", "defenses", "exposures", "exposure_instance_details" ], "title": "AssetEnrichment", "description": "Optional enrichment data to include with asset results." }, "AssetFilter": { "properties": { "asset_properties": { "$ref": "#/components/schemas/AssetPropertiesFilter", "description": "Properties directly tied to the asset or DNS you want to filter on" }, "certificate_properties": { "$ref": "#/components/schemas/CertificatePropertiesFilter", "description": "Properties related to certificates on the asset you want to filter on" }, "exposure_properties": { "$ref": "#/components/schemas/ExposurePropertiesFilter", "description": "Properties relating to exposures found on assets you wish to filter on" }, "technology_properties": { "$ref": "#/components/schemas/TechnologyPropertiesFilter", "description": "Properties related to open ports and technologies identified on the asset" }, "quick_search": { "anyOf": [ { "$ref": "#/components/schemas/QuickSearchFilter" }, { "type": "null" } ], "description": "Quick search across asset name, IP addresses, and technology fields" } }, "type": "object", "title": "AssetFilter", "description": "Filter criteria for asset search queries." }, "AssetPropertiesFilter": { "properties": { "asset_id": { "$ref": "#/components/schemas/EqFilter", "description": "Filter for the specific asset, which will be either a IP or domain value (examples: `192.88.99.2` or `www.example.com`)." }, "name": { "anyOf": [ { "$ref": "#/components/schemas/ContainsFilter" }, { "type": "null" } ], "description": "Filter on the name of the asset(IP address or domain)." }, "static_asset": { "anyOf": [ { "$ref": "#/components/schemas/BooleanFilter" }, { "type": "null" } ], "description": "Filter static and non static assets." }, "apex": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" } ], "title": "Apex", "description": "Filter on the apex domain of the assets. Only makes sense for `domain` asset types. Example: `example.com`" }, "added_to_project": { "$ref": "#/components/schemas/DateRangeFilter", "description": "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": { "$ref": "#/components/schemas/DateRangeFilter", "description": "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." }, "asset_type": { "$ref": "#/components/schemas/EqFilter", "description": "The type of asset, one of: `ip`, `domain` and `host`(where `domain` and `host` represent the same asset type)." }, "referenced_ip": { "anyOf": [ { "$ref": "#/components/schemas/ContainsFilter" }, { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" } ], "title": "Referenced Ip", "description": "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." }, "cname_reference": { "anyOf": [ { "$ref": "#/components/schemas/ContainsFilter" }, { "$ref": "#/components/schemas/EqFilter" } ], "title": "Cname Reference", "description": "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`." }, "referenced_ip_at": { "$ref": "#/components/schemas/DateRangeFilter", "description": "If filtering on a `referenced_ip`, include additional criteria that the record existed during a date range." }, "valid_record_type": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/NeqFilter" } ], "title": "Valid Record Type", "description": "Filter for assets that have this DNS record type, e.g. `A`,`CNAME`,`MX`." }, "dns_resolves": { "$ref": "#/components/schemas/BooleanFilter", "description": "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." }, "custom_tags": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/RequireAllFilter" } ], "title": "Custom Tags", "description": "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. By using `*` you can filter for assets that have at least one custom tag applied. By using an empty(`[]`) list you can filter for assets that have no custom tags applied." }, "custom_tags_strict": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/RequireAllFilter" } ], "title": "Custom Tags Strict", "description": "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. By using `*` you can filter for assets that have at least one custom tag applied. By using an empty(`[]`) list you can filter for assets that have no custom tags applied." }, "asn": { "anyOf": [ { "$ref": "#/components/schemas/IntEqFilter" }, { "$ref": "#/components/schemas/IntInFilter" } ], "title": "Asn", "description": "Filter for assets which either are, or point to, an IP address announced by the provided ASN (e.g. `16509`)." }, "ip_geo_country_iso": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" } ], "title": "Ip Geo Country Iso", "description": "Filter for assets which either are, or point to, an IP address located in the provided ISO country code (e.g. `US`)." }, "ip_owner": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" } ], "title": "Ip Owner", "description": "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." }, "registry": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Registry", "description": "Filter for assets by their IP registry source (e.g., 'arin', 'ripe', 'apnic')." }, "whois_email_current": { "anyOf": [ { "$ref": "#/components/schemas/EmailEqFilter" }, { "$ref": "#/components/schemas/EmailInFilter" } ], "title": "Whois Email Current", "description": "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": { "anyOf": [ { "$ref": "#/components/schemas/EmailEqFilter" }, { "$ref": "#/components/schemas/EmailInFilter" } ], "title": "Whois Email", "description": "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." } }, "type": "object", "title": "AssetPropertiesFilter", "description": "Filter options for asset properties (hostname, IP, tags, ports, etc.)." }, "AssetSearchRequest": { "properties": { "filter": { "anyOf": [ { "$ref": "#/components/schemas/AssetFilter" }, { "type": "null" } ], "examples": [ {} ] }, "pagination": { "$ref": "#/components/schemas/Pagination", "examples": [ { "limit": 100 } ] }, "enrichments": { "items": { "$ref": "#/components/schemas/AssetEnrichment" }, "type": "array", "title": "Enrichments" }, "sort": { "anyOf": [ { "items": { "$ref": "#/components/schemas/AssetSortField" }, "type": "array" }, { "items": { "prefixItems": [ { "$ref": "#/components/schemas/AssetSortField" }, { "$ref": "#/components/schemas/SortDirection" } ], "type": "array", "maxItems": 2, "minItems": 2 }, "type": "array" } ], "title": "Sort" } }, "type": "object", "title": "AssetSearchRequest", "description": "Search request body for querying assets with filters, sorting, and pagination." }, "AssetSortField": { "type": "string", "enum": [ "discovered_at", "added_to_project_at", "last_scanned_at", "exposure_score", "asset_id", "apex_domain" ], "title": "AssetSortField", "description": "Field to sort asset results by." }, "BooleanFilter": { "properties": { "eq": { "type": "boolean", "title": "Eq" } }, "type": "object", "required": [ "eq" ], "title": "BooleanFilter", "description": "Boolean filter (true/false)." }, "Certificate": { "properties": { "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "issued_at": { "type": "string", "format": "date-time", "title": "Issued At" }, "sha256": { "type": "string", "title": "Sha256" }, "subject": { "$ref": "#/components/schemas/CertificateEntity" }, "subject_alt_names": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Subject Alt Names" }, "issuer": { "anyOf": [ { "$ref": "#/components/schemas/CertificateEntity" }, { "type": "null" } ] }, "chain": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Certificate" }, "type": "array" }, { "type": "null" } ], "title": "Chain" }, "signature_algorithm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Signature Algorithm" } }, "type": "object", "required": [ "expires_at", "issued_at", "sha256", "subject" ], "title": "Certificate", "description": "TLS/SSL certificate details found on an asset." }, "CertificateEntity": { "properties": { "common_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Common Name" }, "organization_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization Name" }, "organizational_unit_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organizational Unit Name" }, "country_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Name" } }, "type": "object", "title": "CertificateEntity", "description": "Certificate entity (subject or issuer) with organization details." }, "CertificateInstance": { "properties": { "certificate": { "$ref": "#/components/schemas/Certificate", "description": "The details of the certificate iself." }, "seen_ports": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Port" }, "type": "array" }, { "type": "null" } ], "title": "Seen Ports", "description": "When available, indicates 'where' we saw this certificate. An asset may have serviced different certificaes on different ports, at different times" } }, "type": "object", "required": [ "certificate" ], "title": "CertificateInstance", "description": "A `CertificateInstance` represents the linkage between a Certificate (unique on sha256) and the `Port`s an IPs it was seen on for this asset." }, "CertificatePropertiesFilter": { "properties": { "certificate_subject": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/ContainsFilter" }, { "type": "null" } ], "title": "Certificate Subject", "description": "Filter where certificate `subject` or `organizationName` matches the provided value" }, "certificate_subject_alt_name": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/ContainsFilter" }, { "type": "null" } ], "title": "Certificate Subject Alt Name", "description": "Filter here the certificate Subject Alternate Names section matches the provided value" }, "certificate_sha256": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "type": "null" } ], "description": "Filter where the certificate public key sha256 value matches the provided value" }, "certificate_expires_at": { "anyOf": [ { "$ref": "#/components/schemas/DateRangeFilter" }, { "type": "null" } ], "description": "Filter where the certificate expiration matches the provided value" }, "certificate_issued_at": { "anyOf": [ { "$ref": "#/components/schemas/DateRangeFilter" }, { "type": "null" } ], "description": "Filter where the certificate issuance date matches the provided value" }, "certificate_issuer": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Certificate Issuer", "description": "Filter where the certificate (or in the chain) issuer's common name or organization matches the provided value" }, "certificate_covers_domain": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/ContainsFilter" }, { "type": "null" } ], "title": "Certificate Covers Domain", "description": "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" } }, "type": "object", "title": "CertificatePropertiesFilter", "description": "Filter options for certificate properties (issuer, expiration, etc.)." }, "ContainsFilter": { "properties": { "contains": { "type": "string", "title": "Contains" } }, "type": "object", "required": [ "contains" ], "title": "ContainsFilter", "description": "Substring containment filter." }, "DNSRecord": { "properties": { "record_type": { "type": "string", "title": "Record Type" }, "value": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DNSValue" }, "type": "array" }, { "type": "null" } ], "title": "Value" }, "is_virtual": { "type": "boolean", "title": "Is Virtual", "description": "Is this a virtual DNS record?", "default": false } }, "type": "object", "required": [ "record_type", "value" ], "title": "DNSRecord", "description": "A DNS record associated with an asset." }, "DNSValue": { "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "object" } ], "title": "Value" }, "seen_from": { "items": { "type": "string" }, "type": "array", "title": "Seen From" }, "first_seen_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "First Seen At" }, "last_resolved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Resolved At" } }, "type": "object", "required": [ "value", "last_resolved_at" ], "title": "DNSValue", "description": "A DNS record value with type and resolution details." }, "DateRangeFilter": { "properties": { "start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "End" } }, "type": "object", "title": "DateRangeFilter", "description": "Date range filter with from/to bounds." }, "DefensiveControl": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the technology, sometimes prefixed with the vendor", "examples": [ "Apache httpd", "OpenSSH" ] }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vendor", "description": "If available, the vendor of the product", "examples": [ "Microsoft", "Apache" ] }, "technology_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technology Type", "description": "If available, the type of technology" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "If available, the specific version of the product", "examples": [ "v1.0.0", "v2.3-p1" ] }, "instances": { "items": { "$ref": "#/components/schemas/TechnologyInstance" }, "type": "array", "title": "Instances", "description": "Specific instances of this technology" } }, "type": "object", "required": [ "name" ], "title": "DefensiveControl", "description": "A defensive security control (e.g., WAF, CDN) detected on an asset." }, "EmailEqFilter": { "properties": { "eq": { "type": "string", "format": "email", "title": "Eq" } }, "type": "object", "required": [ "eq" ], "title": "EmailEqFilter", "description": "Exact email address match filter." }, "EmailInFilter": { "properties": { "in": { "items": { "type": "string", "format": "email" }, "type": "array", "title": "In" } }, "type": "object", "required": [ "in" ], "title": "EmailInFilter", "description": "Email address inclusion filter (matches any in list)." }, "EqFilter": { "properties": { "eq": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "string", "format": "ipvanyaddress" }, { "type": "string", "format": "ipvanynetwork" }, { "type": "string", "format": "date" } ], "title": "Eq" } }, "type": "object", "required": [ "eq" ], "title": "EqFilter", "description": "Exact value match filter." }, "Exposure": { "properties": { "id": { "type": "string", "title": "Id" }, "detection_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detection Id" }, "severity": { "$ref": "#/components/schemas/ExposureSeverity" }, "instances": { "items": { "$ref": "#/components/schemas/ExposureInstance" }, "type": "array", "title": "Instances" }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Details" }, "supports_evidence": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Supports Evidence", "description": "Does this exposure support evidence downloads?" } }, "type": "object", "required": [ "id", "detection_id", "severity", "instances" ], "title": "Exposure", "description": "A security exposure (vulnerability, misconfiguration, or risk) detected on an asset." }, "ExposureInstance": { "properties": { "port_number": { "type": "integer", "title": "Port Number" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Details" } }, "type": "object", "required": [ "port_number" ], "title": "ExposureInstance", "description": "A specific instance of an exposure found on an asset." }, "ExposurePropertiesFilter": { "properties": { "severity": { "anyOf": [ { "$ref": "#/components/schemas/InFilter" }, { "$ref": "#/components/schemas/EqFilter" } ], "title": "Severity", "description": "Filter for assets which have an exposure severity matching or higher than the provided value. Acceptable values: unknown, informational, moderate, critical." }, "signature_id": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" } ], "title": "Signature Id", "description": "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`." }, "asset_exposure_score": { "$ref": "#/components/schemas/IntRangeFilter", "description": "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." }, "last_scanned_at": { "anyOf": [ { "$ref": "#/components/schemas/DateRangeFilter" }, { "type": "null" } ], "description": "Filter on the date (Y-m-d) when the asset was last scanned for exposures." } }, "type": "object", "title": "ExposurePropertiesFilter", "description": "Filter options for exposure properties (severity, signature, etc.)." }, "ExposureSeverity": { "type": "string", "enum": [ "unknown", "informational", "moderate", "critical" ], "title": "ExposureSeverity", "description": "Exposure severity level." }, "GeoLocation": { "properties": { "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continent", "description": "Continent of the IP address" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Country of the IP address" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City of the IP address" }, "country_iso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Iso", "description": "ISO code of the country of the IP address" } }, "type": "object", "title": "GeoLocation", "description": "Geographic location data for an IP address." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError", "description": "Validation error response with detail about which fields failed." }, "IPMetadata": { "properties": { "as_number": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "As Number", "description": "Autonomous System Number which IP/block is registered to" }, "owner_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Owner Name", "description": "AS or Org Name of the IP/block is registered to" }, "registry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registry", "description": "Nearest or top-level RIR", "examples": [ "RIPE", "ARIN" ] }, "owner_geo": { "anyOf": [ { "$ref": "#/components/schemas/GeoLocation" }, { "type": "null" } ], "description": "Geolocation information for the IP address" } }, "type": "object", "title": "IPMetadata", "description": "Metadata about an IP address including ASN and geolocation." }, "InFilter": { "properties": { "in": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "string", "format": "ipvanyaddress" }, { "type": "string", "format": "ipvanynetwork" }, { "type": "string", "format": "date" }, { "$ref": "#/components/schemas/ExposureSeverity" } ] }, "type": "array", "title": "In" } }, "type": "object", "required": [ "in" ], "title": "InFilter", "description": "Value inclusion filter (matches any in list)." }, "IntEqFilter": { "properties": { "eq": { "type": "integer", "title": "Eq" } }, "type": "object", "required": [ "eq" ], "title": "IntEqFilter", "description": "Exact integer match filter." }, "IntInFilter": { "properties": { "in": { "items": { "type": "integer" }, "type": "array", "title": "In" } }, "type": "object", "required": [ "in" ], "title": "IntInFilter", "description": "Integer inclusion filter." }, "IntRangeFilter": { "properties": { "start": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "End" } }, "type": "object", "required": [ "start", "end" ], "title": "IntRangeFilter", "description": "Integer range filter with min/max bounds." }, "NeqFilter": { "properties": { "neq": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "string", "format": "ipvanyaddress" }, { "type": "string", "format": "ipvanynetwork" }, { "type": "string", "format": "date" } ], "title": "Neq" } }, "type": "object", "required": [ "neq" ], "title": "NeqFilter", "description": "Not-equal filter (excludes matching values)." }, "Pagination": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "An opaque value which should be passed as the `cursor` to retrieve the next page of results. If None or not present there are no remaining pages. This value should not be interpreted by the client." }, "limit": { "type": "integer", "maximum": 1000, "title": "Limit", "description": "The number of items to return", "default": 50 } }, "type": "object", "title": "Pagination", "description": "Cursor-based pagination parameters for requests." }, "PaginationResponse": { "properties": { "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "An opaque value which should be passed as the `cursor` to retrieve the next page of results. If None or not present there are no remaining pages. This value should not be interpreted by the client." }, "limit": { "type": "integer", "title": "Limit", "description": "The number of items returned", "default": 50 }, "total": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Total" }, "sort": { "anyOf": [ { "items": { "prefixItems": [ { "type": "string" }, { "type": "string" } ], "type": "array", "maxItems": 2, "minItems": 2 }, "type": "array" }, { "type": "null" } ], "title": "Sort", "description": "The sort order of the results" } }, "type": "object", "title": "PaginationResponse", "description": "Cursor-based pagination data in responses." }, "Port": { "properties": { "port": { "type": "integer", "title": "Port", "description": "The open port number" }, "protocol": { "type": "string", "title": "Protocol", "description": "The protocol of the open port, should be one of UDP or TCP" }, "instances": { "items": { "$ref": "#/components/schemas/PortInstance" }, "type": "array", "title": "Instances", "description": "The specific instances of this port on an IP" }, "certificate": { "anyOf": [ { "$ref": "#/components/schemas/Certificate" }, { "type": "null" } ] } }, "type": "object", "required": [ "port", "protocol" ], "title": "Port", "description": "An open port detected on an asset." }, "PortInstance": { "properties": { "seen_ip": { "anyOf": [ { "type": "string", "format": "ipvanyaddress" }, { "type": "string", "format": "ipv6" } ], "title": "Seen Ip" }, "seen_at": { "type": "string", "format": "date-time", "title": "Seen At" }, "service": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Service", "description": "The service protocol running on the open port" }, "technology": { "anyOf": [ { "$ref": "#/components/schemas/TechnologyWithInstances" }, { "type": "null" } ], "description": "The application running on the open port" }, "web_technologies": { "anyOf": [ { "items": { "$ref": "#/components/schemas/TechnologyWithInstances" }, "type": "array" }, { "type": "null" } ], "title": "Web Technologies", "description": "Web technologies detected on this port" }, "exposures": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Exposure" }, "type": "array" }, { "type": "null" } ], "title": "Exposures", "description": "Exposures detected on this port" }, "defenses": { "anyOf": [ { "items": { "$ref": "#/components/schemas/DefensiveControl" }, "type": "array" }, { "type": "null" } ], "title": "Defenses", "description": "Defensive measures in place for the port" } }, "type": "object", "required": [ "seen_ip", "seen_at" ], "title": "PortInstance", "description": "A specific port instance with service and protocol details." }, "QuickSearchFilter": { "properties": { "search": { "type": "string", "title": "Search", "description": "Search term to match against asset name, IP addresses, and technology fields" } }, "type": "object", "required": [ "search" ], "title": "QuickSearchFilter", "description": "Quick search text filter for assets." }, "RequireAllFilter": { "properties": { "in": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "type": "string", "format": "ipvanyaddress" }, { "type": "string", "format": "ipvanynetwork" }, { "type": "string", "format": "date" }, { "$ref": "#/components/schemas/ExposureSeverity" } ] }, "type": "array", "title": "In" } }, "type": "object", "required": [ "in" ], "title": "RequireAllFilter", "description": "Filter requiring all specified values to match." }, "ScannedIP": { "properties": { "ip": { "type": "string", "format": "ipvanyaddress", "title": "Ip" }, "last_scanned_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Scanned At", "description": "Datetime when a port scan was run on this IP address" }, "whois": { "anyOf": [ { "$ref": "#/components/schemas/WHOISRecord" }, { "type": "null" } ] }, "open_ports": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Port" }, "type": "array" }, { "type": "null" } ], "title": "Open Ports" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/IPMetadata" }, { "type": "null" } ], "description": "Ownership and ASN information about this IP address" }, "is_responsive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Responsive", "description": "Indicates whether this IP address is unresponsive over ICMP and no ports were found open" } }, "type": "object", "required": [ "ip" ], "title": "ScannedIP", "description": "A `ScannedIP` is a container for a specific IP address that an asset resolves to and that we have performed scanning\nactivities on.\n\nThere may be cases where we discover different technologies or vulnerabilities depending on which IP was looked at." }, "SortDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "SortDirection", "description": "Sort direction (ascending or descending)." }, "TechnologyInstance": { "properties": { "seen_at": { "type": "string", "format": "date-time", "title": "Seen At" }, "seen_port": { "type": "integer", "title": "Seen Port" }, "seen_url": { "anyOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Seen Url", "description": "The URL where this technology was seen, if applicable" } }, "type": "object", "required": [ "seen_at", "seen_port" ], "title": "TechnologyInstance", "description": "A technology (software/framework) detected on an asset." }, "TechnologyPropertiesFilter": { "properties": { "open_port_number": { "anyOf": [ { "$ref": "#/components/schemas/IntEqFilter" }, { "$ref": "#/components/schemas/IntInFilter" }, { "type": "null" } ], "title": "Open Port Number", "description": "Filter for assets which have an open port with the provided number (e.g. `80`)." }, "open_port_service": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Open Port Service", "description": "Filter for assets which have an open port that appears to support the provided protocol (e.g. `http`, `rdp`, `ftp`)." }, "open_port_protocol": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Open Port Protocol", "description": "Filter for assets which have an open port on the provided protocol (e.g. `tcp`, `udp`)." }, "open_port_technology": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Open Port Technology", "description": "Filter for assets which have a specific product listening on an open port (e.g. `nginx`, `apache httpd`)" }, "waf_detected": { "anyOf": [ { "$ref": "#/components/schemas/BooleanFilter" }, { "type": "null" } ], "description": "Filter for assets where a WAF (Web Application Firewall) is detected." }, "waf_name": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Waf Name", "description": "Filter for assets where a specific WAF is detected. Will attempt to match both vendor and product, e.g. `Cloudflare`." }, "technology_name": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Technology Name", "description": "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": { "anyOf": [ { "$ref": "#/components/schemas/EqFilter" }, { "$ref": "#/components/schemas/InFilter" }, { "type": "null" } ], "title": "Web Technology Name", "description": "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." }, "is_responsive": { "anyOf": [ { "$ref": "#/components/schemas/BooleanFilter" }, { "type": "null" } ], "description": "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." } }, "type": "object", "title": "TechnologyPropertiesFilter", "description": "Filter options for technology properties (name, version, vendor, etc.)." }, "TechnologyWithInstances": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the technology, sometimes prefixed with the vendor", "examples": [ "Apache httpd", "OpenSSH" ] }, "vendor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Vendor", "description": "If available, the vendor of the product", "examples": [ "Microsoft", "Apache" ] }, "technology_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Technology Type", "description": "If available, the type of technology" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Version", "description": "If available, the specific version of the product", "examples": [ "v1.0.0", "v2.3-p1" ] }, "instances": { "items": { "$ref": "#/components/schemas/TechnologyInstance" }, "type": "array", "title": "Instances", "description": "Specific instances of this technology" } }, "type": "object", "required": [ "name" ], "title": "TechnologyWithInstances", "description": "A technology with all instances where it was detected." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError", "description": "Individual field validation error with location and message." }, "WHOISContact": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Email address of the contact", "examples": [ "contact@example.com" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Name of the contact, if available", "examples": [ "John Doe" ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Organization", "description": "Organization of the contact", "examples": [ "Your Company Here" ] }, "is_current": { "type": "boolean", "title": "Is Current", "description": "Is this still a current contact?", "default": true } }, "type": "object", "title": "WHOISContact", "description": "A WHOIS contact record (registrant, admin, tech)." }, "WHOISRecord": { "properties": { "registrar": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Registrar", "description": "Registrar of the domain if known" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At", "description": "Expiration date of the domain" }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Updated At", "description": "Last updated date of the domain" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At", "description": "Creation date of the domain" }, "is_private": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Private", "description": "Is the domain registration private?" }, "is_from_parent": { "type": "boolean", "title": "Is From Parent", "description": "Is this WHOIS record from the parent domain?", "default": false }, "contacts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WHOISContact" }, "type": "array" }, { "type": "null" } ], "title": "Contacts", "description": "Contacts associated with the domain" }, "name_servers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Name Servers", "description": "Primary nameservers for the domain" } }, "type": "object", "title": "WHOISRecord", "description": "From proposal:\ncontact.email\ncontact.organization\ncontact.name\nexpires\ncreated\nupdated\nregistrar" } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "apikey" } } }, "x-readme": { "proxy-enabled": false } } ```