pwn 0.5.708 → 0.5.709

data/lib/pwn/plugins/file_fu.rb

@@ -116,27 +116,30 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # Run recurse in dir and return its result
           #{self}.recurse_in_dir(
-            dir_path: 'optional path to dir defaults to .',
-            include_extensions: 'optional - array of file extensions to search for in scan (e.g. ['.js', '.php'])',
-            exclude_extensions: 'optional - array of file extensions to exclude from scan (e.g. ['.log', '.txt', '.spec'])'
-          ) do |entry|
-            puts entry
-          end
+            dir_path: 'optional - optional path to dir defaults to .',
+            include_extensions: 'optional - array of file extensions to search for in scan (e.g. [.js, .php])',
+            exclude_extensions: 'optional - array of file extensions to exclude from scan (e.g. [.log, .txt, .spec])'
+          )
 
+          # Run untar gz file and return its result
           #{self}.untar_gz_file(
             tar_gz_file: 'required - path to .tar.gz file',
             destination: 'required - destination folder to save extracted contents'
           )
 
+          # Run shift file up and return its result
           #{self}.shift_file_up(
             path: 'required - path to file to shift up',
-            bytes: 'required - number of bytes to shift up',
-            buffer_size: 'optional - buffer size to use when shifting file up (default: 256 * 1024 / i.e 256KB)'
+            bytes: 'required - number of bytes to shift up (remove from beginning)',
+            buffer_size: 'optional - buffer size to use when shifting (default: 256KB)'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/frida.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module PWN
+  module Plugins
+    # Frida attach/spawn + script injection.
+    module Frida
+      public_class_method def self.required_bins
+        %w[frida]
+      end
+
+      public_class_method def self.ps(opts = {})
+        PWN::Plugins::Doctor.require_bin!(name: 'frida')
+        stdout, stderr, status = Open3.capture3('frida-ps', *Array(opts[:extra]))
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus }
+      end
+
+      public_class_method def self.attach(opts = {})
+        PWN::Plugins::Doctor.require_bin!(name: 'frida')
+        target = opts[:target] || opts[:name]
+        script = opts[:script].to_s
+        raise 'ERROR: target is required' if target.to_s.empty?
+
+        cmd = ['frida', '-n', target.to_s]
+        cmd += ['-l', opts[:script_path].to_s] if opts[:script_path]
+        cmd += ['-e', script] unless script.empty?
+        stdout, stderr, status = Open3.capture3(*cmd)
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus }
+      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 ps and return its result
+          #{self}.ps(
+            extra: 'optional - Array extra value consumed by #ps'
+          )
+
+          # Run attach and return its result
+          #{self}.attach(
+            target: 'required - hostname, IP, or CIDR to scan (defaults to opts[:name])',
+            name: 'optional - binary or identifier name',
+            script: 'required - script value consumed by #attach',
+            script_path: 'optional - script path value consumed by #attach'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/fuzz.rb

@@ -183,13 +183,14 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          socket_fuzz_results_arr = #{self}.socket(
-            target: 'required = target host or ip',
-            port: 'required => target port',
-            protocol: 'optional => :tcp || :udp (defaults to tcp)',
+          # Run socket and return its result
+          #{self}.socket(
+            target: 'required - target host or ip',
+            port: 'required - target port',
+            protocol: 'optional - :tcp || :udp (defaults to tcp)',
             tls: 'optional - boolean connect to target socket using TLS (defaults to false)',
-            fuzz_delimeter: \"optional - fuzz delimeter used in request to specify where payloads should reside (defaults to \u2665)\",
-            request: \"required - String object of socket request w/ \u2665 as fuzz delimeter (e.g. '\"GET /\u2665\u2665 HTTP/1.1\\r\\nHost: \u2665127.0.0.1\u2665\\r\\n\\r\\n\"')\",
+            fuzz_delimeter: 'optional - fuzz delimeter used in request to specify where payloads should reside (defaults to \\u2665)',
+            request: 'required - String object of socket request w/ \\u001A as fuzz delimeter (e.g. GET /\\u001A\\u001A HTTP/1.1\\r\\nHost: \\u001A127..0.0.1\\u001A\\r\\n\\r\\n)',
             payload: 'required - payload string',
             response_timeout: 'optional - float (defaults to 0.9)',
             request_rate_limit: 'optional - float (defaults to 0.3)',
@@ -198,8 +199,10 @@ module PWN
             char_encoding: 'optional - character encoding returned by PWN::Plugins::Char.list_encoders (defaults to UTF-8)'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/gdb.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module PWN
