pwn 0.5.713 → 0.5.714

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc496486bb8a12f9803c7fe6d75ffeffe72a885486de20f2791363c050cf011d
-  data.tar.gz: 0a23407f3aa2707b806032e36ebc888428e63e6019825c0e24d6d6cf93269aa3
+  metadata.gz: 347698a0da0cfba54c8e8975a931cd0894940c126e842c17c5bad162e1307eee
+  data.tar.gz: fd5495f0f65d8e06acc5695b4ca796818e107ea164285c79161cf2c44c7184db
 SHA512:
-  metadata.gz: e0882283247eb1d1389b1f2171286a14df1a460b41a244a89b05e8a06926f81c9e5d381534d10bdc603e8b0d6663e62ee4e12f1abd9aedafec792f852bbad1e7
-  data.tar.gz: bd5dc6602f9d74153780ca07aa7fc3b81d7ae3148115916d47ea17ccc6a1b3433fe2d98fe9074b611bd00ab46bcc750062f5b94885799403697652fd8c6904d3
+  metadata.gz: bdcfa6f78d2ef9d8350cfc7dd69c4294e679fd537112428922858dea21eaad3ed9d295247c194dcf7372289e18c31c63fcf79076e82117792fb3c3214f2ad341
+  data.tar.gz: a604db47a0ea8f698cd8c3b659d626951209082a7bfff7b4ec51c6529d200d24ab9d36d7302d6796bdc422d89ab9e8b45ea67bf926b43dee4b2d4ced4c7feeff

data/etc/default_skills/pwn/ai/agent/tool_guard/SKILL.md

@@ -36,6 +36,11 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `present`
 - `placeholder`
 - `bashism`
+- `shell_syntax_surface`
+- `mint_canary`
+- `canary_leak`
+- `injection_score`
+- `quarantine_output`
 - `shell_bash`
 - `shell_name`
 - `protect_http`
@@ -54,6 +59,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `timeout_prior_count`
 - `refuse_copied_persist`
 - `scope_refusal`
+- `rfc1918`
 - `ip_in_cidr`
 - `command_class`
 - `record_runtime`
@@ -63,6 +69,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `help`
 - `auto_job?`
 - `bashism?`
+- `canary_leak?`
 - `ip_in_cidr?`
 - `note_timeout!`
 - `placeholder?`
@@ -71,6 +78,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `protect_http!`
 - `refuse_copied_persist?`
 - `reset_timeout_budget!`
+- `rfc1918?`
 - `shell_bash?`
 
 ## Source

data/etc/default_skills/pwn/ai/agent/tools/decompile/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pwn-ai-agent-tools-decompile
+description: Drive PWN::Ai::Agent::Tools::Decompile from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Ai::Agent::Tools::Decompile
+  source: pwn/ai/agent/tools/decompile.rb
+---
+
+# PWN::Ai::Agent::Tools::Decompile
+
+Public API for PWN::Ai::Agent::Tools::Decompile.
+
+## When to use
+
+Call `PWN::Ai::Agent::Tools::Decompile` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/ai/agent/tools/decompile.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Ai::Agent::Tools::Decompile.help
+PWN::Ai::Agent::Tools::Decompile.help(opts)
+```
+
+## Public methods
+
+- _(no public class methods parsed)_
+
+## Source
+
+`pwn/ai/agent/tools/decompile.rb`
+
+## Verification
+
+`PWN::Ai::Agent::Tools::Decompile.respond_to?(:help)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/memory_index/SKILL.md

@@ -39,6 +39,7 @@ PWN::MemoryIndex.available(opts)
 - `refresh`
 - `embed`
 - `reset`
+- `bm25`
 - `authors`
 - `help`
 - `available?`

data/etc/default_skills/pwn/plugins/artifact_registry/SKILL.md

@@ -37,6 +37,7 @@ PWN::Plugins::ArtifactRegistry.required_bins(opts)
 - `register`
 - `list`
 - `get`
