pwn 0.5.708 → 0.5.709

data/lib/pwn/plugins/jobs.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'securerandom'
+require 'open3'
+
+module PWN
+  module Plugins
+    # Background jobs that survive a pwn-ai turn (scans, fuzz campaigns).
+    module Jobs
+      JOBS_DIR = File.join(Dir.home, '.pwn', 'jobs')
+
+      public_class_method def self.required_bins
+        []
+      end
+
+      public_class_method def self.start(opts = {})
+        cmd = opts[:command] || opts[:cmd]
+        raise 'ERROR: command is required' if cmd.to_s.empty?
+
+        FileUtils.mkdir_p(JOBS_DIR)
+        id = SecureRandom.hex(6)
+        log = File.join(JOBS_DIR, "#{id}.log")
+        meta = File.join(JOBS_DIR, "#{id}.json")
+        pid = spawn(cmd.to_s, %i[out err] => [log, 'a'])
+        Process.detach(pid)
+        row = {
+          id: id,
+          pid: pid,
+          command: cmd.to_s,
+          log: log,
+          session_id: opts[:session_id],
+          started_at: Time.now.utc.iso8601
+        }
+        File.write(meta, JSON.generate(row))
+        row
+      end
+
+      public_class_method def self.status(opts = {})
+        row = load_job(opts)
+        alive = begin
+          Process.kill(0, row[:pid].to_i)
+          true
+        rescue Errno::ESRCH, Errno::EPERM
+          false
+        end
+        row.merge(alive: alive)
+      end
+
+      public_class_method def self.tail(opts = {})
+        row = load_job(opts)
+        n = (opts[:lines] || 40).to_i
+        return '' unless File.file?(row[:log])
+
+        File.readlines(row[:log]).last(n).join
+      end
+
+      public_class_method def self.stop(opts = {})
+        row = load_job(opts)
+        Process.kill('TERM', row[:pid].to_i)
+        true
+      rescue Errno::ESRCH
+        false
+      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
+
+          # Run start and return its result
+          #{self}.start(
+            command: 'required - command value consumed by #start (defaults to opts[:cmd])',
+            cmd: 'required - command string to run',
+            session_id: 'optional - session id value consumed by #start'
+          )
+
+          # Run status and return its result
+          #{self}.status
+
+          # Run tail and return its result
+          #{self}.tail(
+            lines: 'optional - lines value consumed by #tail'
+          )
+
+          # Run stop and return its result
+          #{self}.stop
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+
+      private_class_method def self.load_job(opts = {})
+        id = opts[:id].to_s
+        path = File.join(JOBS_DIR, "#{id}.json")
+        raise "ERROR: unknown job #{id}" unless File.file?(path)
+
+        JSON.parse(File.read(path), symbolize_names: true)
+      end
+    end
+  end
+end

data/lib/pwn/plugins/json_pathify.rb

@@ -33,13 +33,17 @@ module PWN
       # Display Usage for this Module
 
       public_class_method def self.help
-        puts %{USAGE:
-          json_path_arr = #{self}.search_key(
-            json_data_struct: "required JSON data structure",
-            key: "required key to find in JSON data structure. returns key values"
+        puts "USAGE:
+          # Run search key and return its result
+          #{self}.search_key(
+            json_data_struct: 'required - required JSON data structure',
+            key: 'required - required key to find in JSON data structure. returns key values'
           )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
-        }
+        "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/log.rb

@@ -751,23 +751,123 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          logger = #{self}.append(
-            level: 'required - log verbosity :debug|:error|:fatal|:info|:learning|:unknown|:warn',
-            msg: 'required - message to log',
-            which_self: 'required - pass in self object from module calling #{self}'
+          # Run append and return its result
+          #{self}.append(
+            level: 'required - level value consumed by #append',
+            msg: 'optional - msg value consumed by #append',
+            which_self: 'optional - which self value consumed by #append'
           )
 
