README.md
# ruby-nmap
[![CI](https://github.com/postmodern/ruby-nmap/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/ruby-nmap/actions/workflows/ruby.yml)
[![Code Climate](https://codeclimate.com/github/postmodern/ruby-nmap.svg)](https://codeclimate.com/github/postmodern/ruby-nmap)
[![Gem Version](https://badge.fury.io/rb/ruby-nmap.svg)](https://badge.fury.io/rb/ruby-nmap)
* [Source](https://github.com/postmodern/ruby-nmap/)
* [Issues](https://github.com/postmodern/ruby-nmap/issues)
* [Documentation](http://rubydoc.info/gems/ruby-nmap/frames)
## Description
A Ruby API to [nmap], the exploration tool and security / port scanner.
Allows automating nmap and parsing nmap XML files.
## Features
* Provides a Ruby API for automating nmap.
* Provides a Parser for enumerating nmap XML scan files.
* Supports the full [Nmap XML DTD][nmap-dtd].
## Examples
Run Nmap from Ruby:
```ruby
require 'nmap/command'
Nmap::Command.run do |nmap|
nmap.connect_scan = true
nmap.service_scan = true
nmap.output_xml = 'scan.xml'
nmap.verbose = true
nmap.ports = [20, 21, 22, 23, 25, 80, 110, 443, 512, 522, 8080, 1080]
nmap.targets = '192.168.1.*'
end
```
Run `sudo nmap` from Ruby:
```ruby
require 'nmap/command'
Nmap::Command.sudo do |nmap|
nmap.syn_scan = true
nmap.os_fingerprint = true
nmap.service_scan = true
nmap.output_xml = 'scan.xml'
nmap.verbose = true
nmap.ports = [20, 21, 22, 23, 25, 80, 110, 443, 512, 522, 8080, 1080]
nmap.targets = '192.168.1.*'
end
```
Parse Nmap XML scan files:
```ruby
require 'nmap/xml'
Nmap::XML.open('scan.xml') do |xml|
xml.each_host do |host|
puts "[#{host.ip}]"
host.each_port do |port|
puts " #{port.number}/#{port.protocol}\t#{port.state}\t#{port.service}"
end
end
end
```
Print NSE script output from an XML scan file:
```ruby
require 'nmap/xml'
Nmap::XML.open('nse.xml') do |xml|
xml.each_host do |host|
puts "[#{host.ip}]"
host.scripts.each do |name,output|
output.each_line { |line| puts " #{line}" }
end
host.each_port do |port|
puts " [#{port.number}/#{port.protocol}]"
port.scripts.each do |id,script|
puts " [#{id}]"
script.output.each_line { |line| puts " #{line}" }
end
end
end
end
```
## Requirements
* [ruby] >= 2.0.0
* [nmap] >= 5.00
* [nokogiri] ~> 1.3
* [command_mapper] ~> 0.3
## Install
* Debian / Ubuntu:
```shell
$ sudo apt install nmap
```
* Fedora / RedHat:
```shell
$ sudo dnf install nmap
```
* Homebrew:
```shell
$ brew install nmap
```
```shell
$ gem install ruby-nmap
```
## License
See {file:LICENSE.txt} for license information.
[nmap]: http://www.insecure.org/
[ruby]: https://www.ruby-lang.org/
[nokogiri]: http://nokogiri.rubyforge.org/
[command_mapper]: https://github.com/postmodern/command_mapper.rb#readme
[nmap-dtd]: https://nmap.org/book/nmap-dtd.html