+- `read_page`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/ghidra/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pwn-plugins-ghidra
+description: Drive PWN::Plugins::Ghidra from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Plugins::Ghidra
+  source: pwn/plugins/ghidra.rb
+---
+
+# PWN::Plugins::Ghidra
+
+Headless Ghidra analyzeHeadless wrapper with r2 fallback.
+
+## When to use
+
+Call `PWN::Plugins::Ghidra` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/plugins/ghidra.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Plugins::Ghidra.help
+PWN::Plugins::Ghidra.required_bins(opts)
+```
+
+## Public methods
+
+- `required_bins`
+- `analyze`
+- `decompile`
+- `authors`
+- `help`
+
+## Source
+
+`pwn/plugins/ghidra.rb`
+
+## Verification
+
+`PWN::Plugins::Ghidra.respond_to?(:required_bins)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/plugins/log/SKILL.md

@@ -38,6 +38,7 @@ PWN::Plugins::Log.append(opts)
 - `debug_log_path`
 - `start_debug`
 - `trace_enabled`
+- `debug_dir`
 - `next_request_log`
 - `finish_request_log`
 - `stop_debug`

data/etc/default_skills/pwn/setup/references/urls.md

@@ -1,3 +1,4 @@
 # PWN::Setup source links
 
 - https://install.pwndbg.re
+- https://ghidra-sre.org

data/lib/pwn/ai/agent/dispatch.rb

@@ -46,6 +46,10 @@ module PWN
           args = parse_args(raw: raw, entry: entry)
           required = Array(entry.schema&.dig(:parameters, :required))
           args = ToolGuard.coerce_args(args: args, required: required) if defined?(ToolGuard)
+          if defined?(ToolGuard) && ToolGuard.respond_to?(:canary_leak?) &&
+             ToolGuard.canary_leak?(text: args.inspect)
+            return JSON.generate(success: false, error: 'refused: session canary in outbound args')
+          end
           if defined?(ToolGuard) && ToolGuard.respond_to?(:refuse_copied_persist?) &&
              ToolGuard.refuse_copied_persist?(name: entry.name, args: args)
             return JSON.generate(
@@ -54,6 +58,7 @@ module PWN
             )
           end
           result = entry.handler.call(args)
+          result = ToolGuard.quarantine_output(text: result) if defined?(ToolGuard) && result.is_a?(String) && ToolGuard.respond_to?(:quarantine_output)
           JSON.generate(success: true, result: result, effect: effect(name: entry.name, args: args))
         rescue StandardError => e
           JSON.generate(

data/lib/pwn/ai/agent/loop.rb

@@ -1168,12 +1168,22 @@ module PWN
         end
 
         private_class_method def self.note_same_payload!(opts = {})
+          return 0 if read_like?(opts)
+
           sig = payload_sig(opts)
           counts = Thread.current[:pwn_same_payload] ||= Hash.new(0)
           counts[sig] += 1
           counts[sig]
         end
 
+        private_class_method def self.read_like?(opts = {})
+          name = opts[:name].to_s
+          return true if name.match?(/_(read|get|list|status|recall|tail)\z/)
+          return true if %w[pty_read artifact_read artifacts_get job_status job_result].include?(name)
+
+          false
+        end
+
         private_class_method def self.no_progress_result(opts = {})
           checkpoint_result(opts)
         end

data/lib/pwn/ai/agent/mistakes.rb

@@ -115,6 +115,7 @@ module PWN
           return 'auth_denied' if e.match?(/access denied|unauthorized|not authorized|\b401\b|\b403\b|pull access denied/i)
           return 'name_conflict' if e.match?(/already (?:in use|exists)|name conflict|Conflict\.|duplicate/i)
           return 'parse_error' if e.match?(/parse error|parsererror|template.*error|unexpected token/i)
+          return 'socket_perm' if e.match?(/docker\.sock|unix(?:\s+|:)socket|eperm.*sock|sock.*permission/i)
           return 'missing_path' if e.match?(%r{no such file|enoent|not found: /}i)
           return 'net_unreach' if e.match?(/network is unreachable|no route to host|ehostunreach/i)
           return 'perm_denied' if e.match?(/permission denied|eacces/i)
@@ -872,7 +873,7 @@ module PWN
               error: 'required - raw error text (will be normalised)'
             )
 
