ronin-nmap 0.1.0.rc1

data/data/completions/ronin-nmap

@@ -0,0 +1,79 @@
+# ronin-nmap completion                                    -*- shell-script -*-
+
+# This bash completions script was generated by
+# completely (https://github.com/dannyben/completely)
+# Modifying it manually is not recommended
+
+_ronin-nmap_completions_filter() {
+  local words="$1"
+  local cur=${COMP_WORDS[COMP_CWORD]}
+  local result=()
+
+  if [[ "${cur:0:1}" == "-" ]]; then
+    echo "$words"
+  
+  else
+    for word in $words; do
+      [[ "${word:0:1}" != "-" ]] && result+=("$word")
+    done
+
+    echo "${result[*]}"
+
+  fi
+}
+
+_ronin-nmap_completions() {
+  local cur=${COMP_WORDS[COMP_CWORD]}
+  local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")
+  local compline="${compwords[*]}"
+
+  case "$compline" in
+    'new'*'--xml-file')
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -A file -- "$cur" )
+      ;;
+
+    'scan'*'--output')
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -A file -- "$cur" )
+      ;;
+
+    'completion'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--print --install --uninstall")" -- "$cur" )
+      ;;
+
+    'convert'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -A file -W "$(_ronin-nmap_completions_filter "--format -F")" -- "$cur" )
+      ;;
+
+    'scan'*'-o')
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -A file -- "$cur" )
+      ;;
+
+    'import'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -A file -W "$(_ronin-nmap_completions_filter "--db --db-uri --db-file")" -- "$cur" )
+      ;;
+
+    'print'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--ip --ip-range --domain --with-os --with-ports --with-service --with-script --with-script-output --with-script-regex")" -- "$cur" )
+      ;;
+
+    'dump'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--print-ips --print-hosts --print-ip-ports --print-host-ports --print-uris --ip --ip-range --domain --with-os --with-ports --with-service --with-script --with-script-output --with-script-regex --ports -p --services")" -- "$cur" )
+      ;;
+
+    'scan'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--db --db-uri --db-file --sudo --output -o --output-format -F --import")" -- "$cur" )
+      ;;
+
+    'new'*)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--parser --scanner --printing --import --xml-file --syn-scan --ports -p --target")" -- "$cur" )
+      ;;
+
+    *)
+      while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_ronin-nmap_completions_filter "--version -V help completion convert dump grep import new print scan")" -- "$cur" )
+      ;;
+
+  esac
+} &&
+complete -F _ronin-nmap_completions ronin-nmap
+
+# ex: filetype=sh

data/data/templates/script.rb.erb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+require 'ronin/nmap'
+
+<%- if @script_type == :parser -%>
+<%-   if @xml_file -%>
+xml = Ronin::Nmap.parse(<%= @xml_file.inspect %>)
+<%-   else -%>
+xml = Ronin::Nmap.parse(ARGV[0])
+<%-   end -%>
+<%- else -%>
+xml = Ronin::Nmap.scan do |nmap|
+<%-   if @xml_file -%>
+  nmap.xml_file = <%= @xml_file.inspect %>
+<%-   else -%>
+  # nmap.xml_file = "path/to/nmap.xml"
+<%-   end -%>
+<%-   if @syn_scan -%>
+  nmap.syn_scan = true
+<%-   else -%>
+  # nmap.syn_scan = true
+<%-   end -%>
+<%-   if @ports -%>
+  nmap.ports    = <%= @ports.inspect %>
+<%-   else -%>
+  # nmap.ports    = [22, 80, 443, 8000..9000]
+<%-   end -%>
+<%-   case @targets.length -%>
+<%-   when 0 -%>
+  nmap.targets  = ARGV[0]
+<%-   when 1 -%>
+  nmap.targets  = <%= @targets[0].inspect %>
+<%-   else -%>
+  nmap.targets  = <%= @targets.inspect %>
+<%-   end -%>
+end
+<%- end -%>
+<% if @features[:printing] -%>
+
+xml.each_host do |host|
+  puts "[ #{host.ip} ]"
+
+  host.each_port do |port|
+    puts "  #{port.number}/#{port.protocol}\t#{port.state}\t#{port.service}"
+
+    port.scripts.each do |id,script|
+      puts "    [ #{id} ]"
+
+      script.output.each_line { |line| puts "      #{line}" }
+    end
+  end
+end
+<%- end -%>
+<%- if @features[:import] -%>
+
+Ronin::DB.connect
+Ronin::Nmap::Importer.import(xml)
+<%- end -%>

