File `whois`

Download: http://nmap.org/svn/scripts/whois.nse

User Summary

Queries the WHOIS services of Regional Internet Registries (RIR) and attempts to retrieve information about the IP Address Assignment which contains the Target IP Address.

The fields displayed contain information about the assignment and the organisation responsible for managing the address space. When output verbosity is requested on the Nmap command line (-v) extra information about the assignment will be displayed.

To determine which of the RIRs to query for a given Target IP Address this script utilises Assignments Data hosted by IANA. The data is cached locally and then parsed for use as a lookup table. The locally cached files are refreshed periodically to help ensure the data is current. If, for any reason, these files are not available to the script then a default sequence of Whois services are queried in turn until: the desired record is found; or a referral to another (defined) Whois service is found; or until the sequence is exhausted without finding either a referral or the desired record.

The script will recognize a referral to another Whois service if that service is defined in the script and will continue by sending a query to the referred service. A record is assumed to be the desired one if it does not contain a referral.

To reduce the number unnecessary queries sent to Whois services a record cache is employed and the entries in the cache can be applied to any targets within the range of addresses represented in the record.

In certain circumstances, the ability to cache responses prevents the discovery of other, smaller IP address assignments applicable to the target because a cached response is accepted in preference to sending a Whois query. When it is important to ensure that the most accurate information about the IP address assignment is retrieved the script argument whodb should be used with a value of "nocache" (see script arguments). This reduces the range of addresses that may use a cached record to a size that helps ensure that smaller assignments will be discovered. This option should be used with caution due to the potential to send large numbers of whois queries and possibly be banned from using the services.

In using this script your IP address will be sent to iana.org. Additionally your address and the address of the target of the scan will be sent to one of the RIRs.

Script Arguments

whodb

Takes any of the following values, which may be combined:

whodb=nofile Prevent the use of IANA assignments data and instead query the default services.
whodb=nofollow Ignore referrals and instead display the first record obtained.
whodb=nocache Prevent the acceptance of records in the cache when they apply to large ranges of addresses.
whodb=[service-ids] Redefine the default services to query. Implies nofile.

http-max-cache-size, http.useragent, pipeline

See the documentation for the http library.

Example Usage

# Basic usage:
nmap target --script whois

# To prevent the use of IANA assignments data supply the nofile value
# to the whodb argument:
nmap target --script whois --script-args whodb=nofile
nmap target --script whois --script-args whois.whodb=nofile

# Supplying a sequence of whois services will also prevent the use of
# IANA assignments data and override the default sequence:
nmap target --script whois --script-args whodb=arin+ripe+afrinic
nmap target --script whois --script-args whois.whodb=apnic*lacnic
# The order in which the services are supplied is the order in which
# they will be queried. (N.B. commas or semi-colons should not be
# used to delimit argument values.)

# To return the first record obtained even if it contains a referral
# to another service, supply the nofollow value to whodb:
nmap target --script whois --script-args whodb=nofollow
nmap target --script whois --script-args whois.whodb=nofollow+ripe
# Note that only one service (the first one supplied) will be used in
# conjunction with nofollow.

# To ensure discovery of smaller assignments even if larger ones
# exist in the cache, supply the nocache value to whodb:
nmap target --script whois --script-args whodb=nocache
nmap target --script whois --script-args whois.whodb=nocache

Script Output

Host script results:
|  whois: Record found at whois.arin.net
|  netrange: 64.13.134.0 - 64.13.134.63
|  netname: NET-64-13-143-0-26
|  orgname: Titan Networks
|  orgid: INSEC
|_ country: US stateprov: CA

Requires

id \r?\n%s*[Oo]rg[\-]-[Ii][Dd]:(.-)\r?\n

categories discovery external safe

author jah <jah at zadkiel.plus.com>

copyright © See Nmap License: http://nmap.org/book/man-legal.html

Action

action (host)

Queries WHOIS services until an applicable record is found or the list of services to query is exhausted and finishes by displaying elements of an applicable record.

Parameters

host:

Hostrule

hostrule (host)