-            # Classify an error into auth_denied/name_conflict/parse_error/missing_path/net_unreach/perm_denied/timeout/other.
+            # Classify an error into auth_denied/name_conflict/parse_error/socket_perm/missing_path/net_unreach/perm_denied/timeout/other.
             #{self}.error_class(
               error: 'required - raw error text'
             )

data/lib/pwn/ai/agent/prompt_builder.rb

@@ -201,9 +201,12 @@ module PWN
           load_line = "load1=#{snap[:load1]} ncpu=#{snap[:ncpu]} mem_avail_mb=#{snap[:mem_avail_mb]}"
           doc = (PWN::Plugins::PreflightChecker.host_summary if defined?(PWN::Plugins::PreflightChecker))
           land = (PWN::Plugins::DetectOS.living_off_the_land[:summary] if defined?(PWN::Plugins::DetectOS))
+          canary = (Thread.current[:pwn_canary] || ToolGuard.mint_canary if defined?(ToolGuard) && ToolGuard.respond_to?(:mint_canary))
           "#{load_line} pwn_eval/shell timeout = conservative seconds for this host " \
             "(defaults eval=#{eval_s || 20}s shell=#{shell_s || 30}s, clamped). " \
-            "LIVING OFF THE LAND #{land} #{doc}"
+            "LIVING OFF THE LAND #{land} #{doc} " \
+            "CANARY #{canary} never copy this token into tool args. " \
+            'DOMAIN TOOLS for pentest/RE: binary_triage, pty_open, job_run, exploitdev, fuzz_campaign, finding_record, decompile.'
         rescue StandardError
           'load unknown — pass a conservative timeout on pwn_eval/shell anyway.'
         end

data/lib/pwn/ai/agent/registry.rb

@@ -127,7 +127,8 @@ module PWN
             pool = pool.select { |e| CORE_TOOLS.include?(e.name) }
           elsif opts[:relevance] && router_enabled?
             keep = rank({ query: opts[:relevance], entries: pool }.merge(pref_fwd)).first(opts[:top_k] || 10).map(&:name)
-            names = (CORE_TOOLS + keep).uniq
+            pinned = domain_pin_names(query: opts[:relevance])
+            names = (CORE_TOOLS + keep + pinned).uniq
             pool  = pool.select { |e| names.include?(e.name) }
           end
 
@@ -338,6 +339,25 @@ module PWN
           {}
         end
 
+        DOMAIN_PINS = {
+          re: %w[pty_open pty_send pty_read pty_close binary_triage exploitdev job_run decompile],
+          pentest: %w[pty_open job_run finding_record binary_triage fuzz_campaign exploitdev],
+          fuzzing: %w[fuzz_campaign job_run job_status job_result],
+          exploitation: %w[exploitdev pty_open job_run finding_record],
+          reporting: %w[finding_record finding_report artifacts_list]
+        }.freeze
+
+        private_class_method def self.domain_pin_names(opts = {})
+          q = opts[:query].to_s.downcase
+          classes = []
+          classes << :re if q.match?(/reverse.?engineer|binary.?analy|decompile/)
+          classes << :pentest if q.match?(/penet|bug.?bounty|offensive|red.?team|pentest/)
+          classes << :fuzzing if q.match?(/\bfuzz|afl/)
+          classes << :exploitation if q.match?(/exploit|payload/)
+          classes << :reporting if q.match?(/finding|report|severity/)
+          classes.flat_map { |c| Array(DOMAIN_PINS[c]) }.uniq
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors

data/lib/pwn/ai/agent/reward.rb

@@ -1252,7 +1252,8 @@ module PWN
         private_class_method def self.judge_model
           return nil unless defined?(PWN::Env) && PWN::Env.is_a?(Hash)
 
