Library comm

Common communication functions for network discovery tasks like banner grabbing and data exchange.

The functions in this module return values appropriate for use with exception handling via nmap.new_try.

These functions may be passed a table of options, but it's not required. The keys for the options table are:

  • bytes - minimum number of bytes to read.
  • lines - minimum number of lines to read.
  • proto - string, protocol to use. Default "tcp"
  • timeout - override timeout in milliseconds. This overrides all other timeout defaults, but can be overridden by specific connect and request timeouts (below)
  • connect_timeout - socket timeout for connection. Default: same as stdnse.get_timeout
  • request_timeout - additional socket timeout for requests. This is added to the connect_timeout to get a total time for a request to receive a response. Default: 6000ms
  • recv_before - boolean, receive data before sending first payload
  • any_af - boolean, allow connecting to any address family, inet or inet6. By default, these functions will only use the same AF as nmap.address_family to resolve names.

If both "bytes" and "lines" are provided, "lines" takes precedence. If neither are given, the functions read as many bytes as possible.

Author:

  • Kris Katterjohn 04/2008

Copyright © Same as Nmap--See https://nmap.org/book/man-legal.html

Source: https://svn.nmap.org/nmap/nselib/comm.lua

Functions

exchange (host, port, data, opts)

This function connects to the specified port number on the specified host, sends data, then waits for and returns the response, if any.

get_banner (host, port, opts)

This function simply connects to the specified port number on the specified host and returns any data received.

opencon (host, port, data, opts)

This function opens a connection, sends the first data payload and check if a response is correctly received (what means that the protocol used is fine)

tryssl (host, port, data, opts)

Opens a SSL connection if possible, with fallback to plain text.

Functions

exchange (host, port, data, opts)

This function connects to the specified port number on the specified host, sends data, then waits for and returns the response, if any.

The first return value is true to signal success or false to signal failure. On success the second return value is the response from the remote host. On failure the second return value is an error message.

Parameters

host
The host to connect to.
port
The port on the host.
data
The data to send initially.
opts
The options. See the module description.

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).
get_banner (host, port, opts)

This function simply connects to the specified port number on the specified host and returns any data received.

The first return value is true to signal success or false to signal failure. On success the second return value is the response from the remote host. On failure the second return value is an error message.

Parameters

host
The host to connect to.
port
The port on the host.
opts
The options. See the module description.

Return values:

  1. Status (true or false).
  2. Data (if status is true) or error string (if status is false).
opencon (host, port, data, opts)

This function opens a connection, sends the first data payload and check if a response is correctly received (what means that the protocol used is fine)

Possible options: timeout, connect_timeout, request_timeout: See module documentation recv_before: receive data before sending first payload proto: the protocol to use ("tcp", "udp", or "ssl")

Parameters

host
The destination host IP
port
The destination host port
data
The first data payload of the connection
opts
An options table

Return values:

  1. sd The socket descriptor, nil if no connection is established
  2. response The response received for the payload, or an error message
  3. early_resp If opt recv_before is true, returns the value of the first receive (before sending data)
tryssl (host, port, data, opts)

Opens a SSL connection if possible, with fallback to plain text.

For likely-SSL services (as determined by shortport.ssl), SSL is tried first. For UDP services, only plain text is currently supported.

Either data or opts.recv_before is required:

  • If the service sends a banner first, use opts.recv_before
  • If the service waits for client data first, provide that via data.
  • If you provide neither, then a service that waits for client data will only work with SSL and a service that sends a banner first will require you to do a read to get that banner.

Parameters

host
The host table
port
The port table
data
The first data payload of the connection. Optional if opts.recv_before is true.
opts
Options, such as timeout

Return values:

  1. sd The socket descriptor, or nil on error
  2. response The response received for the payload, or an error message
  3. correctOpt Correct option for connection guess
  4. earlyResp If opt recv_before is true, returns the value of the first receive (before sending data)