ronin-nmap 0.1.0.rc1

data/lib/ronin/nmap.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+#
+# ronin-nmap - A Ruby library for automating nmap and importing nmap scans.
+#
+# Copyright (c) 2023-2024 Hal Brodigan (postmodern.mod3@gmail.com)
+#
+# ronin-nmap is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-nmap is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-nmap.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/nmap/exceptions'
+require 'ronin/nmap/importer'
+require 'ronin/core/home'
+require 'nmap/command'
+require 'nmap/xml'
+
+require 'tempfile'
+require 'fileutils'
+
+module Ronin
+  #
+  # Namespace for the `ronin-nmap` library.
+  #
+  module Nmap
+    # The `~/.cache/ronin-nmap` cache directory.
+    #
+    # @api private
+    CACHE_DIR = Core::Home.cache_dir('ronin-nmap')
+
+    #
+    # Runs `nmap` and parses the XML output.
+    #
+    # @param [Array<#to_s>] targets
+    #   The targets to scan.
+    #
+    # @param [Hash{Symbol => Object}, Boolean, nil] sudo
+    #   Controls whether the `nmap` command should be ran under `sudo`.
+    #   If the `sudo:` keyword argument is not given, then `nmap` will
+    #   automatically be ran under `sudo` if `sync_scan`, `ack_scan`,
+    #   `window_scan`, `maimon_scan`, `null_scan`, `fin_scan`, `xmas_scan`,
+    #   `scan_flags`, `os_fingerprint`, or `traceroute` are enabled.
+    #
+    # @option sudo [Boolean] :askpass
+    #   Enables the `--askpass` `sudo` option.
+    #
+    # @option sudo [Boolean] :background
+    #   Enables the `--background` `sudo` option
+    #
+    # @option sudo [Boolean] :bell
+    #   Enables the `--bell` `sudo` option
+    #
+    # @option sudo [Integer] :close_from
+    #   Enables the `--close-from=...` `sudo` option
+    #
+    # @option sudo [String] :chdir
+    #   Enables the `--chdir=...` `sudo` option
+    #
+    # @option sudo [String] :preserve_env
+    #   Enables the `--preseve-env=...` `sudo` option
+    #
+    # @option sudo [String, Boolean] :group
+    #   Enables the `--preseve-env=...` `sudo` option
+    #
+    # @option sudo [Boolean] :set_home
+    #   Enables the `--set-home` `sudo` option
+    #
+    # @option sudo [String] :host
+    #   Enables the `--host=...` `sudo` option
+    #
+    # @option sudo [Boolean] :login
+    #   Enables the `--login` `sudo` option
+    #
+    # @option sudo [Boolean] :remove_timestamp
+    #   Enables the `--remove-timestamp` `sudo` option
+    #
+    # @option sudo [Boolean] :reset_timestamp
+    #   Enables the `--reset-timestamp` `sudo` option
+    #
+    # @option sudo [Boolean] :non_interactive
+    #   Enables the `--non-interactive` `sudo` option
+    #
+    # @option sudo [Boolean] :preserve_groups
+    #   Enables the `--preserve-groups` `sudo` option
+    #
+    # @option sudo [String] :prompt
+    #   Enables the `--prompt=...` `sudo` option
+    #
+    # @option sudo [String] :chroot
+    #   Enables the `--chroot=...` `sudo` option
+    #
+    # @option sudo [String] :role
+    #   Enables the `--role=...` `sudo` option
+    #
+    # @option sudo [Boolean] :stdin
+    #   Enables the `--stdin` `sudo` option
+    #
+    # @option sudo [Boolean] :shell
+    #   Enables the `--shell` `sudo` option
+    #
+    # @option sudo [String] :type
+    #   Enables the `--type=...` `sudo` option
+    #
+    # @option sudo [Integer] :command_timeout
+    #   Enables the `--command-timeout=...` `sudo` option
+    #
+    # @option sudo [String] :other_user
+    #   Enables the `--other-user=...` `sudo` option
+    #
+    # @option sudo [String] :user
+    #   Enables the `--user=...` `sudo` option
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments for `nmap`.
+    #
+    # @yield [nmap]
+    #   If a block is given, it will be passed the new `nmap` command object
+    #   for additional configuration.
+    #
+    # @yieldparam [::Nmap::Command] nmap
+    #   The `nmap` command object.
+    #
+    # @return [::Nmap::XML]
+    #   If the `nmap` command was successful, the parsed nmap XML data will be
+    #   returned.
+    #
+    # @raise [NotInstalled]
+    #   The `nmap` command was not installed.
+    #
+    # @raise [ScanFailed]
+    #   The `nmap` scan failed.
+    #
+    # @example
+    #   xml = Nmap.scan('192.168.1.*', syn_scan: true, ports: [80, 443])
+    #   # => #<Nmap::XML: ...>
+    #   xml.up_hosts
+    #   # => [#<Nmap::XML::Host: 192.168.1.1>, ...]
+    #
+    # @example with a block:
+    #   xml = Nmap.scan do |nmap|
+    #     nmap.syn_scan = true
+    #     nmap.ports    = [80, 443]
+    #     nmap.targets  = '192.168.1.*'
+    #   end
+    #   # => #<Nmap::XML: ...>
+    #
+    # @see https://rubydoc.info/gems/ruby-nmap/Nmap/Command
+    # @see https://rubydoc.info/gems/ruby-nmap/Nmap/XML
+    #
+    # @api public
+    #
+    def self.scan(*targets, sudo: nil, **kwargs,&block)
+      nmap = ::Nmap::Command.new(**kwargs,&block)
+
+      nmap.targets ||= targets
+
+      unless nmap.output_xml
+        FileUtils.mkdir_p(CACHE_DIR)
+        tempfile = Tempfile.new(['nmap','.xml'], CACHE_DIR)
+
+        nmap.output_xml = tempfile.path
+      end
+
+      sudo ||= nmap.syn_scan ||
+               nmap.ack_scan ||
+               nmap.window_scan ||
+               nmap.maimon_scan ||
+               nmap.null_scan ||
+               nmap.fin_scan ||
+               nmap.xmas_scan ||
+               nmap.scan_flags ||
+               nmap.ip_scan ||
+               nmap.os_fingerprint ||
+               nmap.traceroute
+
+      # run the nmap command
+      status = case sudo
+               when Hash       then nmap.sudo_command(**sudo)
+               when true       then nmap.sudo_command
+               when false, nil then nmap.run_command
+               else
+                 raise(ArgumentError,"sudo keyword must be a Hash, true, false, or nil")
+               end
+
+      # if the command was successful, return the parsed XML, otherwise raises
+      # an exception.
+      case status
+      when nil
+        raise(NotInstalled,"the nmap command is not installed")
+      when false
+        raise(ScanFailed,"nmap scan failed: #{nmap.command_argv.join(' ')}")
+      else
+        ::Nmap::XML.open(nmap.output_xml)
+      end
+    end
+
+    #
+    # Parses a nmap XML file.
+    #
+    # @param [String] path
+    #   The path to the nmap XML file.
+    #
+    # @return [::Nmap::XML]
+    #   The parsed nmap XML file.
+    #
+    # @see https://rubydoc.info/gems/ruby-nmap/Nmap/XML
+    #
+    # @api public
+    #
+    def self.parse(path)
+      ::Nmap::XML.open(path)
+    end
+  end
+end