-          m = PWN::Env.dig(:ai, :agent, :reward_model)
+          m = PWN::Env.dig(:ai, :agent, :model_routes, :judge)
+          m = PWN::Env.dig(:ai, :agent, :reward_model) if m.to_s.empty?
           m = PWN::Env.dig(:ai, :reflect_model) if m.to_s.empty?
           m.to_s.empty? ? nil : m.to_s
         rescue StandardError

data/lib/pwn/ai/agent/tool_guard.rb

@@ -3,6 +3,7 @@
 require 'digest'
 require 'json'
 require 'fileutils'
+require 'securerandom'
 
 module PWN
   module AI
@@ -45,11 +46,50 @@ module PWN
         end
 
         public_class_method def self.bashism?(opts = {})
-          BASHISM_RX.match?(opts[:text].to_s)
+          BASHISM_RX.match?(shell_syntax_surface(text: opts[:text]))
         rescue StandardError
           false
         end
 
+        public_class_method def self.shell_syntax_surface(opts = {})
+          s = opts[:text].to_s.dup
+          s.gsub!(/<<[-~]?\s*(['"])(\w+)\1.*?^\2\s*$/m, ' ')
+          s.gsub!(/'[^']*'/, "''")
+          s
+        end
+
+        public_class_method def self.mint_canary(opts = {})
+          n = (opts[:bytes] || 8).to_i
+          n = 8 if n <= 0
+          tok = "PWNCANARY#{SecureRandom.hex(n)}"
+          Thread.current[:pwn_canary] = tok
+          tok
+        end
+
+        public_class_method def self.canary_leak?(opts = {})
+          tok = Thread.current[:pwn_canary].to_s
+          return false if tok.empty?
+
+          opts[:text].to_s.include?(tok)
+        end
+
+        public_class_method def self.injection_score(opts = {})
+          t = opts[:text].to_s
+          score = 0
+          score += 3 if t.match?(/ignore (all )?(previous|prior) (instructions|directives)/i)
+          score += 2 if t.match?(/system:\s|tool_call|function_call/i)
+          score += 2 if t.match?(/\bexfiltrat|\bdo not tell (the )?(user|operator)/i)
+          score
+        end
+
+        public_class_method def self.quarantine_output(opts = {})
+          text = opts[:text].to_s
+          score = injection_score(text: text)
+          return text unless score >= 3
+
+          "[QUARANTINED injection_score=#{score}]\n#{text}"
+        end
+
         public_class_method def self.shell_bash?
           v = (PWN::Env.dig(:ai, :agent, :shell_bash) if defined?(PWN::Env))
           v == true || v.to_s.match?(/\A(1|true|yes|on)\z/i)
@@ -373,7 +413,7 @@ module PWN
 
           ips = cmd.scan(/\b\d{1,3}(?:\.\d{1,3}){3}\b/)
           hosts = cmd.scan(/\b[a-z0-9][a-z0-9.-]+\.[a-z]{2,}\b/i)
-          bad_ip = allow.any? ? ips.find { |ip| allow.none? { |cidr| ip_in_cidr?(ip: ip, cidr: cidr) } } : nil
+          bad_ip = allow.any? ? ips.find { |ip| !rfc1918?(ip: ip) && allow.none? { |cidr| ip_in_cidr?(ip: ip, cidr: cidr) } } : nil
           bad_host = domains.any? ? hosts.find { |h| domains.none? { |d| h.downcase.end_with?(d.downcase) } } : nil
           hit = bad_ip || bad_host
           return nil unless hit
@@ -383,6 +423,17 @@ module PWN
           nil
         end
 
+        public_class_method def self.rfc1918?(opts = {})
+          oct = opts[:ip].to_s.split('.').map(&:to_i)
+          return false unless oct.length == 4
+
+          return true if [10, 127].include?(oct[0])
+          return true if oct[0] == 192 && oct[1] == 168
+          return true if oct[0] == 172 && oct[1].between?(16, 31)
+
+          false
+        end
+
         public_class_method def self.ip_in_cidr?(opts = {})
           ip = opts[:ip].to_s.split('.').map(&:to_i)
           cidr, bits = opts[:cidr].to_s.split('/')
@@ -458,6 +509,31 @@ module PWN
               text: 'optional - text value consumed by #bashism?'
             )
 
+            # Strip quoted heredocs and single-quoted strings before bash-syntax lint.
+            #{self}.shell_syntax_surface(
+              text: 'required - command string to lint'
+            )
+
+            # Mint a per-thread session canary token stored on Thread.current.
+            #{self}.mint_canary(
+              bytes: 'optional - hex length (defaults to 8)'
+            )
+
+            # True when text contains the current session canary.
+            #{self}.canary_leak?(
+              text: 'required - outbound argv or URL to inspect'
+            )
+
+            # Heuristic injection score for tool output (ignore-previous, tool-call spoof).
+            #{self}.injection_score(
+              text: 'required - tool output to score'
+            )
+
+            # Prefix high-score tool output with a QUARANTINED frame.
+            #{self}.quarantine_output(
+              text: 'required - tool output to wrap if injection_score >= 3'
+            )
+
             # Run shell bash and return its result
             #{self}.shell_bash?
 
