lookup

Run a security attribution lookup

Classifies the input, dispatches it to the appropriate strategy, and runs cross-strategy chaining (max depth 3). Returns attribution, reporting paths ordered by applicability to the queried owner/asset, the resolution chain, and the list of data sources queried.

Inputs are auto-classified unless kind explicitly selects an asset type. Use prefix forms to disambiguate (npm:foo, pypi:bar, gh:owner/repo, app:WhatsApp, hw:Cisco ASA, ext:uBlock Origin, desktop:Slack). Browser extensions also accept ext:chrome:<id>, ext:firefox:<slug>, and Chrome/Firefox/Edge store URLs. Bare organization names fall through to the Organization strategy.

Attack-payload short-circuit. Inputs matching SQL-injection and XSS patterns return status: "failed" immediately without running the strategy chain, so abuse traffic does not inflate partial-result metrics.

post/api/lookup

Request

  • Base URL: https://lookup.disclose.io
  • URL: https://lookup.disclose.io/api/lookup
  • Auth: one of:
    • none
    • HTTP bearer
    • API key in header X-API-Key

Headers

X-Request-Idstring

Caller-supplied request identifier. Must match ^[A-Za-z0-9._:-]+$ and be at most 128 characters. Replaced with a server-generated req_<uuid> if absent or malformed. Echoed on every response.

X-Lookup-Sessionstring

Stable opaque browser/client identifier used only to give individual users a fair new-work allowance behind shared NATs. Must be 20–128 characters from A-Z a-z 0-9 . _ : -. Create once and persist; do not rotate per request. Missing or malformed values fall back to IP policy. API-key requests use their key quota instead.

If-None-Matchstring

Comma-separated list of weak ETags. If any matches the current cached ETag, the server returns 304 with no body. Use the ETag from a previous 200 response.

Request body

inputstring required

The asset to look up. Auto-classified unless kind is supplied. Use prefix forms (npm:, pypi:, gh:, app:, hw:, ext:, desktop:) to disambiguate. Browser extensions also accept ext:chrome:<id>, ext:firefox:<slug>, and store URLs.

kind'domain' | 'ipv4' | 'ipv6' | 'url' | 'email' | 'cidr' | 'asn' | 'package' | 'repository' | 'container' | 'cloud-resource' | 'mobile-app' | 'hardware' | 'extension' | 'desktop-app' | 'organization'

Response

Lookup completed (status discriminates outcome).

inputstring required
assetType'domain' | 'ipv4' | 'ipv6' | 'url' | 'email' | 'cidr' | 'asn' | 'package' | 'repository' | 'container' | 'cloud-resource' | 'mobile-app' | 'hardware' | 'extension' | 'desktop-app' | 'organization' required
timestampstring date-time required
status'complete' | 'partial' | 'failed' required

Subset of ResponseStatus emitted by the lookup engine on 200 responses.

requestIdstring required

Same value emitted in the X-Request-Id response header.

hasErrorsboolean required

true when at least one resolution step (in this strategy or any chained child strategy) recorded an error — either by throwing or by returning details.error. Lets consumers render a "results may be incomplete" badge on a complete status whose primary-source step actually crashed. Per-step error detail is on dataSources[].error.

detailsobject required

Free-form per-step diagnostic detail. inputAdvice describes input interpretation: assetType, normalized, explicit, status (ready, clarify, invalid, non_public), code, message, suggestion, and actions. Each action contains label, input, and optional kind usable in another lookup. Ready means syntactically usable, not verified existence or ownership. A package kind without registry coordinates requires clarification. For cloud resources, additive cloudOwnershipSignals entries record provider, exact resource key, identifier kind, role, status, source, and observation time. Roles include owner account, authentication tenant, signer, operator, and publisher; a signal does not by itself establish the responsible organization or an owner reporting route. Optional censysCloudCandidates are public source-host leads from an explicitly enabled Censys search, not ownership or contact proof. When the engine short-circuits on a recognized-but-non-routable input (RFC1918 private space, loopback, multicast, RFC2606 documentation domains, mDNS .local, etc.) the response carries status: failed and details of the shape: reason: "reserved" category: rfc1918 | loopback | link_local | multicast | cgnat | unspecified | ipv6_ula | rfc2606_tld | mdns_local | private_dns | ipv6_docs | test_net | benchmarking | reserved_future rfc: e.g. "RFC1918" voice: short UI-facing line (UI surfaces this; programmatic clients ignore) explanation: one-line factual description suggestion: try-something-else hint When the engine rejects an obvious attack payload, details.reason is "invalid-input" with kind and matchedPattern keys instead. Result-quality signal (additive, present on normal 200 results): ownerContactFound: boolean — false when the only channels are universal CERT/CC coordinators, i.e. no real owner/vendor contact was found. A partial carrying ownerContactFound: false should not be read as a meaningful owner result. kind: "coordinator_only" — set when CERT/CC is the sole channel. For container inputs, details.container carries { registry, registryName, repository, tag, digest, inferredOrg, officialImage, attributable }; attributable: false marks a private, account-scoped registry (ACR / per-account ECR) that cannot be attributed to a public owner. When a local Common Crawl evidence index is configured, details.commonCrawl contains timestamped archived observations and capture provenance. Those observations are historical leads only: archived contacts never appear in contacts, and only explicit organization/domain/repository edges may fan out through the normal live strategies (maximum three, root lookup only).

Changes

No recorded changes to this operation across all 1 revision of this API.