-          path = #{self}.start_debug(
-            tee: $stdout,
-            session_id: 'optional - pwn-ai session id'
+          # Run debug enabled and return its result
+          #{self}.debug_enabled?
+
+          # Run debug log path and return its result
+          #{self}.debug_log_path
+
+          # Open a debug session. Request traces go to
+          #{self}.start_debug(
+            trace: 'optional - trace value consumed by #start_debug',
+            path: 'required - filesystem path to read or write',
+            tee: 'optional - tee value consumed by #start_debug',
+            session_id: 'optional - session id value consumed by #start_debug',
+            step_io: 'optional - step io value consumed by #start_debug',
+            prefixes: 'optional - prefixes value consumed by #start_debug'
+          )
+
+          # Run trace enabled and return its result
+          #{self}.trace_enabled?
+
+          # Run next request log and return its result
+          #{self}.next_request_log!(
+            force: 'optional - force value consumed by #next_request_log!',
+            session_id: 'optional - session id value consumed by #next_request_log!'
+          )
+
+          # Run finish request log and return its result
+          #{self}.finish_request_log!(
+            force: 'optional - force value consumed by #finish_request_log!',
+            iter: 'optional - iter value consumed by #finish_request_log!',
+            tools_called: 'optional - tools called value consumed by #finish_request_log!',
+            engine_s: 'optional - engine s value consumed by #finish_request_log!',
+            final_chars: 'optional - final chars value consumed by #finish_request_log!',
+            nested: 'optional - nested value consumed by #finish_request_log!'
+          )
+
+          # Run stop debug and return its result
+          #{self}.stop_debug(
+            reason: 'required - reason value consumed by #stop_debug'
           )
-          #{self}.next_request_log!(session_id: 'optional')
-          #{self}.progress(msg: 'stage', which_self: self)
-          #{self}.finish_request_log!(iter: 1, tools_called: 0, engine_s: 0.2, final_chars: 12)
-          #{self}.stop_debug
-          # start_debug(trace: true) enables TracePoint + ENTER after each Loop step
-          # (toggle-trace). Stored on Pry.config.pwn_ai_trace, not Env.
+
+          # Run capture stderr and return its result
+          #{self}.capture_stderr!(
+            text: 'required - text value consumed by #capture_stderr!'
+          )
+
+          # Spinner frames stay on the TTY; never persist them in the RN log
+          #{self}.spinner_frame?(
+            text: 'optional - text value consumed by #spinner_frame?'
+          )
+
+          # Run raw stderr and return its result
+          #{self}.raw_stderr
+
+          # Run quiet tui and return its result
+          #{self}.quiet_tui!(
+            skip: 'optional - skip value consumed by #quiet_tui!'
+          )
+
+          # Run loud tui and return its result
+          #{self}.loud_tui!(
+            skip: 'optional - skip value consumed by #loud_tui!'
+          )
+
+          # One progress line to the debug file and the TUI tee (same payload)
+          #{self}.progress(
+            msg: 'optional - msg value consumed by #progress',
+            which_self: 'optional - which self value consumed by #progress (defaults to self)',
+            keep_newlines: 'optional - keep newlines value consumed by #progress',
+            cap: 'optional - cap value consumed by #progress',
+            tee: 'optional - tee value consumed by #progress'
+          )
+
+          # Run note interrupt and return its result
+          #{self}.note_interrupt!(
+            where: 'required - where value consumed by #note_interrupt!',
+            which_self: 'optional - which self value consumed by #note_interrupt! (defaults to self)'
+          )
+
+          # Run note exception and return its result
+          #{self}.note_exception!(
+            error: 'optional - error value consumed by #note_exception!',
+            where: 'required - where value consumed by #note_exception!',
+            which_self: 'optional - which self value consumed by #note_exception! (defaults to self)'
+          )
+
+          # Clone operator-visible TUI rows into the open RN request log (no ANSI)
+          #{self}.mirror_tui!(
+            msg: 'optional - msg value consumed by #mirror_tui!'
+          )
+
+          # Run start trace and return its result
+          #{self}.start_trace!(
+            prefixes: 'optional - prefixes value consumed by #start_trace!'
+          )
+
+          # Run stop trace and return its result
+          #{self}.stop_trace!(
+            skip: 'optional - skip value consumed by #stop_trace!'
+          )
+
+          # Run wait trace step and return its result
+          #{self}.wait_trace_step!(
+            nested: 'optional - nested value consumed by #wait_trace_step!',
+            label: 'required - label value consumed by #wait_trace_step!'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/mail_agent.rb