data/gemspec.yml

@@ -0,0 +1,42 @@
+name: ronin-nmap
+summary: A Ruby library and CLI for working with nmap.
+description: |
+  ronin-nmap is a Ruby library for working with nmap. ronin-nmap can parse
+  nmap XML, convert nmap XML into JSON or CSV, or import nmap XML into the
+  ronin-db database.
+
+license: LGPL-3.0
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://ronin-rb.dev/
+has_yard: true
+
+metadata:
+  documentation_uri: https://ronin-rb.dev/docs/ronin-nmap
+  source_code_uri:   https://github.com/ronin-rb/ronin-nmap
+  bug_tracker_uri:   https://github.com/ronin-rb/ronin-nmap/issues
+  changelog_uri:     https://github.com/ronin-rb/ronin-nmap/blob/main/ChangeLog.md
+  rubygems_mfa_required: 'true'
+
+generated_files:
+ - data/completions/ronin-nmap
+ - man/ronin-nmap.1
+ - man/ronin-nmap-completion.1
+ - man/ronin-nmap-convert.1
+ - man/ronin-nmap-dump.1
+ - man/ronin-nmap-grep.1
+ - man/ronin-nmap-import.1
+ - man/ronin-nmap-new.1
+ - man/ronin-nmap-print.1
+ - man/ronin-nmap-scan.1
+
+required_ruby_version: ">= 3.0.0"
+
+dependencies:
+  ruby-nmap: ~> 1.0
+  # Ronin dependencies:
+  ronin-core: ~> 0.2.0.rc1
+  ronin-db: ~> 0.2.0.rc1
+
+development_dependencies:
+  bundler: ~> 2.0

data/lib/ronin/nmap/cli/command.rb

@@ -0,0 +1,40 @@
+# 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/root'
+
+require 'ronin/core/cli/command'
+
+module Ronin
+  module Nmap
+    class CLI
+      #
+      # Base class for all other `ronin-nmap` commands.
+      #
+      class Command < Core::CLI::Command
+
+        man_dir File.join(ROOT,'man')
+
+        bug_report_url 'https://github.com/ronin-rb/ronin-nmap/issues/new'
+
+      end
+    end
+  end
+end

data/lib/ronin/nmap/cli/commands/completion.rb

@@ -0,0 +1,61 @@
+# 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/root'
+require 'ronin/core/cli/completion_command'
+
+module Ronin
+  module Nmap
+    class CLI
+      module Commands
+        #
+        # Manages the shell completion rules for `ronin-nmap`.
+        #
+        # ## Usage
+        #
+        #     ronin-nmap completion [options]
+        #
+        # ## Options
+        #
+        #         --print                      Prints the shell completion file
+        #         --install                    Installs the shell completion file
+        #         --uninstall                  Uninstalls the shell completion file
+        #     -h, --help                       Print help information
+        #
+        # ## Examples
+        #
+        #     ronin-nmap completion --print
+        #     ronin-nmap completion --install
+        #     ronin-nmap completion --uninstall
+        #
+        class Completion < Core::CLI::CompletionCommand
+
+          completion_file File.join(ROOT,'data','completions','ronin-nmap')
+
+          man_dir File.join(ROOT,'man')
+          man_page 'ronin-nmap-completion.1'
+
+          description 'Manages the shell completion rules for ronin-nmap'
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/nmap/cli/commands/convert.rb