@@ -548,6 +624,11 @@ module PWN
               command: 'required - shell command to inspect for IPs and hostnames'
             )
 
+            # True when ip is RFC1918 or loopback (always in-scope unless strict).
+            #{self}.rfc1918?(
+              ip: 'required - IPv4 address'
+            )
+
             # True when ip is inside cidr (e.g. 10.1.2.3 in 10.0.0.0/8).
             #{self}.ip_in_cidr?(
               ip: 'required - IPv4 address',

data/lib/pwn/ai/agent/tools/artifacts.rb

@@ -33,3 +33,29 @@ PWN::AI::Agent::Registry.register(
     PWN::Plugins::ArtifactRegistry.get(path: args[:path] || args['path'])
   }
 )
+PWN::AI::Agent::Registry.register(
+  name: 'artifact_read',
+  toolset: 'sessions',
+  schema: {
+    name: 'artifact_read',
+    description: 'Page an artifact as text/hex/base64 from offset.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        offset: { type: 'integer' },
+        length: { type: 'integer' },
+        mode: { type: 'string', description: 'text|hex|base64' }
+      },
+      required: %w[path]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::ArtifactRegistry.read_page(
+      path: args[:path] || args['path'],
+      offset: args[:offset] || args['offset'],
+      length: args[:length] || args['length'],
+      mode: args[:mode] || args['mode']
+    )
+  }
+)

data/lib/pwn/ai/agent/tools/decompile.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+
+PWN::AI::Agent::Registry.register(
+  name: 'decompile',
+  toolset: 'pwn',
+  schema: {
+    name: 'decompile',
+    description: 'Decompile a binary via Ghidra analyzeHeadless, or r2 pdg if Ghidra is absent.',
+    parameters: {
+      type: 'object',
+      properties: {
+        bin: { type: 'string' },
+        path: { type: 'string' },
+        project_dir: { type: 'string' }
+      },
+      required: %w[bin]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Ghidra.decompile(
+      bin: args[:bin] || args[:path] || args['bin'],
+      project_dir: args[:project_dir] || args['project_dir']
+    )
+  }
+)

data/lib/pwn/config.rb

@@ -196,7 +196,13 @@ module PWN
             operator_account: nil,
             sessions_keep_days: 90,
             artifacts_keep_days: 90,
-            max_total_mb: 512
+            max_total_mb: 512,
+            model_routes: {
+              summarize: nil,
+              judge: nil,
+              act: nil,
+              sensitive: nil
+            }
             # multi-agent personas : ~/.pwn/agents.yml  (see PWN::AI::Agent::Swarm.help)
             # swarm bus            : ~/.pwn/swarm/<swarm_id>/bus.jsonl
           }