+  module Plugins
+    # gdb/MI batch driver: run-to-crash, registers, mitigations, core dumps.
+    module GDB
+      public_class_method def self.required_bins
+        %w[gdb]
+      end
+
+      public_class_method def self.batch(opts = {})
+        PWN::Plugins::Doctor.require_bin!(name: 'gdb')
+        binary = opts[:binary].to_s
+        cmds = Array(opts[:commands] || opts[:cmds])
+        args = Array(opts[:args])
+        mi = ['gdb', '--batch', '--quiet']
+        mi += ['-ex', 'set pagination off']
+        cmds.each { |c| mi += ['-ex', c.to_s] }
+        mi << '--args' if !binary.empty? || args.any?
+        mi << binary unless binary.empty?
+        mi.concat(args.map(&:to_s))
+        stdout, stderr, status = Open3.capture3(*mi)
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus }
+      end
+
+      public_class_method def self.run_to_crash(opts = {})
+        cmds = ['run', 'bt', 'info registers']
+        batch(opts.merge(commands: cmds))
+      end
+
+      public_class_method def self.registers(opts = {})
+        batch(opts.merge(commands: ['info registers']))
+      end
+
+      public_class_method def self.mitigations(opts = {})
+        batch(opts.merge(commands: ['checksec']))
+      rescue StandardError
+        path = opts[:binary].to_s
+        return { error: 'gdb missing' } unless PWN::Plugins::Doctor.bin?(name: 'gdb')
+
+        { hint: 'pwndbg/gef checksec not loaded', binary: path }
+      end
+
+      public_class_method def self.core(opts = {})
+        core = opts[:core].to_s
+        binary = opts[:binary].to_s
+        raise 'ERROR: core is required' if core.empty?
+
+        batch(opts.merge(commands: ['bt', 'info registers'], binary: binary, args: []))
+      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 batch and return its result
+          #{self}.batch(
+            binary: 'required - binary value consumed by #batch',
+            commands: 'optional - commands value consumed by #batch',
+            cmds: 'optional - cmds value consumed by #batch',
+            args: 'required - Array args value consumed by #batch'
+          )
+
+          # Run run to crash and return its result
+          #{self}.run_to_crash
+
+          # Run registers and return its result
+          #{self}.registers
+
+          # Run mitigations and return its result
+          #{self}.mitigations(
+            binary: 'optional - binary value consumed by #mitigations'
+          )
+
+          # Run core and return its result
+          #{self}.core(
+            core: 'required - core value consumed by #core',
+            binary: 'optional - binary value consumed by #core'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/git.rb

@@ -132,27 +132,32 @@ module PWN
       # Display Usage for this Module
 
       public_class_method def self.help
-        puts %{USAGE:
-          git_html_resp = #{self}.gen_html_diff(
-            repo: 'required git repo name',
-            branch: 'required git repo branch (e.g. master, develop, etc)',
-            since: 'optional date, otherwise default to last pull'
+        puts "USAGE:
+          # Run gen html diff and return its result
+          #{self}.gen_html_diff(
+            repo: 'required - required git repo name',
+            branch: 'required - required git repo branch (e.g. master, develop, etc)',
+            since: 'optional - optional date, otherwise default to last pull'
           )
 
-          author = #{self}.get_author(
-            repo_root: 'optional path to git repo root (defaults to ".")'
-            from_line: 'required line number to start in range',
-            to_line: 'required line number to stop in range',
-            target_file: 'required file in which line range is queried'
-            entry_beautified: 'required boolean'
+          # Run dump all repo branches and return its result
+          #{self}.dump_all_repo_branches(
+            git_url: 'required - required git repo url'
           )
 
-          all_repo_branches = #{self}.dump_all_repo_branches(
-            git_url: 'required git repo url'
+          # Run get author and return its result
+          #{self}.get_author(
+            repo_root: 'optional - repo root value consumed by #get_author',
+            from_line: 'optional - from line value consumed by #get_author',
+            to_line: 'optional - to line value consumed by #get_author',
+            target_file: 'optional - target file value consumed by #get_author',
+            entry_beautified: 'optional - entry beautified value consumed by #get_author'
           )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
-        }
+        "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/github.rb

@@ -235,6 +235,7 @@ module PWN
         gh_bin = ENV['PATH'].to_s.split(File::PATH_SEPARATOR)
                             .map { |d| File.join(d, 'gh') }
                             .find { |f| File.executable?(f) }