@@ -0,0 +1,108 @@
+# 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/cli/command'
+require 'ronin/nmap/converter'
+
+module Ronin
+  module Nmap
+    class CLI
+      module Commands
+        #
+        # Converts an nmap XML file to JSON or CSV.
+        #
+        # ## Usage
+        #
+        #     ronin-nmap convert [--format json|csv] XML_FILE [OUTPUT_FILE]
+        #
+        # ## Option
+        #
+        #     -F, --format json|csv            The desired output format
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     XML_FILE                         The input XML file to parse
+        #     OUTPUT_FILE                      The output file
+        #
+        class Convert < Command
+
+          usage '[--format json|csv] XML_FILE [OUTPUT_FILE]'
+
+          option :format, short: '-F',
+                          value: {
+                            type:     [:json, :csv],
+                            required: true
+                          },
+                          desc: 'The desired output format'
+
+          argument :xml_file, required: true,
+                              desc:     'The input XML file to parse'
+
+          argument :output_file, required: false,
+                                 desc:     'The output file'
+
+          description "Converts an nmap XML file to JSON or CSV"
+
+          man_page 'ronin-nmap-convert.1'
+
+          # The desired output format.
+          #
+          # @return [:json, :csv, nil]
+          attr_reader :format
+
+          #
+          # Runs the `ronin-nmap convert` command.
+          #
+          # @param [String] xml_file
+          #   The XML input file to parse.
+          #
+          # @param [String] output_file
+          #   The output file to write to.
+          #
+          def run(xml_file,output_file=nil)
+            unless File.file?(xml_file)
+              print_error "no such file or directory: #{xml_file}"
+              exit(-1)
+            end
+
+            if output_file
+              if (format = options[:format])
+                Converter.convert_file(xml_file,output_file, format: format)
+              else
+                Converter.convert_file(xml_file,output_file)
+              end
+            else
+              unless (format = options[:format])
+                print_error "must specify a --format if no output file is given"
+                exit(-1)
+              end
+
+              xml = ::Nmap::XML.open(xml_file)
+
+              Converter.convert(xml,stdout, format: format)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/nmap/cli/commands/dump.rb