data/man/ronin-nmap-completion.1

@@ -0,0 +1,76 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-nmap-completion 1 "2024-01-01" Ronin Nmap "User Manuals"
+.SH NAME
+.PP
+ronin\-nmap\-completion \- Manages shell completion rules for \fBronin\-nmap\fR
+.SH SYNOPSIS
+.PP
+\fBronin\-nmap completion\fR \[lB]\fIoptions\fP\[rB]
+.SH DESCRIPTION
+.PP
+The \fBronin\-nmap completion\fR command can print, install, or uninstall shell
+completion rules for the \fBronin\-nmap\fR command\.
+.PP
+Supports installing completion rules for Bash or Zsh shells\.
+Completion rules for the Fish shell is currently not supported\.
+.SS ZSH SUPPORT
+.PP
+Zsh users will have to add the following lines to their \fB\[ti]\[sl]\.zshrc\fR file in
+order to enable Zsh\[cq]s Bash completion compatibility layer:
+.PP
+.RS 4
+.EX
+autoload \-Uz \[pl]X compinit && compinit
+autoload \-Uz \[pl]X bashcompinit && bashcompinit
+.EE
+.RE
+.SH OPTIONS
+.TP
+\fB\-\-print\fR
+Prints the shell completion file\.
+.TP
+\fB\-\-install\fR
+Installs the shell completion file\.
+.TP
+\fB\-\-uninstall\fR
+Uninstalls the shell completion file\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Prints help information\.
+.SH ENVIRONMENT
+.TP
+\fIPREFIX\fP
+Specifies the root prefix for the file system\.
+.TP
+\fIHOME\fP
+Specifies the home directory of the user\. Ronin will search for the
+\fB\[ti]\[sl]\.cache\[sl]ronin\-nmap\fR cache directory within the home directory\.
+.TP
+\fIXDG\[ru]DATA\[ru]HOME\fP
+Specifies the data directory to use\. Defaults to \fB\[Do]HOME\[sl]\.local\[sl]share\fR\.
+.SH FILES
+.TP
+\fB\[ti]\[sl]\.local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The user\-local installation directory for Bash completion files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]bash\-completion\[sl]completions\[sl]\fR
+The system\-wide installation directory for Bash completions files\.
+.TP
+\fB\[sl]usr\[sl]local\[sl]share\[sl]zsh\[sl]site\-functions\[sl]\fR
+The installation directory for Zsh completion files\.
+.SH EXAMPLES
+.TP
+\fBronin\-nmap completion \-\-print\fR
+Prints the shell completion rules instead of installing them\.
+.TP
+\fBronin\-nmap completion \-\-install\fR
+Installs the shell completion rules for \fBronin\-nmap\fR\.
+.TP
+\fBronin\-nmap completion \-\-uninstall\fR
+Uninstalls the shell completion rules for \fBronin\-nmap\fR\.
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME

data/man/ronin-nmap-completion.1.md

@@ -0,0 +1,78 @@
+# ronin-nmap-completion 1 "2024-01-01" Ronin Nmap "User Manuals"
+
+## NAME
+
+ronin-nmap-completion - Manages shell completion rules for `ronin-nmap`
+
+## SYNOPSIS
+
+`ronin-nmap completion` [*options*]
+
+## DESCRIPTION
+
+The `ronin-nmap completion` command can print, install, or uninstall shell
+completion rules for the `ronin-nmap` command.
+
+Supports installing completion rules for Bash or Zsh shells.
+Completion rules for the Fish shell is currently not supported.
+
+### ZSH SUPPORT
+
+Zsh users will have to add the following lines to their `~/.zshrc` file in
+order to enable Zsh's Bash completion compatibility layer:
+
+    autoload -Uz +X compinit && compinit
+    autoload -Uz +X bashcompinit && bashcompinit
+
+## OPTIONS
+
+`--print`
+: Prints the shell completion file.
+
+`--install`
+: Installs the shell completion file.
+
+`--uninstall`
+: Uninstalls the shell completion file.
+
+`-h`, `--help`
+: Prints help information.
+
+## ENVIRONMENT
+
+*PREFIX*
+: Specifies the root prefix for the file system.
+
+*HOME*
+: Specifies the home directory of the user. Ronin will search for the
+  `~/.cache/ronin-nmap` cache directory within the home directory.
+
+*XDG_DATA_HOME*
+: Specifies the data directory to use. Defaults to `$HOME/.local/share`.
+
+## FILES
+
+`~/.local/share/bash-completion/completions/`
+: The user-local installation directory for Bash completion files.
+
+`/usr/local/share/bash-completion/completions/`
+: The system-wide installation directory for Bash completions files.
+
+`/usr/local/share/zsh/site-functions/`
+: The installation directory for Zsh completion files.
+
+## EXAMPLES
+
+`ronin-nmap completion --print`
+: Prints the shell completion rules instead of installing them.
+
+`ronin-nmap completion --install`
+: Installs the shell completion rules for `ronin-nmap`.
+
+`ronin-nmap completion --uninstall`
+: Uninstalls the shell completion rules for `ronin-nmap`.
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+