This script will run only if the target IP address has been determined to be routable on the Internet.

Parameters

host:

Functions

add_to_cache (ip, range, redirect, data)	Caches discovered records and referrals in the registry. The cache is indexed by the Target IP addresses sent as Whois query terms. A lookup against the cache is performed by testing the cached IP address range, hence a range must always be present in each cache entry. Where a range is not passed as a parameter, a small assignment containing the Target's IP address is instead cached. Either a referral or output data should also be present in the cache - so one or the other should always be passed as a parameter.
analyse_response (tracking, ip, response, data)	Extracts fields (if present) from the information returned in response to our query and determines whether it represents a referral to a record hosted elsewhere. The referral is cached in the registry to allow threads for targets in the same assignment to avoid performing their queries to this service. If it is not a referral, we assume it is the desired record and the extracted fields are cached in the registry ready for output.
check_response_cache (ip)	Checks the registry for cached redirects and results applicable to the supplied Target's IP address.
conditional_download (url, mod_date, e_tag)	Performs either an HTTP Conditional GET request if mod_date or e_tag is passed, or a plain GET request otherwise. Will follow a single redirect for the remote resource.
constrain_response (response, db, ip, meta)	Attempts to reduce the query response to a subset containing the most specific assignment information. It does this by collecting inetnum objects (and their positions in the response) and choosing the smallest assignment represented by them. A subset beginning with the most specific inetnum object and ending before any further inetnum objects is returned along with the position of the subset within the entire response.
do_query (db, ip)	Connects to a whois service (usually TCP port 43) and sends an IP address query, returning any response.
extract_objects_from_response (response_string, db, ip, meta, specific_object)	Extracts Whois record objects (or a single object) and accompanying fields from the supplied (possibly partial) response to a whois query. If a fifth parameter specific_object is not supplied, all objects defined in fields_meta will be captured if they are present in the response.
file_exists (file)	Given a filepath, checks for the existence of that file.
file_is_expired (time_string)	Checks the age of the supplied timestamp and compares it to the value of local_assignments_file_expiry.
format_data_for_output (data)	Uses the output_short or output_long tables to format the supplied table of data for output as a string.
get_args ()	Parses the command line arguments passed to the script with --script-args. Sets flags in the registry which threads read to determine certain behaviours. Permitted args are 'nofile' - Prevents use of a list of assignments to determine which service to query, 'nofollow' - Prevents following redirects found in records, 'arin', 'ripe', 'apnic', etc. - Service id's, as defined in the whoisdb table in the registry (see script_init).
get_assignment (ip, prefix)	Given an IP address and a prefix length, returns a string representing a valid IP address assignment (size is not checked) which contains the supplied IP address. For example, with ip = 192.168.1.187 and prefix = 24 the return value will be 192.168.1.1-192.168.1.255
get_cache_key (ip)	Determines which entry in the cache is applicable to the Target and returns the key for that entry.
get_db_from_assignments (ip)	Performs a lookup against assignments data to determine which service to query for the supplied Target.
get_local_assignments_data ()	Makes IANA hosted assignments data available for lookups against that data. In more detail it: Caches a local copy of remote assignments data if copies do not currently exist or are out-of-date. Checks whether the cached copies require updating and performs update as required. Parses the cached copies and populates a table of lookup data which is returned to the caller. Sets a flag in the registry to prevent use of the lookup data in the event of an error.
get_next_action (tracking, ip)	Determines whether or not to query a whois service and which one to query. Checks the cache first - where there may be a redirect or a cached record. If not, it trys to get a service from the assignments files if this was not previously attempted. Finally, if a service has not yet been obtained the first unqueried service from whoisdb_default_order is used. The tracking table is manipulated such that a thread knows its next move in the main loop.
get_output_from_cache (ip)	Retrieves data applicable to the Target from the registry. Cached data is only returned if the Target IP matches a key in the cache. If the Target IP is in a range for which there exists cached data then a pointer string is instead returned.
get_parentpath (fname)	Uses `nmap.fetchfile` to get the path of the parent directory of the supplied Nmap datafile filename.
get_period (period)	Converts a string representing a period of time made up of a quantity and a unit such as "24h" into whole seconds.
get_prefix_length (range)	Calculates the prefix length for the given assignment.
not_short_prefix (ip, range, redirect)	This function prevents the caching of large ranges in certain circumstances which would adversely affect lookups against the cache. Specifically we don't allow a cache entry including either a referral or a found record with a range equal to 0/0 or ::/0. Instead we cache an /8 or, in the case of IPv6, /23 - These are large, but safer ranges. Additionally, we don't allow a cache entry for a found record with ranges larger than IPv4 /8 and IPv6 /23. Instead we cache an /24 or, in the case of IPv6, /96 - These are small ranges and are a fair trade-off between accuracy and repeated queries.
output (ip, services_queried)	Controls what to output at the end of the script execution. Attempts to get data from the registry. If the data is a string it is output as it is. If the data is a table then `format_data_for_output` is called. If there is no cached data, nothing will be output.
parse_assignments (address_family_spec, table_of_lines)	Converts raw data from an assignments file into a form optimised for lookups against that data.
read_from_file (file)	Reads a file, line by line, into a table.
redirection_rules (db, ip, data, meta)	Checks for referrals in fields extracted from the whois query response.
redirection_validation (directed_to, directed_from, icnt)	Decides the value of a redirect and whether it should be followed. Referrals to IANA, found in whois records that represent the "Whole Address Space", are acted upon by redirecting to ARIN or accepting the record from ARIN if it was previously queried. This function also catches (ignores) referrals to the referring service - which happens as a side-effect of the method of redirection detection. The return values of this function will be returned by its parent function.
requires_updating (file)	Checks whether a cached file requires updating via HTTP. The cached file should contain the following string on the second line: "<timestamp><Last-Modified-Date><Entity-Tag>". where timestamp is number of seconds since epoch at the time the file was last cached and Last-Modified-Date is an HTTP compliant date sting returned by an HTTP server at the time the file was last cached and Entity-Tag is an HTTP Etag returned by an HTTP server at the time the file was last cached.
sane_expiry_period (period)	Checks that the supplied string represents a period of time between 0 and 7 days.
script_init ()	Called once per script invocation, the purpose of this function is to populate the registry with variables and data for use by all threads.
smallest_range (range_1, range_2)	When passed to `table.sort`, will sort a table of tables containing IP address ranges in ascending order of size. Identical ranges will be sorted in descending order of their position within a record if it is present.
trim (to_trim)	Trims space characters from either end of a string and converts an empty string to nil.
write_to_file (file, content)	Writes the supplied content to file.