@@ -0,0 +1,293 @@
+# 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/cli/command'
+require 'ronin/nmap/cli/filtering_options'
+require 'nmap/xml'
+
+require 'set'
+
+module Ronin
+  module Nmap
+    class CLI
+      module Commands
+        #
+        # Dumps the scanned ports from nmap XML file(s).
+        #
+        # ## Usage
+        #
+        #     ronin-nmap dump [options] XML_FILE [...]
+        #
+        # ## Options
+        #
+        #         --print-ips                  Print all IP addresses
+        #         --print-hosts                Print all hostnames
+        #         --print-ip-ports             Print IP:PORT pairs. (Default)
+        #         --print-host-ports           Print HOST:PORT pairs
+        #         --print-uris                 Print URIs
+        #         --ip IP                      Filters the targets by IP
+        #         --ip-range CIDR              Filter the targets by IP range
+        #         --domain DOMAIN              Filters the targets by domain
+        #         --with-os OS                 Filters the targets by OS
+        #         --with-ports {PORT | PORT1-PORT2},...
+        #                                      Filter targets by port numbers
+        #         --with-service SERVICE[,...] Filters targets by service
+        #         --with-script SCRIPT[,...]   Filters targets with the script
+        #         --with-script-output STRING  Filters targets containing the script output
+        #         --with-script-regex /REGEX/  Filters targets containing the script output
+        #         -p, --ports {PORT | PORT1-PORT2},...
+        #                                      Filter targets by port numbers
+        #         --services SERVICE[,...]     Filters targets by service
+        #     -h, --help                       Print help information
+        #
+        # ## Arguments
+        #
+        #     XML_FILE ...                     The nmap XML file(s) to parse
+        #
+        # ## Examples
+        #
+        #     ronin-nmap dump --print-ip-ports scan.xml
+        #     ronin-nmap dump --print-ip-ports --ports 22,80,443 scan.xml
+        #     ronin-nmap dump --print-host-ports scan.xml
+        #     ronin-nmap dump --print-hosts --with-port 22 scan.xml
+        #     ronin-nmap dump --print-uris scan.xml
+        #
+        class Dump < Command
+
+          usage '[options] XML_FILE [...]'
+
+          option :print_ips, desc: 'Print all IP addresses' do
+            @mode = :ips
+          end
+
+          option :print_hosts, desc: 'Print all hostnames' do
+            @mode = :hostnames
+          end
+
+          option :print_ip_ports, desc: 'Print IP:PORT pairs. (Default)' do
+            @mode = :ip_ports
+          end
+
+          option :print_host_ports, desc: 'Print HOST:PORT pairs' do
+            @mode = :host_ports
+          end
+
+          option :print_uris, desc: 'Print URIs' do
+            @mode = :uris
+          end
+
+          include FilteringOptions
+
+          option :ports, short: '-p',
+                         value: {
+                           type: /\A(?:\d+|\d+-\d+)(?:,(?:\d+|\d+-\d+))*\z/,
+                           usage: '{PORT | PORT1-PORT2},...'
+                         },
+                         desc: 'Filter targets by port numbers' do |ports|
+                           @ports << PortList.parse(ports)
+                         end
+
+          option :services, value: {
+                              type: /\A(?:[a-z]+[a-z0-9_+-]*)(?:,[a-z]+[a-z0-9_+-]*)*\z/,
+                              usage: 'SERVICE[,...]'
+                            },
+                            desc: 'Filters targets by service' do |services|
+                              @services.merge(services.split(','))
+                            end
+
+          argument :xml_file, required: true,
+                              repeats:  true,
+                              desc:     'The nmap XML file(s) to parse'
+
+          examples [
+            '--print-ip-ports scan.xml',
+            '--print-ip-ports --ports 22,80,443 scan.xml',
+            '--print-host-ports scan.xml',
+            '--print-hosts --with-port 22 scan.xml',
+            '--print-uris scan.xml'
+          ]
+
+          description 'Dumps the scanned ports from nmap XML file(s)'
+
+          man_page 'ronin-nmap-dump.1'
+
+          #
+          # Initializes the command.
+          #
+          # @param [Hash{Symbol => Object}] kwargs
+          #   Additional keywords for the command.
+          #
+          def initialize(**kwargs)
+            super(**kwargs)
+
+            @mode = :ip_ports
+
+            @ports    = Set.new
+            @services = Set.new
+          end
+
+          #
+          # Runs the `ronin-nmap dump` command.
+          #
+          # @param [Array<String>] xml_files
+          #   The nmap XML files to parse.
+          #
+          def run(*xml_files)
+            xml_files.each do |xml_file|
+              xml = ::Nmap::XML.open(xml_file)
+
+              filter_targets(xml).each do |host|
+                print_target(host)
+              end
+            end
+          end
+
+          #
+          # Prints the targets.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_target(host)
+            case @mode
+            when :ips        then print_ip(host)
+            when :hostnames  then print_hostname(host)
+            when :ip_ports   then print_ip_ports(host)
+            when :host_ports then print_host_ports(host)
+            when :uris       then print_uris(host)
+            end
+          end
+
+          #
+          # Prints the IPs for the target.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_ip(host)
+            puts host.address
+          end
+
+          #
+          # Prints the host names for the target.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_hostnames(host)
+            if (hostname = host.hostname)
+              puts hostname
+            end
+          end
+
+          #
+          # Prints the `IP:PORT` pair for the target.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_ip_ports(host)
+            filter_ports(host).each do |port|
+              puts "#{host.address}:#{port.number}"
+            end
+          end
+
+          #
+          # Prints the `HOST:PORT` pair for the target.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_host_ports(host)
+            filter_ports(host).each do |port|
+              if (hostname = host.hostname)
+                puts "#{hostname}:#{port.number}"
+              end
+            end
+          end
+
+          #
+          # Prints the URIs for the target.
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          def print_uris(host)
+            filter_ports(host).each do |port|
+              if (port.service && port.service.name == 'http') ||
+                 (port.number == 80)
+                puts URI::HTTP.build(
+                  host: host.to_s,
+                  port: port.number
+                )
+              elsif (port.service && port.service.name == 'https') ||
+                    (port.number == 443)
+                puts URI::HTTPS.build(
+                  host: host.to_s,
+                  port: port.number
+                )
+              end
+            end
+          end
+
+          #
+          # @param [::Nmap::XML::Host] host
+          #
+          # @return [Enumerator::Lazy]
+          #
+          def filter_ports(host)
+            ports = host.each_open_port.lazy
+
+            unless @ports.empty?
+              ports = filter_ports_by_number(ports)
+            end
+
+            unless @services.empty?
+              ports = filter_ports_by_service(ports)
+            end
+
+            return ports
+          end
+
+          #
+          # @param [Enumerator::Lazy] ports
+          #
+          # @return [Enumerator::Lazy]
+          #
+          def filter_ports_by_number(ports)
+            ports.filter do |port|
+              @ports.any? do |port_list|
+                port_list.include?(port.number)
+              end
+            end
+          end
+
+          #
+          # @param [Enumerator::Lazy] ports
+          #
+          # @return [Enumerator::Lazy]
+          #
+          def filter_ports_by_service(ports)
+            ports.filter do |port|
+              if (service = port.service)
+                @services.include?(service.name)
+              end
+            end
+          end
+
+        end
+      end
+    end
+  end
+end