@@ -242,102 +242,110 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # attachment_name1.doc: attachment file path 1,
           #{self}.office365(
-            from: 'required',
-            to: 'required',
-            cc: 'optional',
-            bcc: 'optional',
-            reply_to: 'optional',
-            subject: 'optional',
-            html_body: 'optional',
-            txt_body: 'optional alternative to :html_body',
-            attachments_hash: {
-              'attachment_name1.doc': 'attachment file path 1',
-              'attachment_name2.xls': 'attachment file path 2'
-            },
-            username: 'required domain\\username',
-            password: 'optional (but will be prompted if not submitted)',
-            debug: true|false
+            from: 'required - sender account or address to bind as operator',
+            to: 'required - to value consumed by #office365',
+            cc: 'optional - cc value consumed by #office365',
+            bcc: 'optional - bcc value consumed by #office365',
+            reply_to: 'optional - reply to value consumed by #office365',
+            subject: 'optional - subject value consumed by #office365',
+            html_body: 'optional - html body value consumed by #office365',
+            txt_body: 'optional - optional alternative to :html_body',
+            attachments_hash: 'optional - attachments hash value consumed by #office365',
+            username: 'required - required username',
+            password: 'optional - optional (but will be prompted if not submitted)',
+            debug: 'optional - debug value consumed by #office365',
+            address: 'optional - address value consumed by #office365',
+            port: 'optional - TCP/UDP port number',
+            tls_auto: 'optional - tls auto value consumed by #office365',
+            authentication: 'optional - authentication value consumed by #office365'
           )
 
+          # attachment_name1.doc: attachment file path 1,
           #{self}.gmail(
-            from: 'required',
-            to: 'required',
-            cc: 'optional',
-            bcc: 'optional',
-            reply_to: 'optional',
-            subject: 'optional',
-            html_body: 'optional',
-            txt_body: 'optional alternative to :html_body',
-            attachments_hash: {
-              'attachment_name1.doc': 'attachment file path 1',
-              'attachment_name2.xls': 'attachment file path 2'
-            },
-            username: 'required',
-            password: 'optional (but will be prompted if not submitted)'
-            debug: true|false
+            from: 'required - sender account or address to bind as operator',
+            to: 'required - to value consumed by #gmail',
+            cc: 'optional - cc value consumed by #gmail',
+            bcc: 'optional - bcc value consumed by #gmail',
+            reply_to: 'optional - reply to value consumed by #gmail',
+            subject: 'optional - subject value consumed by #gmail',
+            html_body: 'optional - html body value consumed by #gmail',
+            txt_body: 'optional - optional alternative to :html_body',
+            attachments_hash: 'optional - attachments hash value consumed by #gmail',
+            username: 'required - username value consumed by #gmail',
+            password: 'optional - optional (but will be prompted if not submitted)',
+            debug: 'optional - debug value consumed by #gmail',
+            address: 'optional - address value consumed by #gmail',
+            port: 'optional - TCP/UDP port number',
+            tls_auto: 'optional - tls auto value consumed by #gmail',
+            authentication: 'optional - authentication value consumed by #gmail'
           )
 
+          # attachment_name1.doc: attachment file path 1,
           #{self}.hotmail_n_live(