+        # Run api and return its result
         raise "ERROR: gh CLI not found on PATH - use #{self}.api(path:) instead, or install gh (https://cli.github.com)" unless gh_bin
 
         token = resolve_token(opts)
@@ -259,36 +260,58 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          response_json = #{self}.download_all_gists(
-            username: 'optional - username of gists to download (default PWN::Env[:plugins][:github][:username])',
+          # Run download all gists and return its result
+          #{self}.download_all_gists(
+            username: 'optional - username of gists to backup (default PWN::Env[:plugins][:github][:username])',
             target_dir: 'required - target directory to save respective gists'
           )
 
-          runs = #{self}.workflow_runs(
-            owner: 'optional - default PWN::Env[:plugins][:github][:username]',
+          # Run workflow runs and return its result
+          #{self}.workflow_runs(
+            owner: 'required - repo owner (default PWN::Env[:plugins][:github][:username])',
             repo: 'required - repo name',
-            workflow: 'optional - e.g. install-matrix.yml',
-            params: 'optional - {branch:, status:, per_page:}'
+            workflow: 'optional - workflow file name or id (e.g. install-matrix.yml). Omit for all runs.',
+            params: 'optional - {branch:, status:, per_page:, page:}',
+            token: 'optional - token value consumed by #workflow_runs'
           )
 
-          jobs = #{self}.workflow_run_jobs(
-            owner: 'optional', repo: 'required', run_id: 'required'
+          # Run workflow run jobs and return its result
+          #{self}.workflow_run_jobs(
+            owner: 'required - repo owner (default PWN::Env[:plugins][:github][:username])',
+            repo: 'required - repo name',
+            run_id: 'required - workflow run id',
+            params: 'optional - params value consumed by #workflow_run_jobs',
+            token: 'optional - token value consumed by #workflow_run_jobs'
           )
 
-          log = #{self}.job_log(
-            owner: 'optional', repo: 'required', job_id: 'required'
+          # Run job log and return its result
+          #{self}.job_log(
+            owner: 'required - repo owner (default PWN::Env[:plugins][:github][:username])',
+            repo: 'required - repo name',
+            job_id: 'required - job id from workflow_run_jobs',
+            token: 'optional - token value consumed by #job_log'
           )
 
-          json = #{self}.api(
-            path: 'required - e.g. repos/0dayinc/pwn/releases/latest',
-            method: 'optional - :get|:post|:put|:patch|:delete',
-            params: 'optional', body: 'optional', raw: 'optional'
+          # Run api and return its result
+          #{self}.api(
+            path: 'required - REST path relative to https://api.github.com (e.g. repos/0dayinc/pwn/releases/latest)',
+            method: 'optional - :get|:post|:put|:patch|:delete (default :get)',
+            params: 'optional - query params Hash',
+            body: 'optional - request body Hash/Array/String for POST/PUT/PATCH',
+            token: 'optional - PAT (default PWN::Env[:plugins][:github][:personal_access_token])',
+            raw: 'optional - return raw RestClient::Response instead of parsed JSON (default false)'
           )
 
-          #{self}.gh(cmd: 'run view <run_id> -R <owner>/<repo> --log-failed')
+          # Thin wrapper around the `gh` CLI with GH_TOKEN injected from PWN::Env so
+          #{self}.gh(
+            cmd: 'required - gh subcommand string, e.g. run list -R 0dayinc/pwn -L 5 --json databaseId,status',
+            token: 'optional - PAT (default PWN::Env[:plugins][:github][:personal_access_token])'
+          )
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/google_workspace.rb

@@ -876,51 +876,194 @@ module PWN
       end
 
       public_class_method def self.help
-        puts <<~USAGE
-          USAGE:
-            # OAuth (Desktop client from Google Cloud Console)
-            # authorize the printed URL; refresh/bearer persist to Env + pwn.yaml
-            #{self}.obtain_oauth_auth_url(services: 'email,calendar')
-            #{self}.obtain_oauth_auth_url(wait: false)  # URL only; no listener
-            #{self}.exchange_oauth_code(code: 'optional paste fallback')
-            #{self}.authenticated?
-            #{self}.revoke
-
-            # Gmail
-            #{self}.gmail_search(query: 'is:unread', max: 10)
-            #{self}.gmail_get(id: 'MESSAGE_ID')
-            #{self}.gmail_send(to: 'a@b.com', subject: 'Hi', body: '...')
-            #{self}.gmail_reply(id: 'MESSAGE_ID', body: 'Thanks')
-            #{self}.gmail_labels
-            #{self}.gmail_modify(id: 'MESSAGE_ID', add_labels: ['STARRED'], remove_labels: ['UNREAD'])
-
-            # Calendar
-            #{self}.calendar_list(start: '2026-03-01T00:00:00Z')
-            #{self}.calendar_create(summary: 'Standup', start: '2026-03-01T10:00:00-06:00', end: '2026-03-01T10:30:00-06:00')
-            #{self}.calendar_update(id: 'EVENT_ID', summary: 'Standup (moved)')
-            #{self}.calendar_delete(id: 'EVENT_ID')
-
-            # Drive
-            #{self}.drive_search(query: 'quarterly report')
-            #{self}.drive_get(id: 'FILE_ID')
-            #{self}.drive_upload(path: '/tmp/report.pdf')
-            #{self}.drive_download(id: 'FILE_ID', output: '/tmp/out.pdf')
-            #{self}.drive_create_folder(name: 'Reports')
-            #{self}.drive_share(id: 'FILE_ID', email: 'a@b.com', role: 'reader')
-            #{self}.drive_delete(id: 'FILE_ID')
-
-            # Docs / Sheets
-            #{self}.docs_create(title: 'Notes', body: 'Hello')
-            #{self}.docs_get(id: 'DOC_ID')
-            #{self}.docs_append(id: 'DOC_ID', text: ' more')
-            #{self}.sheets_create(title: 'Budget')
-            #{self}.sheets_get(id: 'SHEET_ID', range: 'Sheet1!A1:D10')
-            #{self}.sheets_update(id: 'SHEET_ID', range: 'Sheet1!A1', values: [['Name']])
-            #{self}.sheets_append(id: 'SHEET_ID', range: 'Sheet1!A:C', values: [['a', 'b', 'c']])
-
-            Config: PWN::Env[:plugins][:google_workspace][:oauth]
-            #{self}.authors
-        USAGE
+        puts "USAGE:
+          # Run scopes and return its result
+          #{self}.scopes(
+            scope: 'optional - scope value consumed by #scopes',
+            services: 'optional - services value consumed by #scopes'
+          )
+
+          # Run parse oauth code and return its result
+          #{self}.parse_oauth_code(
+            code: 'optional - code value consumed by #parse_oauth_code'
+          )
+
+          # Run obtain oauth auth url and return its result
+          #{self}.obtain_oauth_auth_url(
+            wait: 'optional - wait value consumed by #obtain_oauth_auth_url',
+            timeout: 'optional - seconds to wait before giving up',
+            probe: 'optional - probe value consumed by #obtain_oauth_auth_url'
+          )
+
+          # Run exchange oauth code and return its result
+          #{self}.exchange_oauth_code(
+            code: 'required - code value consumed by #exchange_oauth_code',
+            code_verifier: 'optional - code verifier value consumed by #exchange_oauth_code (defaults to pending[:verifier])'
+          )
+
+          # Run refresh oauth bearer token and return its result
+          #{self}.refresh_oauth_bearer_token(
+            refresh_token: 'required - refresh token value consumed by #refresh_oauth_bearer_token (defaults to c[:refresh_token])',
+            client_id: 'required - client id value consumed by #refresh_oauth_bearer_token (defaults to c[:client_id])',
+            client_secret: 'required - client secret value consumed by #refresh_oauth_bearer_token (defaults to c[:client_secret])'
+          )
+
+          # Run bearer token and return its result
+          #{self}.bearer_token
+
+          # Run authenticated and return its result
+          #{self}.authenticated?
+
+          # Run revoke and return its result
+          #{self}.revoke
+
+          # ── Gmail ──────────────────────────────────────────────────────────
+          #{self}.gmail_search(
+            query: 'optional - search query string',
+            max: 'optional - max value consumed by #gmail_search'
+          )
+
+          # Run gmail get and return its result
+          #{self}.gmail_get(
+            id: 'required - id value consumed by #gmail_get',
+            format: 'optional - format value consumed by #gmail_get (defaults to full)'
+          )
+
+          # Run gmail send and return its result
+          #{self}.gmail_send(
+            to: 'required - to value consumed by #gmail_send'
+          )
+
+          # Run gmail reply and return its result
+          #{self}.gmail_reply(
+            id: 'required - id value consumed by #gmail_reply'
+          )
+
+          # Run gmail labels and return its result
+          #{self}.gmail_labels
+
+          # Run gmail modify and return its result
+          #{self}.gmail_modify(
+            id: 'required - id value consumed by #gmail_modify',
+            add_labels: 'optional - add labels value consumed by #gmail_modify',
+            add: 'required - add value consumed by #gmail_modify',
+            remove_labels: 'optional - remove labels value consumed by #gmail_modify',
+            remove: 'required - remove value consumed by #gmail_modify'
+          )
+
+          # ── Calendar ───────────────────────────────────────────────────────
+          #{self}.calendar_list(
+            calendar_id: 'optional - calendar id value consumed by #calendar_list',
+            start: 'optional - start value consumed by #calendar_list',
+            end: 'optional - end value consumed by #calendar_list',
+            max: 'optional - max value consumed by #calendar_list'
+          )
+
+          # Run calendar create and return its result
+          #{self}.calendar_create(
+            calendar_id: 'optional - calendar id value consumed by #calendar_create'
+          )
+
+          # Run calendar update and return its result
+          #{self}.calendar_update(
+            id: 'required - id value consumed by #calendar_update',
+            calendar_id: 'optional - calendar id value consumed by #calendar_update'
+          )
+
+          # Run calendar delete and return its result
+          #{self}.calendar_delete(
+            id: 'required - id value consumed by #calendar_delete',
+            calendar_id: 'optional - calendar id value consumed by #calendar_delete'
+          )
+
+          # ── Drive ──────────────────────────────────────────────────────────
+          #{self}.drive_search(
+            query: 'optional - search query string',
+            raw_query: 'optional - raw query value consumed by #drive_search',
+            max: 'optional - max value consumed by #drive_search'
+          )
+
+          # Run drive get and return its result
+          #{self}.drive_get(
+            id: 'required - id value consumed by #drive_get'
+          )
+
+          # Run drive upload and return its result
+          #{self}.drive_upload(
+            path: 'required - filesystem path to read or write',
+            name: 'required - binary or identifier name',
+            parent: 'optional - parent value consumed by #drive_upload',
+            mime: 'optional - mime value consumed by #drive_upload'
+          )
+
+          # Run drive download and return its result
+          #{self}.drive_download(
+            id: 'required - id value consumed by #drive_download',
+            export_mime: 'optional - export mime value consumed by #drive_download (defaults to EXPORT_MIME[meta[:mimeType])',
+            output: 'optional - output value consumed by #drive_download'
+          )
+
+          # Run drive create folder and return its result
+          #{self}.drive_create_folder(
+            name: 'required - binary or identifier name',
+            parent: 'optional - parent value consumed by #drive_create_folder'
+          )
+
+          # Run drive share and return its result
+          #{self}.drive_share(
+            id: 'required - id value consumed by #drive_share',
+            role: 'optional - role value consumed by #drive_share',
+            type: 'optional - type value consumed by #drive_share',
+            email: 'optional - email value consumed by #drive_share',
+            domain: 'optional - FQDN to query (e.g. example.com)',
+            notify: 'optional - notify value consumed by #drive_share'
+          )
+
+          # Run drive delete and return its result
+          #{self}.drive_delete(
+            id: 'required - id value consumed by #drive_delete',
+            permanent: 'optional - permanent value consumed by #drive_delete'
+          )
+
+          # ── Docs ───────────────────────────────────────────────────────────
+          #{self}.docs_get(
+            id: 'required - id value consumed by #docs_get'
+          )
+
+          # Run docs create and return its result
+          #{self}.docs_create(
+            title: 'required - title value consumed by #docs_create',
+            body: 'optional - body value consumed by #docs_create'
+          )
+
+          # Run docs append and return its result
+          #{self}.docs_append(
+            id: 'required - id value consumed by #docs_append',
+            text: 'optional - text value consumed by #docs_append'
+          )
+
+          # ── Sheets ─────────────────────────────────────────────────────────
+          #{self}.sheets_create(
+            title: 'required - title value consumed by #sheets_create',
+            sheet_name: 'optional - sheet name value consumed by #sheets_create'
+          )
+
+          # Run sheets get and return its result
+          #{self}.sheets_get(
+            id: 'required - id value consumed by #sheets_get',
+            range: 'required - range value consumed by #sheets_get'
+          )
+
+          # Run sheets update and return its result
+          #{self}.sheets_update
+
+          # Run sheets append and return its result
+          #{self}.sheets_append
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
       end
     end
   end