data/man/ronin-nmap-convert.1

@@ -0,0 +1,33 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-nmap-convert 1 "2023-03-01" Ronin Nmap "User Manuals"
+.SH NAME
+.PP
+ronin\-nmap\-convert \- Converts an nmap XML file to JSON or CSV
+.SH SYNOPSIS
+.PP
+\fBronin\-nmap convert\fR \[lB]\fB\-\-format\fR \fBjson\fR\[or]\fBcsv\fR\[rB] \fIXML\[ru]FILE\fP \[lB]\fIOUTPUT\[ru]FILE\fP\[rB]
+.SH DESCRIPTION
+.PP
+Converts an nmap XML file to JSON or CSV\.
+.SH ARGUMENTS
+.TP
+\fIXML\[ru]FILE\fP
+The nmap XML file to import\.
+.TP
+\fIOUTPUT\[ru]FILE\fP
+The optional output file to write to\.
+.SH OPTIONS
+.TP
+\fB\-F\fR, \fB\-\-format\fR \fBjson\fR\[or]\fBcsv\fR
+Sets the output conversion format to JSON or CSV\. If the option is not given,
+the output conversion format Will be inferred from the \fIOUTPUT\[ru]FILE\fP file
+extension\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help information
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME

data/man/ronin-nmap-convert.1.md

@@ -0,0 +1,36 @@
+# ronin-nmap-convert 1 "2023-03-01" Ronin Nmap "User Manuals"
+
+## NAME
+
+ronin-nmap-convert - Converts an nmap XML file to JSON or CSV
+
+## SYNOPSIS
+
+`ronin-nmap convert` [`--format` `json`\|`csv`] *XML_FILE* [*OUTPUT_FILE*]
+
+## DESCRIPTION
+
+Converts an nmap XML file to JSON or CSV.
+
+## ARGUMENTS
+
+*XML_FILE*
+: The nmap XML file to import.
+
+*OUTPUT_FILE*
+: The optional output file to write to.
+
+## OPTIONS
+
+`-F`, `--format` `json`|`csv`
+: Sets the output conversion format to JSON or CSV. If the option is not given,
+  the output conversion format Will be inferred from the *OUTPUT_FILE* file
+  extension.
+
+`-h`, `--help`
+: Print help information
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+

data/man/ronin-nmap-dump.1