Tables

data	Holds field data captured from the responses of each service queried and includes additional information about the final desired record.
tracking	Used in the main loop to manage mutexes, the structure of tracking is as follows.
whois	Data and flags shared between threads.

Functions

add_to_cache (ip, range, redirect, data)

Caches discovered records and referrals in the registry. The cache is indexed by the Target IP addresses sent as Whois query terms. A lookup against the cache is performed by testing the cached IP address range, hence a range must always be present in each cache entry. Where a range is not passed as a parameter, a small assignment containing the Target's IP address is instead cached. Either a referral or output data should also be present in the cache - so one or the other should always be passed as a parameter.

Parameters

ip: String representing the Target's IP address.
range: String representing the most specific assignment found in a whois record. May be nil.
redirect: String id of a referred service defined in whoisdb.
data: Table or String of extracted data.

Parameters

tracking: Tracking table.
ip: String representing a Target's IP address.
response: String obtained from a service in response to our query.
data: Table of fields captured from previously queried services, indexed by service name.

Return value:

The data table passed as a parameter which may have been added to or may contain only the fields extracted from the desired record (in which case it will no longer be indexed by service name).

Parameters

ip: String representing the Target's IP address.

Return values:

Boolean True if the supplied IP address is within a range of addresses for which there is a cache entry and a redirect or a record is present; otherwise false.
ID of a service defined in whoisdb if a redirect is present; otherwise nil.