-            from: 'required',
-            to: 'required',
-            cc: 'optional',
-            bcc: 'optional',
-            reply_to: 'optional',
-            subject: 'optional',
-            html_body: 'optional',
-            txt_body: 'optional alternative to :html_body',
-            attachments_hash: {
-              'attachment_name1.doc': 'attachment file path 1',
-              'attachment_name2.xls': 'attachment file path 2'
-            },
-            username: 'required',
-            password: 'optional (but will be prompted if not submitted)'
-            debug: true|false
+            from: 'required - sender account or address to bind as operator',
+            to: 'required - to value consumed by #hotmail_n_live',
+            cc: 'optional - cc value consumed by #hotmail_n_live',
+            bcc: 'optional - bcc value consumed by #hotmail_n_live',
+            reply_to: 'optional - reply to value consumed by #hotmail_n_live',
+            subject: 'optional - subject value consumed by #hotmail_n_live',
+            html_body: 'optional - html body value consumed by #hotmail_n_live',
+            txt_body: 'optional - optional alternative to :html_body',
+            attachments_hash: 'optional - attachments hash value consumed by #hotmail_n_live',
+            username: 'required - username value consumed by #hotmail_n_live',
+            password: 'optional - optional (but will be prompted if not submitted)',
+            debug: 'optional - debug value consumed by #hotmail_n_live',
+            address: 'optional - address value consumed by #hotmail_n_live',
+            port: 'optional - TCP/UDP port number',
+            tls_auto: 'optional - tls auto value consumed by #hotmail_n_live',
+            authentication: 'optional - authentication value consumed by #hotmail_n_live'
           )
 
+          # attachment_name1.doc: attachment file path 1,
           #{self}.yahoo(
-            from: 'required',
-            to: 'required',
-            cc: 'optional',
-            bcc: 'optional',
-            reply_to: 'optional',
-            subject: 'optional',
-            html_body: 'optional',
-            txt_body: 'optional alternative to :html_body',
-            attachments_hash: {
-              'attachment_name1.doc': 'attachment file path 1',
-              'attachment_name2.xls': 'attachment file path 2'
-            },
-            username: 'required',
-            password: 'optional (but will be prompted if not submitted)'
-            debug: true|false
+            from: 'required - sender account or address to bind as operator',
+            to: 'required - to value consumed by #yahoo',
+            cc: 'optional - cc value consumed by #yahoo',
+            bcc: 'optional - bcc value consumed by #yahoo',
+            reply_to: 'optional - reply to value consumed by #yahoo',
+            subject: 'optional - subject value consumed by #yahoo',
+            html_body: 'optional - html body value consumed by #yahoo',
+            txt_body: 'optional - optional alternative to :html_body',
+            attachments_hash: 'optional - attachments hash value consumed by #yahoo',
+            username: 'required - username value consumed by #yahoo',
+            password: 'optional - optional (but will be prompted if not submitted)',
+            debug: 'optional - debug value consumed by #yahoo',
+            address: 'optional - address value consumed by #yahoo',
+            port: 'optional - TCP/UDP port number',
+            tls_auto: 'optional - tls auto value consumed by #yahoo',
+            authentication: 'optional - authentication value consumed by #yahoo'
           )
 
+          # attachment_name1.doc: attachment file path 1,
           #{self}.manual(
-            from: 'required',
-            to: 'required',
-            cc: 'optional',
-            bcc: 'optional',
-            reply_to: 'optional',
-            subject: 'optional',
-            html_body: 'optional',
-            txt_body: 'optional alternative to :html_body',
-            attachments_hash: {
-              'attachment_name1.doc': 'attachment file path 1',
-              'attachment_name2.xls': 'attachment file path 2'
-            },
-            address: 'smtp server ip or domain',
-            port: 'smtp port',
-            tls_auto: true|false,
-            authentication: 'optional defaults to :plain - available :login, :plain, or :cram_md5',
-            username: 'optional',
-            password: 'optional',
-            debug: true|false
+            from: 'required - sender account or address to bind as operator',
+            to: 'required - to value consumed by #manual',
+            cc: 'optional - cc value consumed by #manual',
+            bcc: 'optional - bcc value consumed by #manual',
+            reply_to: 'optional - reply to value consumed by #manual',
+            subject: 'optional - subject value consumed by #manual',
+            html_body: 'optional - html body value consumed by #manual',
+            txt_body: 'optional - optional alternative to :html_body',
+            attachments_hash: 'optional - attachments hash value consumed by #manual',
+            address: 'optional - smtp server ip or domain',
+            port: 'optional - smtp port',
+            tls_auto: 'optional - tls auto value consumed by #manual',
+            username: 'optional - username value consumed by #manual',
+            password: 'optional - password value consumed by #manual',
+            debug: 'optional - debug value consumed by #manual',
+            authentication: 'optional - authentication value consumed by #manual'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/metasploit.rb

