nmap-lookup

Enrich Nmap targets with ownership and responsible disclosure routes. Powered by lookup.disclose.io.

Part of the disclose.io security researcher ecosystem — CLI · Burp · Nmap · MCP.

---

Disclosure Lookup — an Nmap NSE script

nmap-lookup adds ownership and responsible-disclosure routing context to Nmap host results. It calls the public lookup API after Nmap selects a public target; it does not probe the target service or submit vulnerability reports.

A disclose.io project. Use the returned contacts as leads, then confirm the current program scope and reporting instructions.

What it does

• Enriches public hostnames and IP addresses with likely organization ownership.
• Surfaces first-party, platform, and coordinator disclosure routes.
• Produces readable terminal output and structured Nmap XML fields.
• Bounds requests, response size, contact count, and untrusted output fields.
• Skips non-public targets and is not part of Nmap's default script set.

Architecture

nmap-lookup/
├── scripts/lookup-disclose.nse   # NSE host rule, API client, validation, output
├── test/lookup-disclose.test.ts  # End-to-end tests against a local fake API
├── docs/marquee.png              # Repository artwork
└── .github/workflows/build.yml   # Metadata validation and test workflow

Concern	Implementation
Target selection	hostrule rejects private and special-use addresses; input selects hostname or IP
API boundary	HTTPS POST to lookup.disclose.io/api/lookup by default
Endpoint safety	Overrides are restricted to literal loopback addresses for local tests
Output safety	API fields are single-line, length-bounded, and type-checked
Scan safety	Global lookup cap, timeout, response-size limit, and no target-service requests

Requirements

• Nmap with the Nmap Scripting Engine
• Network access to https://lookup.disclose.io
• Bun only for local development and tests

Run directly

No installation is required when the script path is supplied explicitly:

nmap -Pn -sn --script ./scripts/lookup-disclose.nse example.com
nmap -sV --script ./scripts/lookup-disclose.nse 1.1.1.1

The script is categorized as discovery, external, and safe, but not default; invoke it by path or name.

Install in Nmap

Homebrew:

sudo cp ./scripts/lookup-disclose.nse "$(brew --prefix nmap)/share/nmap/scripts/"
sudo nmap --script-updatedb
nmap -Pn -sn --script lookup-disclose example.com

Debian and Ubuntu:

sudo cp ./scripts/lookup-disclose.nse /usr/share/nmap/scripts/
sudo nmap --script-updatedb
nmap -Pn -sn --script lookup-disclose example.com

Usage

Host script results:
| lookup-disclose:
|   input: example.com
|   status: complete
|   asset_type: domain
|   organization: Example Corporation
|   attribution_confidence: high
|   route: First-party security reporting route found.
|   reporting_routes:
|     https://example.com/.well-known/security.txt [security_txt, first_party, verified]
|     security@example.com [email, first_party, verified]
|_  source: https://lookup.disclose.io

Script arguments

All arguments use the lookup-disclose. prefix.

Argument	Default	Description
endpoint	https://lookup.disclose.io/api/lookup	Lookup API URL; overrides are limited to literal loopback addresses
input	target	target prefers the supplied hostname; ip always uses the resolved address
max-contacts	3	Reporting routes shown per host, from 1 to 20
max-lookups	50	External requests across the scan, from 1 to 1000
timeout	15000	HTTP timeout in milliseconds, from 1000 to 60000

The NSE integration intentionally does not accept API keys because Nmap's current HTTPS client does not authenticate remote certificates. Custom endpoints are restricted to literal loopback addresses and cannot include userinfo, a query string, or a fragment. Responses are capped at 256 KiB and displayed fields are sanitized and bounded.

Privacy and safety

This is an external NSE script: it sends the chosen public hostname or IP address to lookup.disclose.io. Private and IANA special-use addresses are skipped. The script makes no request to the scanned service beyond whatever scan the operator separately requested from Nmap. Review your authorization, the target's current program scope, and the returned reporting instructions before acting on results.

Development

bun test
nmap --script-help ./scripts/lookup-disclose.nse

The end-to-end tests start a loopback fake API and execute Nmap itself. They are skipped when Nmap is unavailable; continuous integration installs Nmap first.

This repository is a standalone integration. Inclusion in the upstream Nmap script library would require a separate review and submission.

Upstream Nmap submission

Nmap requires contributed scripts to include structured output, complete NSEDoc examples, and an accepted script license. The NSE file uses Nmap's standard script license under the project's contribution grant. Supporting repository content remains MIT licensed.

License

The NSE script is licensed under Nmap's standard terms. All other repository content is MIT licensed © 2026 disclose.io.