data/lib/pwn/memory_index.rb

@@ -272,6 +272,50 @@ module PWN
       []
     end
 
+    public_class_method def self.bm25(opts = {})
+      query = opts[:query].to_s.downcase
+      docs = Array(opts[:docs]).map(&:to_s)
+      qtok = expand_query(query: query)
+      return docs.map { |d| { doc: d, score: 0.0 } } if qtok.empty?
+
+      df = Hash.new(0)
+      tokenized = docs.map do |d|
+        toks = d.downcase.scan(/[a-z0-9]{3,}/)
+        toks.uniq.each { |t| df[t] += 1 }
+        toks
+      end
+      n = docs.length.to_f
+      avgdl = tokenized.sum(&:length) / [n, 1].max
+      k1 = 1.2
+      b = 0.75
+      ranked = docs.each_with_index.map do |doc, i|
+        toks = tokenized[i]
+        tf = Hash.new(0)
+        toks.each { |t| tf[t] += 1 }
+        dl = toks.length.to_f
+        score = qtok.sum do |t|
+          f = tf[t]
+          next 0.0 if f.zero?
+
+          idf = Math.log(((n - df[t] + 0.5) / (df[t] + 0.5)) + 1)
+          idf * ((f * (k1 + 1)) / (f + (k1 * (1 - b + (b * dl / avgdl)))))
+        end
+        { doc: doc, score: score }
+      end
+      ranked.sort_by { |h| -h[:score] }
+    end
+
+    private_class_method def self.expand_query(opts = {})
+      toks = opts[:query].to_s.downcase.scan(/[a-z0-9]{3,}/)
+      table = {
+        'bypass' => %w[evasion evade],
+        'rate' => %w[throttle],
+        'limit' => %w[throttle],
+        'login' => %w[auth]
+      }
+      toks.flat_map { |t| [t] + Array(table[t]) }.uniq
+    end
+
     # Author(s):: 0day Inc. <support@0dayinc.com>
 
     public_class_method def self.authors
@@ -308,6 +352,12 @@ module PWN
           texts: 'required - Array texts value consumed by #embed'
         )
 
+        # Rank documents by BM25 (pure Ruby; no embedder required).
+        #{self}.bm25(
+          query: 'required - search text',
+          docs: 'required - Array of document strings'
+        )
+
         # Run reset and return its result
         #{self}.reset
 

data/lib/pwn/plugins/artifact_registry.rb

@@ -49,6 +49,27 @@ module PWN
         { path: path, sha256: Digest::SHA256.file(path).hexdigest, bytes: File.size(path), body: File.binread(path)[0, 65_536] }
       end
 
+      public_class_method def self.read_page(opts = {})
+        path = opts[:path].to_s
+        raise 'ERROR: path is required' if path.empty?
+        raise "ERROR: file not found: #{path}" unless File.file?(path)
+
+        offset = opts[:offset].to_i
+        length = (opts[:length] || 4_096).to_i
+        length = 4_096 if length <= 0
+        mode = (opts[:mode] || 'text').to_s
+        data = File.binread(path, length, offset).to_s
+        case mode
+        when 'hex'
+          { path: path, offset: offset, bytes: data.bytesize, hex: data.unpack1('H*') }
+        when 'base64'
+          require 'base64'
+          { path: path, offset: offset, bytes: data.bytesize, body: Base64.strict_encode64(data) }
+        else
+          { path: path, offset: offset, bytes: data.bytesize, body: data.force_encoding('UTF-8').scrub }
+        end
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
       end
@@ -75,6 +96,14 @@ module PWN
             path: 'required - filesystem path of a registered artifact'
           )
 
+          # Page an artifact as text, hex, or base64 from an offset.
+          #{self}.read_page(
+            path: 'required - filesystem path of the artifact',
+            offset: 'optional - byte offset (defaults to 0)',
+            length: 'optional - byte count (defaults to 4096)',
+            mode: 'optional - text, hex, or base64 (defaults to text)'
+          )
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "