Skip to main content

phone-lookup

The phone-lookup tool gathers phone-number intelligence from a list of numbers. It resolves metadata (carrier, line type, region), runs open-source reputation and spam checks, generates search dorks, and attempts a best-effort reverse lookup. Coverage prioritises Spain, LATAM, and Europe, making it a strong reconnaissance node for phone-centric investigations.

Ideal Use Cases & Fit​

This tool excels in scenarios such as:

  • Enriching a batch of phone numbers during reconnaissance, adding carrier, line-type, and region context before deeper investigation.
  • Screening numbers against open-source blocklists and community reporting sites to flag likely spam or fraud callers.
  • Building an intelligence picture around a target where the phone number is the pivot, including best-effort attribution.

It performs best when supplied with numbers in E.164 format and focused on Spain/LATAM/Europe, where provider coverage is strongest. It is less suited to high-volume validation of very large lists at speed, since several providers make live network calls and are subject to per-provider timeouts.

Value in Workflows​

Integrating phone-lookup into security and OSINT workflows strengthens the early enrichment phase, converting a raw list of numbers into structured, provenance-tagged intelligence. Its graph-fragment output slots naturally into downstream correlation and reporting steps, letting teams link numbers to carriers, regions, and reputation signals. The per-provider design also lets builders trade breadth for speed by selecting only the providers relevant to a given case.

Input Data​

The tool expects a file of newline-separated phone numbers, supplied via the -i flag.

  • Format: Newline-separated phone numbers in E.164 (+<country><number>); lines starting with # are ignored.
  • Function: Target
  • Required: Yes

Example:

+34687910523
+34931225081

Output Data​

The tool writes a file in JSON Lines format via the -o flag — one osintgraph fragment per input number.

  • Format: JSONL (flag -o)

Each line contains:

  • entities: the phone-number entity, with provider findings attached as namespaced attributes (e.g. localmeta.carrier, localmeta.line_type).
  • edges: relationships between entities.
  • source / version: provenance of the producing tool.
  • number: the input number the line corresponds to.

Example:

{"entities":[{"id":"phone:+34687910523","type":"phone","value":"+34687910523","attrs":{"localmeta.carrier":"Vodafone","localmeta.country":"Spain","localmeta.line_type":"mobile","localmeta.region":"ES"}}],"edges":[],"source":"phone-lookup","version":"phone-lookup/0.1.0","number":"+34687910523"}

Configuration​

  • only: Comma-separated provider names to run (intersect). Providers: localmeta, dorks, es-blocklist, tc-spamlist, listaspam, spamcalls, numverify, twilio-lookup, vonage-insight, truecallerbot. Optional.
  • exclude: Comma-separated provider names to skip. Optional.
  • region: Default region (ISO alpha-2, e.g. ES) used when an input number is in national rather than E.164 format. Optional.
  • timeout: Per-provider timeout as a Go duration (e.g. 15s). Optional; defaults to 15s.
  • proxy: HTTP/HTTPS proxy URL applied to all network providers (e.g. http(s)://host:port), set with the -p flag. Offline providers (localmeta, dorks, es-blocklist) do not need it. Optional; defaults to PROXY_FULL. Updated: 2026-07-29