@@ -130,21 +130,26 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          console_obj = #{self}.connect(
-            yaml_conf: 'optional -  path to userland yaml (defaults to $PWN_ROOT/etc/userland/$PWN_PROVIDER/metasploit/vagrant.yaml)'
+          # Run connect and return its result
+          #{self}.connect(
+            yaml_conf: 'optional - path to userland yaml (defaults to /pwn/etc/userland/PWN_PROVIDEDR/metasploit/vagrant.yaml)'
           )
 
-          console_obj = #{self}.console_exec(
-            console_obj: 'required - msfrpcd_conn object returned from #connect method',
+          # Run console exec and return its result
+          #{self}.console_exec(
+            console_obj: 'required - console_obj object returned from #connect method',
             cmd: 'required - msfconsole command string or array of strings'
           )
 
-          console_obj = #{self}.disconnect(
-            console_obj: 'required - msfrpcd_conn object returned from #connect method'
+          # Run disconnect and return its result
+          #{self}.disconnect(
+            console_obj: 'required - console_obj returned from #console_exec method to terminate'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/monkey_patch.rb

@@ -172,10 +172,13 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # Run pry and return its result
           #{self}.pry
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/msr206.rb

@@ -1193,64 +1193,78 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          msr206_obj = #{self}.connect(
-            block_dev: 'optional serial block device path (defaults to /dev/ttyUSB0)',
-            baud: 'optional (defaults to 19200)',
-            data_bits: 'optional (defaults to 8)',
-            stop_bits: 'optional (defaults to 1)',
-            parity: 'optional - :even||:odd|:none (defaults to :none)',
-            flow_control: 'optional - :none||:hard||:soft (defaults to :soft)'
+          # Run connect and return its result
+          #{self}.connect(
+            block_dev: 'optional - serial block device path (defaults to /dev/ttyUSB0)',
+            baud: 'optional - (defaults to 19200)',
+            data_bits: 'optional - (defaults to 8)',
+            stop_bits: 'optional - (defaults to 1)',
+            parity: 'optional - :even|:mark|:odd|:space|:none (defaults to :none),',
+            flow_control: 'optional - :none|:hard|:soft (defaults to :soft)'
           )
 
+          # Run list cmds and return its result
+          #{self}.list_cmds
+
+          # Run set protocol and return its result
           #{self}.set_protocol(
             msr206_obj: 'required - msr206_obj returned from #connect method',
             protocol: 'optional - :usi0 or :usi1 (defaults to :usi0)'
           )
 
-          cmds = #{self}.list_cmds
-
-          parsed_cmd_resp_arr = #{self}.exec(
-            msr206_obj: 'required msr206_obj returned from #connect method',
+          # Run exec and return its result
+          #{self}.exec(
+            msr206_obj: 'required - msr206_obj returned from #connect method',
             cmd: 'required - cmd returned from #list_cmds method',
-            params: 'optional - parameters for specific command'
+            params: 'optional - parameters for specific command returned from #list_params method'
           )
 
-          track_data = #{self}.read_card(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run read card and return its result
+          #{self}.read_card(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
-          track_data = #{self}.backup_card(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run backup card and return its result
+          #{self}.backup_card(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
-          track_data = #{self}.write_card(
-            msr206_obj: 'required msr206_obj returned from #connect method',
+          # Run write card and return its result
+          #{self}.write_card(
+            msr206_obj: 'required - msr206_obj returned from #connect method',
             encoding: 'required - :iso || :iso_alt || :raw',
-            track_data: 'required - track data to write'
+            track_data: 'required - track data to write (see #backup_card for structure)'
           )
 
-          track_data = #{self}.clone_card(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run clone card and return its result
+          #{self}.clone_card(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
-          track_data = #{self}.load_card_from_file(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run load card from file and return its result
+          #{self}.load_card_from_file(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
-          track_data = #{self}.update_card(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run update card and return its result
+          #{self}.update_card(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
-          config = #{self}.get_config(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+          # Run get config and return its result
+          #{self}.get_config(
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
+          # Run disconnect and return its result
           #{self}.disconnect(
-            msr206_obj: 'required msr206_obj returned from #connect method'
+            msr206_obj: 'required - msr206_obj returned from #connect method'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end