Writing Your First Nmap NSE Script on Kali Linux

Writing Your First Nmap NSE Script on Kali Linux

Nmap Scripting Engine (NSE) lets you extend Nmap’s core functionality with Lua scripts, perfect for automating custom checks, fingerprinting odd services, or probing obscure protocols. In this guide, we’ll set up your Kali environment, write a “hello world” script, build a real-world check, then test and package it for reuse.

---

1. Install dependencies

Make sure you’ve got Nmap and Lua support installed on Kali:

sudo apt update && sudo apt install -y nmap lua5.3 liblua5.3-dev

Why?
• nmap provides the --script engine.
• lua5.3 and liblua5.3-dev give you the runtime and headers for compiling and running Lua scripts.

---

2. Locate your NSE scripts folder

By default, NSE scripts live under /usr/share/nmap/scripts. To keep your custom work separate, create a local directory:

mkdir -p ~/.nmap/scripts
export NMAPDIR=~/.nmap

When you run Nmap, point it at your folder with --script:

nmap --script=~/.nmap/scripts/hello.nse target.com

---

3. Write a “Hello world” NSE script

Create ~/.nmap/scripts/hello.nse with this minimal Lua code:

description = [[
  Prints “Hello, NSE!” when the host is up.
]]

author = "Your Name"
license = "Same as Nmap–See https://nmap.org/book/man-legal.html"
categories = {"safe"}

action = function(host, port)
  if host.state == "up" then
    return "Hello, NSE!"
  end
end

That’s all it takes. Run it:

nmap -Pn --script=~/.nmap/scripts/hello.nse 192.168.1.1

---

4. Build a practical check

Let’s extend it to grab a web server’s favicon.ico hash. Create favicon-hash.nse:

local http = require "http"
local md5  = require "md5"

description = [[
  Fetches /favicon.ico and prints its MD5 hash.
]]

categories = {"discovery","safe"}

action = function(host)
  local resp = http.get(host, 80, "/favicon.ico")
  if resp and resp.body then
    return "favicon hash: " .. md5.sumhexa(resp.body)
  end
end

Save under ~/.nmap/scripts and update the script database:

nmap --script-updatedb

---

5. Test & debug your script

Run Nmap with debugging flags to see what’s happening under the hood:

nmap -d -Pn --script=favicon-hash.nse target.com

• -d shows debug output.
• -Pn skips ping checks.
• --script specifies your script.

---

6. Package & share

If you want to contribute your script upstream or share it with teammates:

• Host it on GitHub under nmap/nse-scripts.
• Submit a pull request to Nmap’s official repo.
• Include clear description, categories, and license fields in your script.

---

With these steps, you’ve gone from zero to writing, testing, and sharing your own NSE scripts on Kali Linux — supercharge your reconnaissance and automation now!

---