Nmapr

Your friendly neighborhood Ruby DSL to Nmap for network exploration!

require "nmapr"

Nmapr.scan :cmd do
  target "192.168.0.*"
  ports  22, 80, 8080
  detect :version
end
# => "nmap 192.168.0.* -p 22,80,8080 -sV"

📖 TLDR: It's a simple network mapping language built on top of Nmap and Ruby.

🤔 What is it?

Nmapr is an open-source networking mapping language built on Nmap for specifying network mapping schemes, identifying network hosts and instrumenting a friendlier work flow for performing network reconnaissance. At a glance, the specifications for what a scan is doing should be made evident when reading the Nmapr DSL compared to just working with hard to dissect Nmap commands without deep diving into the man page.

👁 Simple & Readable

Nmapr has a core philosophy of simplicity wherever possible. Mostly because otherwise it'd be harder to maintain. Moreover, this allows you to map ( get it? ) your existing knowledge of Nmap directly when using Nmapr without much of a fuss. The code itself should even allow you to expand and enhance the features wherever they may not suite your needs.

What's more readable?

Both will do the same thing, but which one is easier to understand?

Command-line Nmap Command

$ nmap -A -sS -n -D 192.168.0.3,192.168.0.4 -r -e eth0 -g 31337 -f 192.168.0.10,192.168.0.11

Nmapr

Nmapr.scan :cmd do
  targets ["192.168.0.10", "192.168.0.11"]
  aggressive
  tcp :syn
  decoys ["192.168.0.3", "192.168.0.4"]
  sequential
  interface "eth0"
  source_port 31337
  fragment
end

At the end of the day, with Nmapr it should also be easy to modify or write your own Nmapr schemes to build or orchestrate Nmap scans in an automated fashion. If it's not, then there's a problem with the software and an issue can be made on GitHub to address it! Or, if you see something that could be benefited from being simplified or alias'd or something, then I'd be happy to make those adjustments if they fit the scope of the project.

🗣 Domain Specific Language

Nmapr takes advantage of Ruby's flexibility to design Domain Specific Languages (DSL)s. However, the concept of a DSL is widely used in many other software projects. SQL, Regex, and many other projects your may be familiar withuse their own syntax or language to solve a problem in their particular domain. For the case of SQL, a query language; and for Regex, a finite state machine to parse yo 'text -- r_oughly speaking, mind you; and as f_or Nmapr, a network mapping language of sorts built directly on top of Nmap.

🔧 Basic Usage

You can easily build your own Nmap command to run from the command-line yourself.

Nmapr.scan :cmd do
  targets "192.168.0.3-192.168.0.50"
  aggressive
end
# => "nmap 192.168.0.3-192.168.0.50 -A"

Or, if you'd also like to run and capture the stdout, stderr and status of the command if you were to run it in the command-line yourself, then that's as simple as changing one little symbol. You may want to capture the output though in an object though.

result = Nmapr.scan :run do
  targets "192.168.0.3-192.168.0.50"
  aggressive
end

result[:stdout] # your typical nmap output
result[:stderr] # when things go wrong
result[:status] # the status of the command that was run

Sound Fun?

I think so. You can help contribute to Nmapr by giving it a ⭐️ on GitHub because I just really like those.

Contributing Code, Documentation, Memes, Funny Cat GIFS

Or, if you'd like to help find bugs or enhance the current features or documentation of Nmapr, then that'd also be appreciated greatly! Currently just putting all of this together as a one-man show. So, the more the merrier! Thankfully the core of Nmapr was pretty fast to spin up and took a matter of hours to release the first version. Subsequent versions will be based on my own usage and needs that arise from the community if one happens to form around the tool.

Thank You Nmap Man Page

The nmap man page is awesome! You should read it! There's some spelling and gramtical errors, just like in my documentation! So, you can help and probably contribute to both if you want to. This documentation takes liberally from the nmap man page ot provide descriptions for a large part of hte options reflected in Nmapr when using Nmap. So, by no means did I write every single word in this documentation, but I have wrangled it all together to try and help you use this project.

Made with ❤️