pwn 0.5.739 → 0.5.741

data/lib/pwn/plugins/method_catalog.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'ripper'
+require 'yard'
+
+module PWN
+  module Plugins
+    # JSON-schema descriptors for public PWN::Plugins methods, generated from
+    # YARD / Supported Method Parameters docs. pwn_eval validates kwargs first.
+    module MethodCatalog
+      SIDE_EFFECTS = %w[read_only active_scan exploit destructive].freeze
+
+      public_class_method def self.required_bins
+        []
+      end
+
+      # Build a JSON-schema descriptor for one public plugin method.
+      public_class_method def self.schema(opts = {})
+        mod = plugin_const(opts)
+        name = (opts[:method] || opts[:name]).to_s
+        raise 'ERROR: method is required' if name.empty?
+
+        cache_key = "#{mod}##{name}"
+        @schema_cache ||= {}
+        return @schema_cache[cache_key] if @schema_cache[cache_key]
+
+        keys = allowed_keys(mod: mod, method: name)
+        props = keys.to_h { |key, hint| [key, property_schema(key: key, hint: hint)] }
+        @schema_cache[cache_key] = {
+          name: "#{mod}.#{name}",
+          description: purpose_line(mod: mod, method: name),
+          side_effect: classify_side_effect(mod: mod, method: name),
+          parameters: {
+            type: 'object',
+            properties: props,
+            additionalProperties: false
+          }
+        }
+      end
+
+      # Validate literal kwargs on PWN::Plugins calls; nil means the payload may eval.
+      public_class_method def self.guard_eval(opts = {})
+        code = opts[:code].to_s
+        extract_calls(code: code).each do |call|
+          descriptor = schema(mod: call[:mod], method: call[:method])
+          allowed = descriptor[:parameters][:properties].keys.map(&:to_s)
+          unknown = call[:keys].map(&:to_s) - allowed
+          next if unknown.empty?
+
+          return {
+            error: "unknown keyword: #{unknown.join(', ')}",
+            schema: descriptor,
+            method: descriptor[:name]
+          }
+        end
+        nil
+      rescue SyntaxError
+        nil
+      end
+
+      # List descriptors for every public PWN::Plugins class method (lazy per module).
+      public_class_method def self.descriptors(opts = {})
+        mods = Array(opts[:modules] || plugin_modules)
+        mods.flat_map do |mod|
+          public_methods_for(mod: mod).map { |name| schema(mod: mod, method: name) }
+        end
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # List host binaries this module expects to be installed.
+          #{self}.required_bins
+
+          # Build a JSON-schema descriptor for one public plugin method.
+          #{self}.schema(
+            mod: 'optional - PWN::Plugins::Name or short Name',
+            module: 'optional - alias for mod',
+            method: 'required - public class method name',
+            name: 'optional - alias for method'
+          )
+
+          # Validate literal kwargs on PWN::Plugins calls; nil means the payload may eval.
+          #{self}.guard_eval(
+            code: 'required - Ruby source that may call PWN::Plugins methods'
+          )
+
+          # List descriptors for every public PWN::Plugins class method (lazy per module).
+          #{self}.descriptors(
+            modules: 'optional - Array of PWN::Plugins constants to catalog'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+
+      private_class_method def self.plugin_const(opts = {})
+        raw = (opts[:mod] || opts[:module] || opts[:const]).to_s
+        raw = "PWN::Plugins::#{raw}" unless raw.include?('::')
+        raise 'ERROR: module is required' if raw.empty? || raw == 'PWN::Plugins::'
+        raise 'ERROR: only PWN::Plugins methods are catalogued' unless raw.start_with?('PWN::Plugins::')
+
+        raw
+      end
+
+      private_class_method def self.plugin_modules(opts = {})
+        _n = opts[:n]
+        PWN::Plugins.constants.sort.map { |name| "PWN::Plugins::#{name}" }.select do |mod|
+          Object.const_get(mod).is_a?(Module)
+        rescue StandardError
+          false
+        end
+      end
+
+      private_class_method def self.public_methods_for(opts = {})
+        klass = Object.const_get(opts[:mod].to_s)
+        klass.singleton_methods(false).map(&:to_s).reject { |name| %w[allocate new].include?(name) }.sort
+      rescue StandardError
+        []
+      end
+
+      private_class_method def self.classify_side_effect(opts = {})
+        blob = "#{opts[:mod]} #{opts[:method]} #{purpose_line(opts)}".downcase
+        return 'destructive' if blob.match?(/rm_rf|unlink|delete|kill|wipe|drop|destroy|format|truncate/)
+        return 'exploit' if blob.match?(/exploit|overflow|shellcode|ret2|rce|payload/)
+        return 'active_scan' if blob.match?(/scan|fuzz|brute|attack|nuclei|nmap|crawl|inject/)
+
+        'read_only'
+      end
+
+      private_class_method def self.property_schema(opts = {})
+        hint = opts[:hint].to_s.downcase
+        type = case hint
+               when /bool/
+                 'boolean'
+               when /array/
+                 'array'
+               when /int|number|float/
+                 'number'
+               else
+                 'string'
+               end
+        { type: type, description: opts[:hint].to_s }
+      end
+
+      private_class_method def self.allowed_keys(opts = {})
+        mod = opts[:mod].to_s
+        name = opts[:method].to_s
+        hints = {}
+        yard_options(text: comment_block(mod: mod, method: name)).each { |key, hint| hints[key] = hint }
+        help_options(mod: mod, method: name).each { |key, hint| hints[key] = hint }
+        body_keys(mod: mod, method: name).each { |key| hints[key] ||= key }
+        hints
+      end
+
+      private_class_method def self.yard_options(opts = {})
+        require 'yard'
+        doc = YARD::Docstring.new(opts[:text].to_s)
+        found = {}
+        (doc.tags('option') + doc.tags('param')).each do |tag|
+          key = (tag.pair&.name || tag.name).to_s.delete_prefix(':')
+          next if key.empty? || key == 'opts'
+
+          found[key] = [tag.types&.join(','), tag.text].compact.join(' ').strip
+        end
+        opts[:text].to_s.scan(/(\w+):\s*['"]((?:required|optional)[^'"]*)['"]/i) { |key, hint| found[key] = hint }
+        found
+      rescue StandardError
+        {}
+      end
+
+      private_class_method def self.comment_block(opts = {})
+        klass = Object.const_get(opts[:mod].to_s)
+        path, line = klass.method(opts[:method].to_sym).source_location
+        return '' unless path && line
+
+        lines = File.readlines(path)
+        buf = []
+        (line - 2).downto(0) do |idx|
+          text = lines[idx]
+          break unless text&.match?(/^\s*#/)
+
+          buf.unshift(text.sub(/^\s*#\s?/, ''))
+        end
+        buf.join
+      rescue StandardError
+        ''
+      end
+
+      private_class_method def self.help_options(opts = {})
+        klass = Object.const_get(opts[:mod].to_s)
+        path, = klass.method(:help).source_location
+        return {} unless path && File.file?(path)
+
+        text = File.read(path)
+        name = Regexp.escape(opts[:method].to_s)
+        chunk = text[/#\{self\}\.#{name}\((.*?)\)/m, 1]
+        return {} unless chunk
+
+        chunk.scan(/(\w+):\s*['"]((?:required|optional)[^'"]*)['"]/i).to_h
+      rescue StandardError
+        {}
+      end
+
+      private_class_method def self.body_keys(opts = {})
+        klass = Object.const_get(opts[:mod].to_s)
+        path, line = klass.method(opts[:method].to_sym).source_location
+        return [] unless path && line && File.file?(path)
+
+        lines = File.readlines(path)
+        indent = lines[line - 1][/^\s*/]
+        body = []
+        ((line - 1)...lines.length).each do |idx|
+          body << lines[idx]
+          break if idx > (line - 1) && lines[idx].match?(/^#{Regexp.escape(indent)}end\b/)
+        end
+        body.join.scan(/opts\[\s*:([A-Za-z_]\w*)\s*\]/).flatten.uniq
+      rescue StandardError
+        []
+      end
+
+      private_class_method def self.purpose_line(opts = {})
+        comment_block(opts).to_s.lines.map(&:strip).reject(&:empty?).first.to_s
+      end
+
+      private_class_method def self.extract_calls(opts = {})
+        sexp = Ripper.sexp(opts[:code].to_s)
+        return [] unless sexp
+
+        found = []
+        walk_sexp(node: sexp, found: found)
+        found.select { |row| row[:mod].to_s.start_with?('PWN::Plugins::') && !row[:keys].nil? }
+      end
+
+      private_class_method def self.walk_sexp(opts = {})
+        node = opts[:node]
+        found = opts[:found]
+        return unless node.is_a?(Array)
+
+        if node[0] == :method_add_arg && node[1].is_a?(Array) && node[1][0] == :call
+          rec = call_record(node: node[1], args: node[2])
+          found << rec if rec
+        elsif %i[call command_call].include?(node[0])
+          rec = call_record(node: node)
+          found << rec if rec
+        end
+        node.each { |child| walk_sexp(node: child, found: found) if child.is_a?(Array) }
+      end
+
+      private_class_method def self.call_record(opts = {})
+        node = opts[:node]
+        recv = node[1]
+        name_node = node[3]
+        args_node = opts[:args] || node[4]
+        ident = name_node.is_a?(Array) && name_node[0] == :@ident ? name_node[1] : nil
+        mod = const_path(node: recv)
+        return nil if ident.nil? || mod.nil?
+
+        keys = kwarg_keys(node: args_node)
+        return nil if keys.nil?
+
+        { mod: mod, method: ident, keys: keys }
+      end
+
+      private_class_method def self.const_path(opts = {})
+        node = opts[:node]
+        return nil unless node.is_a?(Array)
+
+        case node[0]
+        when :@const
+          node[1]
+        when :var_ref, :top_const_ref
+          const_path(node: node[1])
+        when :const_path_ref, :const_path_field
+          left = const_path(node: node[1])
+          right = const_path(node: node[2])
+          [left, right].compact.join('::')
+        end
+      end
+
+      private_class_method def self.kwarg_keys(opts = {})
+        node = opts[:node]
+        return [] if node.nil?
+        return nil unless node.is_a?(Array)
+
+        return kwarg_keys(node: node[1]) if node[0] == :arg_paren
+
+        hash = find_assoc_hash(node: node)
+        return nil if hash.nil? && ident_arg?(node: node)
+        return [] if hash.nil?
+
+        hash.each_with_object([]) do |assoc, keys|
+          next unless assoc.is_a?(Array) && assoc[0] == :assoc_new
+
+          label = assoc[1]
+          keys << label[1].to_s.delete_suffix(':') if label.is_a?(Array) && label[0] == :@label
+        end
+      end
+
+      private_class_method def self.find_assoc_hash(opts = {})
+        node = opts[:node]
+        return nil unless node.is_a?(Array)
+        return node[1] if node[0] == :bare_assoc_hash
+
+        node.each do |child|
+          next unless child.is_a?(Array)
+
+          found = find_assoc_hash(node: child)
+          return found if found
+        end
+        nil
+      end
+
+      private_class_method def self.ident_arg?(opts = {})
+        node = opts[:node]
+        return false unless node.is_a?(Array)
+
+        node.flatten.include?(:@ident) && !node.flatten.include?(:@label)
+      end
+    end
+  end
+end

data/lib/pwn/plugins/nmap_it.rb

@@ -5,6 +5,8 @@ require 'nmap/xml'
 require 'open3'
 require 'securerandom'
 require 'tmpdir'
+require 'rexml/document'
+require 'time'
 
 module PWN
   module Plugins
@@ -118,30 +120,46 @@ module PWN
       end
 
       public_class_method def self.to_findings(opts = {})
-        xml_file = opts[:xml_file].to_s
+        inventory(opts)[:ports]
+      end
+
+      public_class_method def self.inventory(opts = {})
+        xml_file = (opts[:xml_file] || opts[:xml]).to_s
         raise 'ERROR: xml_file is required' if xml_file.empty?
-        return [] unless File.file?(xml_file)
-
-        rows = []
-        parse_xml_results(xml_file: xml_file) do |xml|
-          xml.each_host do |host|
-            host.each_port do |port|
-              scripts = {}
-              port.scripts.each { |name, output| scripts[name.to_s] = output.to_s } if port.respond_to?(:scripts) && port.scripts
-              rows << {
-                host: host.ip.to_s,
-                port: port.number,
-                proto: port.protocol.to_s,
-                service: (port.service.name if port.respond_to?(:service) && port.service),
-                version: (port.service.version if port.respond_to?(:service) && port.service.respond_to?(:version)),
-                scripts: scripts,
-                template_id: nil,
-                severity: 'info'
-              }
-            end
+        return { hosts: [], ports: [] } unless File.file?(xml_file)
+
+        doc = REXML::Document.new(File.read(xml_file))
+        hosts = []
+        ports = []
+        doc.elements.each('nmaprun/host') do |node|
+          ip = node.elements['address']&.attributes&.[]('addr').to_s
+          next if ip.empty?
+
+          host_scripts = script_map(node: node.elements['hostscript'])
+          host_ports = []
+          node.elements.each('ports/port') do |port_node|
+            number = port_node.attributes['portid'].to_i
+            proto = port_node.attributes['protocol'].to_s
+            state = port_node.elements['state']&.attributes&.[]('state').to_s
+            svc = port_node.elements['service']
+            scripts = script_map(node: port_node)
+            row = {
+              host: ip,
+              port: number,
+              proto: proto,
+              state: state,
+              service: svc&.attributes&.[]('name'),
+              version: svc&.attributes&.[]('version') || svc&.attributes&.[]('product'),
+              scripts: scripts,
+              template_id: nil,
+              severity: 'info'
+            }
+            host_ports << row
+            ports << row
           end
+          hosts << { host: ip, ports: host_ports, services: host_ports.map { |row| row[:service] }.compact.uniq, scripts: host_scripts }
         end
-        rows
+        { hosts: hosts, ports: ports, xml: xml_file }
       end
 
       public_class_method def self.scan(opts = {})
@@ -154,10 +172,41 @@ module PWN
           xml = File.join(Dir.tmpdir, "pwn-nmap-#{Process.pid}-#{SecureRandom.hex(4)}.xml") if xml.empty?
           port_scan(opts.merge(xml: xml, targets: targets))
         end
-        rows = to_findings(xml_file: xml)
-        PWN::Engagement.merge_scan(results: rows, override: opts[:override], engagement: opts[:engagement] || opts[:name]) if defined?(PWN::Engagement) && opts[:engagement] != false
-        grouped = rows.group_by { |row| row[:host] }.map { |host, ports| { host: host, ports: ports, services: ports.map { |p| p[:service] }.compact } }
-        { hosts: grouped, ports: rows, xml: xml }
+        inv = inventory(xml_file: xml)
+        rows = inv[:ports]
+        eng = opts[:engagement] || opts[:name]
+        if defined?(PWN::Engagement) && opts[:engagement] != false
+          PWN::Engagement.merge_scan(results: rows, override: opts[:override], engagement: eng)
+          PWN::Engagement.record_scan(hosts: inv[:hosts], ports: rows, xml: xml, at: opts[:at], engagement: eng, kind: 'nmap')
+        end
+        grouped = inv[:hosts]
+        {
+          hosts: grouped,
+          ports: rows,
+          xml: xml,
+          diff: changes(opts.merge(engagement: eng, latest: inv[:hosts]))
+        }
+      end
+
+      public_class_method def self.changes(opts = {})
+        eng = opts[:engagement] || opts[:name]
+        snaps = defined?(PWN::Engagement) ? PWN::Engagement.scans(engagement: eng, name: eng) : []
+        latest_hosts = opts[:latest]
+        if latest_hosts.nil?
+          return { since: opts[:since], added_hosts: [], removed_hosts: [], added_ports: [], removed_ports: [], changed_scripts: [], first: true } if snaps.empty?
+
+          latest_hosts = Array(snaps.last[:hosts])
+        end
+        cutoff = parse_since(since: opts[:since])
+        pool = Array(snaps[0..-2])
+        previous = pool.reverse.find do |snap|
+          at = Time.parse(snap[:at].to_s).utc
+          cutoff.nil? || at <= cutoff
+        end
+        previous ||= snaps[-2]
+        return { since: opts[:since], previous_at: nil, added_hosts: [], removed_hosts: [], added_ports: [], removed_ports: [], changed_scripts: [], first: true } unless previous
+
+        diff_inventories(previous: Array(previous[:hosts]), current: latest_hosts).merge(since: opts[:since], previous_at: previous[:at], current_at: snaps.last && snaps.last[:at])
       end
 
       # Author(s):: 0day Inc. <support@0dayinc.com>
@@ -207,7 +256,22 @@ module PWN
             engagement: 'optional - false skips host-state merge',
             override: 'optional - true records out-of-scope hosts',
             target: 'optional - alias for targets',
-            name: 'optional - engagement name for host-state merge'
+            name: 'optional - engagement name for host-state merge',
+            at: 'optional - Time or ISO8601 timestamp stored on the scan snapshot'
+          )
+
+          # Parse nmap XML into hosts, ports, and script output hashes.
+          #{self}.inventory(
+            xml_file: 'required - path to nmap XML output unless xml is set',
+            xml: 'optional - alias for xml_file'
+          )
+
+          # Diff the latest engagement snapshot against yesterday or a prior scan.
+          #{self}.changes(
+            since: 'optional - yesterday, last-scan, ISO8601, or Time (defaults to previous snapshot)',
+            engagement: 'optional - engagement identifier',
+            name: 'optional - alias for engagement',
+            latest: 'optional - inventory host array to treat as current'
           )
 
           # Print the AUTHOR(S) string for this module.
@@ -215,6 +279,73 @@ module PWN
         "
         constants.sort
       end
+
+      private_class_method def self.script_map(opts = {})
+        node = opts[:node]
+        return {} unless node
+
+        map = {}
+        node.elements.each('script') do |script|
+          map[script.attributes['id'].to_s] = script.attributes['output'].to_s
+        end
+        map
+      end
+
+      private_class_method def self.parse_since(opts = {})
+        token = opts[:since]
+        return nil if token.nil? || token.to_s.empty? || token.to_s.match?(/last.?scan/i)
+        return token.getutc if token.is_a?(Time)
+
+        return Time.now.utc - 86_400 if token.to_s.match?(/yesterday/i)
+
+        Time.parse(token.to_s).utc
+      rescue ArgumentError
+        Time.now.utc - 86_400
+      end
+
+      private_class_method def self.diff_inventories(opts = {})
+        prev = index_inventory(hosts: opts[:previous])
+        curr = index_inventory(hosts: opts[:current])
+        added_ports = (curr[:ports].keys - prev[:ports].keys).map { |key| curr[:ports][key] }
+        removed_ports = (prev[:ports].keys - curr[:ports].keys).map { |key| prev[:ports][key] }
+        changed_scripts = []
+        curr[:scripts].each do |key, now|
+          was = prev[:scripts][key]
+          next if was == now
+
+          changed_scripts << { host: key[0], port: key[1], name: key[2], before: was, after: now }
+        end
+        {
+          added_hosts: (curr[:hosts] - prev[:hosts]).to_a,
+          removed_hosts: (prev[:hosts] - curr[:hosts]).to_a,
+          added_ports: added_ports,
+          removed_ports: removed_ports,
+          changed_scripts: changed_scripts
+        }
+      end
+
+      private_class_method def self.index_inventory(opts = {})
+        hosts = []
+        ports = {}
+        scripts = {}
+        Array(opts[:hosts]).each do |host|
+          host = host.transform_keys(&:to_sym) if host.respond_to?(:transform_keys)
+          ip = host[:host].to_s
+          hosts << ip
+          Array(host[:scripts]).each do |name, output|
+            scripts[[ip, 0, name.to_s]] = output.to_s
+          end
+          Array(host[:ports]).each do |port|
+            port = port.transform_keys(&:to_sym) if port.respond_to?(:transform_keys)
+            key = [ip, port[:port], port[:proto].to_s]
+            ports[key] = { host: ip, port: port[:port], proto: port[:proto], service: port[:service], version: port[:version] }
+            Array(port[:scripts]).each do |name, output|
+              scripts[[ip, port[:port], name.to_s]] = output.to_s
+            end
+          end
+        end
+        { hosts: hosts, ports: ports, scripts: scripts }
+      end
     end
   end
 end