Parameters

url: String representing the full URL of the remote resource.
mod_date: String representing an HTTP date.
e_tag: String representing an HTTP entity tag.

Return values:

Table as per http.request or nil in case of a non-HTTP error.
Nil or error message in case of an error.

Parameters

response: String obtained from a whois service in response to our query.
db: String id of the service from which the response was obtained.
ip: String representing the Target's IP address.
meta: Table, nmap.registry.whois.whoisdb[db] where db is either the service queried or a mirrored service.

Return values:

String containing the most specific part of the response (or the entire response if only one inetneum object is present).
Number position of the start of the most specific part of the response.

Parameters

db: String id of a service defined in whoisdb.
ip: String representing the Target's IP address.

Return value:

String response to query or nil.

extract_objects_from_response (response_string, db, ip, meta, specific_object)

Extracts Whois record objects (or a single object) and accompanying fields from the supplied (possibly partial) response to a whois query. If a fifth parameter specific_object is not supplied, all objects defined in fields_meta will be captured if they are present in the response.

Parameters

response_string: String obtained from a service in response to our query.
db: String id of the whois service queried.
ip: String representing the Target's IP address.
meta: Table, nmap.registry.whois.whoisdb[db] where db is either the service queried or a mirrored service.
specific_object: Optional string index of a single object defined in fields_meta (e.g. "inetnum").

Return value:

Table indexed by object name containing the fields captured for each object found.

file_exists (file)

Given a filepath, checks for the existence of that file.

Parameters

file: Path to a file.

Return values:

Boolean True if file exists and can be read or false if file does not exist or is empty or cannot be otherwise read.
Nil or error message. No error message if the file is empty or does not exist, only if the file cannot be read for some other reason.

file_is_expired (time_string)

Checks the age of the supplied timestamp and compares it to the value of local_assignments_file_expiry.

Parameters

time_string: String representing a timestamp (seconds since epoch).

Return value:

Boolean True if the period elapsed since the timestamp is longer than the value of local_assignments_file_expiry also returns true if the parameter is not of the expected type, otherwise returns false.

Parameters

data: Table of captured fields grouped into whois record objects from a single record. data.id is a string id of the service from which the record was retrieved and data.mirror is a string id of a mirrored service.

Return value:

String, ready for output (i.e. to be returned by action() ).

get_args ()

Parses the command line arguments passed to the script with --script-args. Sets flags in the registry which threads read to determine certain behaviours. Permitted args are 'nofile' - Prevents use of a list of assignments to determine which service to query, 'nofollow' - Prevents following redirects found in records, 'arin', 'ripe', 'apnic', etc. - Service id's, as defined in the whoisdb table in the registry (see script_init).

get_assignment (ip, prefix)

Given an IP address and a prefix length, returns a string representing a valid IP address assignment (size is not checked) which contains the supplied IP address. For example, with ip = 192.168.1.187 and prefix = 24 the return value will be 192.168.1.1-192.168.1.255

Parameters

ip: String representing an IP address.
prefix: String or number representing a prefix length. Should be of the same address family as ip.

Return values:

String representing a range of addresses from the first to the last hosts (or nil in case of an error).
Nil or error message in case of an error.

get_cache_key (ip)

Determines which entry in the cache is applicable to the Target and returns the key for that entry.

Parameters

ip: String representing the Target's IP address.

Return value:

String key (IP address) of the cache entry applicable to the Target.

get_db_from_assignments (ip)

Performs a lookup against assignments data to determine which service to query for the supplied Target.

Parameters

ip: String representing the Target's IP address.

Return value:

String id of the whois service to query, or nil.

get_local_assignments_data ()

Makes IANA hosted assignments data available for lookups against that data. In more detail it: Caches a local copy of remote assignments data if copies do not currently exist or are out-of-date. Checks whether the cached copies require updating and performs update as required. Parses the cached copies and populates a table of lookup data which is returned to the caller. Sets a flag in the registry to prevent use of the lookup data in the event of an error.

Return values:

Table of lookup data (or nil in case of an error).
Nil or error message in case of an error.

Parameters

tracking: The Tracking table.
ip: String representing the Target's IP address.

Return value:

The supplied and possibly modified tracking table.

Parameters

ip: String representing the Target's IP address.

Return value:

Table or string or nil.

Parameters

fname: String - Filename of an Nmap datafile.

Return values:

String - The filepath of the directory containing the supplied filename including the trailing slash (or nil in case of an error).
Nil or error message in case of an error.

get_period (period)

Converts a string representing a period of time made up of a quantity and a unit such as "24h" into whole seconds.

Parameters

period: String combining a quantity and a unit of time. Acceptable units are days (D or d), hours (H or h), minutes (M or m) and seconds (S or s). If a unit is not supplied or not one of the above acceptable units, it is assumed to be seconds. Negative or fractional periods are permitted.

Return value:

Number representing the supplied period in whole seconds (or nil in case of an error).

get_prefix_length (range)

Calculates the prefix length for the given assignment.

Parameters

range: String representing an IP address assignment

Return value:

Number - prefix length of the assignment

not_short_prefix (ip, range, redirect)

This function prevents the caching of large ranges in certain circumstances which would adversely affect lookups against the cache. Specifically we don't allow a cache entry including either a referral or a found record with a range equal to 0/0 or ::/0. Instead we cache an /8 or, in the case of IPv6, /23 - These are large, but safer ranges. Additionally, we don't allow a cache entry for a found record with ranges larger than IPv4 /8 and IPv6 /23. Instead we cache an /24 or, in the case of IPv6, /96 - These are small ranges and are a fair trade-off between accuracy and repeated queries.

Parameters

ip: String representing the Target's IP address.
range: String representing a range of IP addresses.
redirect:

Usage:

range = not_short_prefix( ip, range )

Return value:

String range - either the supplied, or a modified one (or nil in case of an error).

Parameters

ip: String representing the Target's IP address.
services_queried: Table of strings. Each is the id of a whois service queried for the Target (tracking.completed).

Return value:

String - Host Script Results.

Parameters

address_family_spec: Table (assoc. array) containing patterns for extracting data.
table_of_lines: Table containing a line of data per table element.

Return values:

Table - each element of the form { range = { first = data, last = data }, service = data } (or nil in case of an error).
Nil or error message in case of an error.

read_from_file (file)

Reads a file, line by line, into a table.

Parameters

file: String representing a filepath.

Return values:

Table (array-style) of lines read from the file (or nil in case of an error).
Nil or error message in case of an error.

redirection_rules (db, ip, data, meta)

Checks for referrals in fields extracted from the whois query response.

Parameters

db: String id of the whois service queried.
ip: String representing the Target's IP address.
data: Table, indexed by whois service id, of extracted fields.
meta: Table, nmap.registry.whois.whoisdb[db] where db is either the service queried or a mirrored service.

Return values:

Boolean "found". True if a referral is not found (i.e. No Referral means the desired record has been "found"), otherwise False.
String "redirect". Service id to which we are referred, or nil.
Number "iana_count". This is the total number of referral to IANA for this Target (for all queries) and is stored in data.iana.

Parameters

directed_to: String id of a whois service.
directed_from: String id of a whois service.
icnt: Number of total redirects to IANA.

Return values:

Boolean "found". True if a redirect is not found or ignored, otherwise False.
String "redirect". Service id to which we are redirected, or nil.
Number "iana_count" which is incremented here if applicable.

requires_updating (file)

Checks whether a cached file requires updating via HTTP. The cached file should contain the following string on the second line: "<timestamp><Last-Modified-Date><Entity-Tag>". where timestamp is number of seconds since epoch at the time the file was last cached and Last-Modified-Date is an HTTP compliant date sting returned by an HTTP server at the time the file was last cached and Entity-Tag is an HTTP Etag returned by an HTTP server at the time the file was last cached.

Parameters

file: Filepath of the cached file.

Return values:

Boolean False if file does not require updating, true otherwise.
nil or a valid modified-date (string).
nil or a valid entity_tag (string).

Parameters

period: String representing a period.

Return value:

Number representing the supplied period or a failsafe period in whole seconds.

Parameters

range_1: Table: {range = String, pointer = Number} where range is an IP address range and pointer is the position of that range in a record.
range_2: Same as range_1.

Return value:

Boolean True if the positions of range_1 and range_2 in the table being sorted are correct, otherwise false.

trim (to_trim)

Trims space characters from either end of a string and converts an empty string to nil.

Parameters

to_trim: String to be trimmed.

Return value:

String, trimmed. If the string is empty before or after trimming (or if the parameter was not a string) then returns nil.

write_to_file (file, content)

Writes the supplied content to file.

Parameters

file: String representing a filepath (if it exists it will be overwritten).
content: String or table of data to write to file. Empty string or table is permitted. A table will be written to file with each element of the table on a new line.

Return values:

Boolean True on success or nil in case of an error.
Nil or error message in case of an error.

Tables

data

Holds field data captured from the responses of each service queried and includes additional information about the final desired record.

The table, indexed by whois service id, holds a table of fields captured from each queried service. Once it has been determined that a record represents the final record we wish to output, the existing values are destroyed and replaced with the one required record. This is done purely to make it easier to reference the data of a desired record. Other values in the table are as follows.

Fields

data.iana: is set after the table is initialised and is the number of times a response encountered represents "The Whole Address Space". If the value reaches 2 it is assumed that a valid record is held at ARIN.
data.id: is set in <code>analyse_response</code> after final record and is the service name at which a valid record has been found. Used in <code>format_data_for_output</code>.
data.mirror: is set in <code>analyse_response</code> after final record and is the service name from which a mirrored record has been found. Used in <code>format_data_for_output</code>.
data.comparison: is set in <code>analyse_response</code> after final record and is a string concatenated from fields extracted from a record and which serves as a fingerprint for a record, used in <code>get_cache_key</code>, to compare two records for equality.

tracking

Used in the main loop to manage mutexes, the structure of tracking is as follows.

Fields

this_db: The service for which a thread will wait for exclusive access before sending a query to it.
next_db: The next service to query. Allows a thread to continue in the main "while do" loop.
last_db: The value of this_db after sending a query, used when exclusive access to a service is no longer required.
completed: An array of services previously queried.

whois

Data and flags shared between threads.

Fields

whoisdb_default_order: The default number and order of whois services to query.
using_local_assignments_file: Set this to: false; to avoid using the data from IANA hosted assignments files (false when whodb=nofile).
local_assignments_file_expiry: A period, between 0 and 7 days, during which cached assignments data may be used without being refreshed.
init_done: Set when <code>script_init</code> has been called and prevents it being called again.
mutex: A table of mutex functions, one for each service defined herein. Allows a thread exclusive access to a service, preventing concurrent connections to it.
nofollow: A flag that prevents referrals to other whois records and allows the first record retrieved to be returned instead. Set to true when whodb=nofollow
using_cache: A flag which modifies the size of ranges in a cache entry. Set to false when whodb=nocache
cache: Storage for cached redirects, records and other data for output.

NSEDoc

Categories

Scripts

Libraries

File whois

User Summary

Script Arguments

whodb

http-max-cache-size, http.useragent, pipeline

Example Usage

Script Output

Requires

Action

Parameters

Hostrule

Parameters

Functions

Tables

Functions

Parameters

See also:

Parameters

Return value:

See also:

Parameters

Return values:

See also:

Parameters

Return values:

See also:

Parameters

Return values:

See also:

Parameters

Return value:

Parameters

Return value:

Parameters

Return values:

Parameters

Return value:

See also:

Parameters

Return value:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

Return values:

See also:

Parameters

Return value:

See also:

Parameters

Return value:

See also:

Parameters

Return values:

Parameters

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

See also:

Parameters

Return value:

See also:

Parameters

Return values:

Parameters

Return values:

Parameters

Return values:

See also:

Parameters

Return values:

File `whois`