@@ -0,0 +1,141 @@
+.\" Generated by kramdown-man 1.0.1
+.\" https://github.com/postmodern/kramdown-man#readme
+.TH ronin-nmap-dump 1 "2023-03-01" Ronin Nmap "User Manuals"
+.SH NAME
+.PP
+ronin\-nmap\-dump \- Dumps the scanned ports from nmap XML file(s)\.
+.SH SYNOPSIS
+.PP
+\fBronin\-nmap dump\fR \[lB]options\[rB] \fIXML\[ru]FILE\fP \[lB]\.\.\.\[rB]
+.SH DESCRIPTION
+.PP
+Dumps the scanned ports from nmap XML files into a variety of formats\. The
+output formats include:
+.RS
+.IP \(bu 2
+IP
+.IP \(bu 2
+Hostname
+.IP \(bu 2
+\fBIP:PORT\fR
+.IP \(bu 2
+\fBHOST:PORT\fR
+.IP \(bu 2
+URI
+.RE
+.PP
+The command also supports filtering the nmap targets by IP, IP range, domain,
+OS, port, service, or NSE script\.
+.SH ARGUMENTS
+.TP
+\fIXML\[ru]FILE\fP
+The nmap XML file to import\.
+.SH OPTIONS
+.TP
+\fB\-\-print\-ips\fR
+Only print the IP addresses of the targets (ex: \fB192\.168\.1\.1\fR)\.
+.TP
+\fB\-\-print\-hosts\fR
+Only print the hostnames of the targets (ex: \fBexample\.com\fR)\.
+.TP
+\fB\-\-print\-ip\-ports\fR
+Print IP address and port pairs for each target (ex: \fB192\.168\.1\.1:443\fR)\.
+This is the default behavior\.
+.TP
+\fB\-\-print\-host\-ports\fR
+Print hostname and port pairs for each target (ex: \fBexample\.com:443\fR)\.
+.TP
+\`\-\-print\-uris
+Print URIs for each target that has either \fBhttp\fR or \fBhttps\fR services
+(ex: \fBhttps:\[sl]\[sl]example\.com\fR or \fBhttp:\[sl]\[sl]example\.com:8080\fR)\.
+.TP
+\fB\-\-ip\fR \fIIP\fP
+Filters the targets by a specific IP address\.
+.TP
+\fB\-\-ip\-range\fR \fICIDR\fP
+Filter the targets by a CIDR IP range (ex: \fB192\.168\.1\.0\[sl]24\fR)\.
+.TP
+\fB\-\-domain\fR \fIDOMAIN\fP
+Filters the targets by a domain (ex: \fBexample\.com\fR)\.
+.TP
+\fB\-\-with\-os\fR \fIOS\fP
+Filters the targets by Operating System (ex: \fBLinux\fR, \fBWindows\fR, etc)\.
+.TP
+\fB\-\-with\-ports\fR \[lC]\fIPORT\fP \[or] \fIPORT1\fP\fB\-\fR\fIPORT2\fP\[rC]\fB,\fR\.\.\.
+Filter targets that have open ports in the port list\.
+The port list is a comma separated list of port numbers (\fB443\fR) or port
+ranges (\fB8000\-9000\fR)\.
+.TP
+\fB\-\-with\-service\fR \fISERVICE\fP\[lB]\fB,\fR\.\.\.\[rB]
+Filters targets who are running one of the specified services\.
+.TP
+\fB\-\-with\-script\fR \fISCRIPT\fP\[lB]\fB,\fR\.\.\.\[rB]
+Filters targets that have the NSE script name(s)\.
+.TP
+\fB\-\-with\-script\-output\fR \fISTRING\fP
+Filters targets that have NSE script output contain the string\.
+.TP
+\fB\-\-with\-script\-regex\fR \fB\[sl]\fR\fIREGEX\fP\fB\[sl]\fR
+Filters targets that have NSE script output that matches the regular
+expression\.
+.TP
+\fB\-p\fR, \fB\-\-ports\fR \[lC]\fIPORT\fP \[or] \fIPORT1\-PORT2\fP\[rC],\.\.\.
+Filter \fBIP:PORT\fR or \fBHOST:PORT\fR pairs who\[cq]s ports are in the gvien port list\.
+The port list is a comma separated list of port numbers (\fB443\fR) or port
+ranges (\fB8000\-9000\fR)\.
+.TP
+\fB\-\-services\fR \fISERVICE\fP\[lB]\fB,\fR\.\.\.\[rB]
+Filters \fBIP:PORT\fR or \fBHOST:PORT\fR pairs who\[cq]s ports are running one of the
+specifiied services\.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help information
+.SH EXAMPLES
+.PP
+Print \fBIP:PORT\fR pairs from the nmap XML file:
+.PP
+.RS 4
+.EX
+\[Do] ronin\-nmap dump \-\-print\-ip\-ports scan\.xml
+.EE
+.RE
+.PP
+Print \fBIP:PORT\fR pairs with ports 22, 80, or 443, from the nmap XML file:
+.PP
+.RS 4
+.EX
+\[Do] ronin\-nmap dump \-\-print\-ip\-ports \-\-ports 22,80,443 scan\.xml
+.EE
+.RE
+.PP
+Print \fBHOST:PORT\fR pairs from the nmap XML file:
+.PP
+.RS 4
+.EX
+\[Do] ronin\-nmap dump \-\-print\-host\-ports scan\.xml
+.EE
+.RE
+.PP
+Print target hostnames from the nmap XML file:
+.PP
+.RS 4
+.EX
+\[Do] ronin\-nmap dump \-\-print\-hosts \-\-with\-port 22 scan\.xml
+.EE
+.RE
+.PP
+Print URIs from the nmap XML file:
+.PP
+.RS 4
+.EX
+\[Do] ronin\-nmap dump \-\-print\-uris scan\.xml
+.EE
+.RE
+.SH AUTHOR
+.PP
+Postmodern 
+.MT postmodern\.mod3\[at]gmail\.com
+.ME
+.SH SEE ALSO
+.PP
+.BR ronin\-nmap\-print (1)

data/man/ronin-nmap-dump.1.md

@@ -0,0 +1,119 @@
+# ronin-nmap-dump 1 "2023-03-01" Ronin Nmap "User Manuals"
+
+## NAME
+
+ronin-nmap-dump - Dumps the scanned ports from nmap XML file(s).
+
+## SYNOPSIS
+
+`ronin-nmap dump` [options] *XML_FILE* [...]
+
+## DESCRIPTION
+
+Dumps the scanned ports from nmap XML files into a variety of formats. The
+output formats include:
+
+* IP
+* Hostname
+* `IP:PORT`
+* `HOST:PORT`
+* URI
+
+The command also supports filtering the nmap targets by IP, IP range, domain,
+OS, port, service, or NSE script.
+
+## ARGUMENTS
+
+*XML_FILE*
+: The nmap XML file to import.
+
+## OPTIONS
+
+`--print-ips`
+: Only print the IP addresses of the targets (ex: `192.168.1.1`).
+
+`--print-hosts`
+: Only print the hostnames of the targets (ex: `example.com`).
+
+`--print-ip-ports`
+: Print IP address and port pairs for each target (ex: `192.168.1.1:443`).
+  This is the default behavior.
+
+`--print-host-ports`
+: Print hostname and port pairs for each target (ex: `example.com:443`).
+
+`--print-uris
+: Print URIs for each target that has either `http` or `https` services
+  (ex: `https://example.com` or `http://example.com:8080`).
+
+`--ip` *IP*
+: Filters the targets by a specific IP address.
+
+`--ip-range` *CIDR*
+: Filter the targets by a CIDR IP range (ex: `192.168.1.0/24`).
+
+`--domain` *DOMAIN*
+: Filters the targets by a domain (ex: `example.com`).
+
+`--with-os` *OS*
+: Filters the targets by Operating System (ex: `Linux`, `Windows`, etc).
+
+`--with-ports` {*PORT* \| *PORT1*`-`*PORT2*}`,`...
+: Filter targets that have open ports in the port list.
+  The port list is a comma separated list of port numbers (`443`) or port
+  ranges (`8000-9000`).
+
+`--with-service` *SERVICE*[`,`...]
+: Filters targets who are running one of the specified services.
+
+`--with-script` *SCRIPT*[`,`...]
+: Filters targets that have the NSE script name(s).
+
+`--with-script-output` *STRING*
+: Filters targets that have NSE script output contain the string.
+
+`--with-script-regex` `/`*REGEX*`/`
+: Filters targets that have NSE script output that matches the regular
+  expression.
+
+`-p`, `--ports` {*PORT* | *PORT1-PORT2*},...
+: Filter `IP:PORT` or `HOST:PORT` pairs who's ports are in the gvien port list.
+  The port list is a comma separated list of port numbers (`443`) or port
+  ranges (`8000-9000`).
+
+`--services` *SERVICE*[`,`...]
+: Filters `IP:PORT` or `HOST:PORT` pairs who's ports are running one of the
+  specifiied services.
+
+`-h`, `--help`
+: Print help information
+
+## EXAMPLES
+
+Print `IP:PORT` pairs from the nmap XML file:
+
+    $ ronin-nmap dump --print-ip-ports scan.xml
+
+Print `IP:PORT` pairs with ports 22, 80, or 443, from the nmap XML file:
+
+    $ ronin-nmap dump --print-ip-ports --ports 22,80,443 scan.xml
+
+Print `HOST:PORT` pairs from the nmap XML file:
+
+    $ ronin-nmap dump --print-host-ports scan.xml
+
+Print target hostnames from the nmap XML file:
+
+    $ ronin-nmap dump --print-hosts --with-port 22 scan.xml
+
+Print URIs from the nmap XML file:
+
+    $ ronin-nmap dump --print-uris scan.xml
+
+## AUTHOR
+
+Postmodern <postmodern.mod3@gmail.com>
+
+## SEE ALSO
+
+[ronin-nmap-print](ronin-nmap-print.1.md)