1. Nmap API
When writing Nmap NSE scripts, we of course need to have a way to talk to the Nmap API, which provides us with various advanced features so we don’t have to write those features ourselves. We can’t do everything in LUA language that is used for writing NSE scripts, but we also need a way to talk to the Nmap API. For example: we need a way to check the information that was already gathered about the scanning host or network when running a script. This can be achieved by passing certain arguments to the NSE script within the action function. Let’s present an example of the banner.nse action function:
We can see that the action function accepts two parameters, the
host and port. The host argument passed into the action function
contains information about the host we’re about to scan while the port
argument contains the port about to be scanned. We can then use the host
and port objects in the NSE script to request specific information that
we require.
The host object has the following members:
- host.ip: the IP address of the target host
- host.name: the reverse DNS of the target host
- host.targetname: the name of the host specified in the Nmap command
- host.directly_connected: specifies if the scanning host is on the same local network as the scanned host
- host.mac_addr: the MAC address of the target host (only available if host.directly_connected is true)
- host.max_addr_src: our own MAC address
- host.interface: our own network interface
- host.interface_mtu: maximum transmission unit of our own interface
- host.bin_ip: the IP address of the target host
- host.bin_ip_src: our own IP address
- host.times: contains the RTT, SRTT, RTTVAR and timeout information about the target host
The port object has the following members:
- port.number: the port number of the target host
- port.protocol: the protocol of the target host
- port.service: the service running on the target host
- port.version: additional information about the service running on the target host
- port.state: what state the target port is in: open, open|filtered, filtered, closed.
When writing NSE scripts, we also have direct access to Nsock, which is the Nmap socket library. We can use the Nsock library to perform parallel non-blocking operations, which provides a powerful mechanism that allows running several scripts at the same time efficiently. With the Nsock library, we can achieve something like the following scenario: we can create a socket that connects to a specific IP address and port, send or receive some data, and then close the socket at the end. We can create a socket with the new_socket function call, which returns a new socket object that has the following methods:
- send: send some data to the socket
- receive: receive some data from the socket
- close: close the socket
- set_timeout: sets the timeout value to a socket
- receive_bytes
- receive_lines
- receive_buf
Within Nsock, we can also create raw sockets which are handled with libpcap, but we won’t go into the details right now. Let’s just say the following: the difference between a normal socket and a raw socket is that a normal socket operates right above the TCP or UDP protocol, while a raw socket operates right above the wire (so we need to provide our own Ethernet, IP, TCP/UDP, application headers).
To print some data on the screen when the script is done executing, we need to form a table that contains special keys, which are used to automatically format and print the data on the screen. The LUA is automatically converted to a string for normal output which we can see when we’re running Nmap. Each nested table gets a new level of indentation, which is honored when the output from the script is being printed on the screen.
There’s also a special table called the registry, which holds the variables from all scripts. This is a global storing place that can be used by all scripts to store and retrieve values, which effectively gives us the ability to share data between different scripts. The values in the registry are stored only for the current run of the Nmap program. When writing a key to the global registry, we need to ensure that the key is unique so we don’t accidentally overwrite the value of some other script if the key is the same. When a certain script depends upon some other script’s output value, we must declare that script as a dependency for the initial script, which ensures the correct execution order of the scripts.
2. An Example
In this example, we’ve written a script that should parse all the available HTTP methods that can be run on a specific HTTP server. We can do that by executing the following requests and reading the response from the server:
When doing this with an NSE script, we need to create a socket
that will connect to the target host on port 80 (or some other port),
and send the “OPTIONS / HTTP/1.0″ command string terminated by CRLF. The
server should then respond with all the available HTTP method options
that it supports. An example of running that request on a host Gentoo Linux -- Gentoo Linux News is presented below:
We used the program telnet to connect to the host Gentoo Linux -- Gentoo Linux News on port 80 and executed the “OPTIONS / HTTP/1.0″ command. The request was accepted and the response said that the valid HTTP methods are GET, HEAD, POST and OPTIONS. Now we need to make an NSE script that will do the same thing.
When starting to write the NSE script, we must first define the fields description, categories, dependencies, license and author. This can be seen below:
The rule of the script should decide if the script will be executed or not. If we don’t receive the right host and port information that are passed into the script, we can simply quit the execution of the script and do nothing. In the rule function, we need to take a look at the host and port number and decide whether that specified port is indeed TCP and open (usually the HTTP port is 80). A script must contain one of the following rules that determine if the script will be run or not: prerule, hostrule, portrule or postrule. In our case we can use portrule to determine whether the port number is opened and running HTTP service. We can do this with the following code:
This will return true whenever Nmap thinks that the port is using
HTTP protocol. After that, we only need to specify the action rules,
which contain the actions to be done when the script is run. We won’t
present the action separately, but let’s present the whole script, which
can be seen below:
The above script is run whenever the used port is determined to be using HTTP protocol. In such cases, the script will first send the “OPTIONS” HTTP method to the server host. Afterwards, it will construct the output by inserting specific values to the table object. At the end, the output is presented with the stdnse.format_output command.
When testing the script, we should use the command below which also specifies the debugging options and print enough information to let us know what’s happening. This is especially important when something goes wrong and the script isn’t working as expected.
Whenever the script is run, the following is outputted:
From this we can see that the Nmap script returned only HTTP methods GET and HEAD even though the previous telnet session said that GET, HEAD, POST, and OPTIONS methods are supported. To check what’s happening, we can use the –script-trace and -dd options. The important output is presented below:
We can see that Nmap is actually executing the “OPTIONS / HTTP/1.1″ command and not “OPTIONS / HTTP/1.0″. It seems that the http.generic_request doesn’t support the use of HTTP/1.0 http version. But not to worry, we can also use raw socket to send arbitrary requests. The new script that uses a raw socket to execute arbitrary requests can be seen below:
After running the script, we get the output as presented below:
Now we can see that we get the right options: GET, HEAD, POST and OPTIONS. Our Nmap script is complete.
3. Conclusion
We’ve seen how to actually write a NSE script that actually does something. In our case, this was merely executing an “OPTIONS / HTTP/1.0″ command, but we could have easily written something more complicated.
Tutorial By :lithiuM
When writing Nmap NSE scripts, we of course need to have a way to talk to the Nmap API, which provides us with various advanced features so we don’t have to write those features ourselves. We can’t do everything in LUA language that is used for writing NSE scripts, but we also need a way to talk to the Nmap API. For example: we need a way to check the information that was already gathered about the scanning host or network when running a script. This can be achieved by passing certain arguments to the NSE script within the action function. Let’s present an example of the banner.nse action function:
Code:
action = function( host, port )
local out = grab_banner(host, port)
return output( out )
end
The host object has the following members:
- host.ip: the IP address of the target host
- host.name: the reverse DNS of the target host
- host.targetname: the name of the host specified in the Nmap command
- host.directly_connected: specifies if the scanning host is on the same local network as the scanned host
- host.mac_addr: the MAC address of the target host (only available if host.directly_connected is true)
- host.max_addr_src: our own MAC address
- host.interface: our own network interface
- host.interface_mtu: maximum transmission unit of our own interface
- host.bin_ip: the IP address of the target host
- host.bin_ip_src: our own IP address
- host.times: contains the RTT, SRTT, RTTVAR and timeout information about the target host
The port object has the following members:
- port.number: the port number of the target host
- port.protocol: the protocol of the target host
- port.service: the service running on the target host
- port.version: additional information about the service running on the target host
- port.state: what state the target port is in: open, open|filtered, filtered, closed.
When writing NSE scripts, we also have direct access to Nsock, which is the Nmap socket library. We can use the Nsock library to perform parallel non-blocking operations, which provides a powerful mechanism that allows running several scripts at the same time efficiently. With the Nsock library, we can achieve something like the following scenario: we can create a socket that connects to a specific IP address and port, send or receive some data, and then close the socket at the end. We can create a socket with the new_socket function call, which returns a new socket object that has the following methods:
- send: send some data to the socket
- receive: receive some data from the socket
- close: close the socket
- set_timeout: sets the timeout value to a socket
- receive_bytes
- receive_lines
- receive_buf
Within Nsock, we can also create raw sockets which are handled with libpcap, but we won’t go into the details right now. Let’s just say the following: the difference between a normal socket and a raw socket is that a normal socket operates right above the TCP or UDP protocol, while a raw socket operates right above the wire (so we need to provide our own Ethernet, IP, TCP/UDP, application headers).
To print some data on the screen when the script is done executing, we need to form a table that contains special keys, which are used to automatically format and print the data on the screen. The LUA is automatically converted to a string for normal output which we can see when we’re running Nmap. Each nested table gets a new level of indentation, which is honored when the output from the script is being printed on the screen.
There’s also a special table called the registry, which holds the variables from all scripts. This is a global storing place that can be used by all scripts to store and retrieve values, which effectively gives us the ability to share data between different scripts. The values in the registry are stored only for the current run of the Nmap program. When writing a key to the global registry, we need to ensure that the key is unique so we don’t accidentally overwrite the value of some other script if the key is the same. When a certain script depends upon some other script’s output value, we must declare that script as a dependency for the initial script, which ensures the correct execution order of the scripts.
2. An Example
In this example, we’ve written a script that should parse all the available HTTP methods that can be run on a specific HTTP server. We can do that by executing the following requests and reading the response from the server:
Code:
OPTIONS / HTTP/1.0
Code:
# telnet www.gentoo.org 80
Trying 89.16.167.134...
Connected to www.gentoo.org.
Escape character is '^]'.
OPTIONS / HTTP/1.0
HTTP/1.1 200 OK
Date: Thu, 27 Sep 2012 21:11:04 GMT
Server: Apache
Allow: GET,HEAD,POST,OPTIONS
Content-Length: 0
Connection: close
Content-Type: text/html; charset=utf-8
Connection closed by foreign host.
We used the program telnet to connect to the host Gentoo Linux -- Gentoo Linux News on port 80 and executed the “OPTIONS / HTTP/1.0″ command. The request was accepted and the response said that the valid HTTP methods are GET, HEAD, POST and OPTIONS. Now we need to make an NSE script that will do the same thing.
When starting to write the NSE script, we must first define the fields description, categories, dependencies, license and author. This can be seen below:
Code:
description = [[
Attempts to find the HTTP methods available on the target HTTP server.
]]
author = "Dejan Lukan"
license = "GPL 2.0"
categories = {"default"}
The rule of the script should decide if the script will be executed or not. If we don’t receive the right host and port information that are passed into the script, we can simply quit the execution of the script and do nothing. In the rule function, we need to take a look at the host and port number and decide whether that specified port is indeed TCP and open (usually the HTTP port is 80). A script must contain one of the following rules that determine if the script will be run or not: prerule, hostrule, portrule or postrule. In our case we can use portrule to determine whether the port number is opened and running HTTP service. We can do this with the following code:
Code:
-- returns true if port is likely to be HTTP, false otherwise
portrule = shortport.http
Code:
local http = require "http"
local nmap = require "nmap"
local stdnse = require "stdnse"
local shortport = require "shortport"
local table = require "table"
description = [[
Attempts to find the HTTP methods available on the target HTTP server.
]]
author = "Dejan Lukan"
license = "GPL 2.0"
categories = {"default"}
-- returns true if port is likely to be HTTP, false otherwise
portrule = shortport.http
action = function(host, port)
local out = {}
-- make the "OPTIONS" request
response = http.generic_request(host, port, "OPTIONS", "/")
-- form the output
table.insert(out, string.format("Request : OPTIONS / HTTP/1.0"))
table.insert(out, string.format("Host : %s (%s)", host.ip, host.name))
table.insert(out, string.format("Port : %s", port.number))
table.insert(out, string.format("Allowed Methods : %s", response.header['allow']))
return stdnse.format_output(true, out)
end
The above script is run whenever the used port is determined to be using HTTP protocol. In such cases, the script will first send the “OPTIONS” HTTP method to the server host. Afterwards, it will construct the output by inserting specific values to the table object. At the end, the output is presented with the stdnse.format_output command.
When testing the script, we should use the command below which also specifies the debugging options and print enough information to let us know what’s happening. This is especially important when something goes wrong and the script isn’t working as expected.
Code:
# nmap --script=/home/user/http_options.nse www.gentoo.org -p 80 --script-
trace -dd
Code:
# nmap --script=/home/eleanor/testing/http_options.nse www.gentoo.org -p 80
Starting Nmap 6.01 ( http://nmap.org ) at 2012-10-01 22:05 CEST
Nmap scan report for www.gentoo.org (89.16.167.134)
Host is up (0.051s latency).
PORT STATE SERVICE
80/tcp open http
| http_options:
| Request : OPTIONS / HTTP/1.0
| Host : 89.16.167.134 (www.gentoo.org)
| Port : 80
|_ Allowed Methods : GET,HEAD
Nmap done: 1 IP address (1 host up) scanned in 0.31 seconds
From this we can see that the Nmap script returned only HTTP methods GET and HEAD even though the previous telnet session said that GET, HEAD, POST, and OPTIONS methods are supported. To check what’s happening, we can use the –script-trace and -dd options. The important output is presented below:
Code:
NSE: TCP 192.168.1.2:57257 > 89.16.167.134:80 | CONNECT
NSE: TCP 192.168.1.2:57257 > 89.16.167.134:80 | 00000000: 4f 50 54 49 4f
4e 53 20 2f 20 48 54 54 50 2f 31 OPTIONS / HTTP/1
00000010: 2e 31 0d 0a 43 6f 6e 6e 65 63 74 69 6f 6e 3a 20 .1 Connection:
00000020: 63 6c 6f 73 65 0d 0a 55 73 65 72 2d 41 67 65 6e close User-Agen
00000030: 74 3a 20 4d 6f 7a 69 6c 6c 61 2f 35 2e 30 20 28 t: Mozilla/5.0 (
00000040: 63 6f 6d 70 61 74 69 62 6c 65 3b 20 4e 6d 61 70 compatible; Nmap
00000050: 20 53 63 72 69 70 74 69 6e 67 20 45 6e 67 69 6e Scripting Engin
00000060: 65 3b 20 68 74 74 70 3a 2f 2f 6e 6d 61 70 2e 6f e; http://nmap.o
00000070: 72 67 2f 62 6f 6f 6b 2f 6e 73 65 2e 68 74 6d 6c rg/book/nse.html
00000080: 29 0d 0a 48 6f 73 74 3a 20 77 77 77 2e 67 65 6e ) Host: www.gen
00000090: 74 6f 6f 2e 6f 72 67 0d 0a 0d 0a too.org
We can see that Nmap is actually executing the “OPTIONS / HTTP/1.1″ command and not “OPTIONS / HTTP/1.0″. It seems that the http.generic_request doesn’t support the use of HTTP/1.0 http version. But not to worry, we can also use raw socket to send arbitrary requests. The new script that uses a raw socket to execute arbitrary requests can be seen below:
Code:
local http = require "http"
local nmap = require "nmap"
local stdnse = require "stdnse"
local shortport = require "shortport"
local table = require "table"
description = [[
Attempts to find the HTTP methods available on the target HTTP server.
]]
author = "Dejan Lukan"
license = "GPL 2.0"
categories = {"default"}
-- returns true if port is likely to be HTTP, false otherwise
portrule = shortport.http
action = function(host, port)
local out = {}
-- make the "OPTIONS / HTTP/1.0" request
local socket = nmap.new_socket()
socket:connect(host, port)
socket:send("OPTIONS / HTTP/1.0\r\n\r\n")
s,response = socket:receive()
socket:close()
-- form the output
table.insert(out, string.format("Request : OPTIONS / HTTP/1.0"))
table.insert(out, string.format("Host : %s (%s)", host.ip, host.name))
table.insert(out, string.format("Port : %s", port.number))
table.insert(out, string.match(response, "Allow: [^\r]*\r\n"));
return stdnse.format_output(true, out)
end
After running the script, we get the output as presented below:
Code:
# nmap --script=/home/user/testing/http_options.nse www.gentoo.org -p 80
Starting Nmap 6.01 ( http://nmap.org ) at 2012-10-01 22:12 CEST
Nmap scan report for www.gentoo.org (89.16.167.134)
Host is up (0.052s latency).
PORT STATE SERVICE
80/tcp open http
| http_options2:
| Request : OPTIONS / HTTP/1.0
| Host : 89.16.167.134 (www.gentoo.org)
| Port : 80
|_ Allow: GET,HEAD,POST,OPTIONS
Nmap done: 1 IP address (1 host up) scanned in 0.30 seconds
Now we can see that we get the right options: GET, HEAD, POST and OPTIONS. Our Nmap script is complete.
3. Conclusion
We’ve seen how to actually write a NSE script that actually does something. In our case, this was merely executing an “OPTIONS / HTTP/1.0″ command, but we could have easily written something more complicated.
Tutorial By :lithiuM
No comments:
Post a Comment