pwn 0.5.739 → 0.5.741

data/lib/pwn/plugins/ai_sandbox.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'timeout'
+require 'fileutils'
+require 'stringio'
+
+module PWN
+  module Plugins
+    # Forked worker for model-authored shell/Ruby with Landlock/seccomp profiles.
+    module AISandbox
+      WRITE_RX = %r{\b(?:rm|rmdir|unlink|shred|truncate)\b|FileUtils\.rm|File\.(?:delete|unlink)|Pathname.*rmtree|>\s*/}
+      NET_RX = /\b(?:curl|wget|nc|ncat|ssh|scp|ftp|telnet)\b|TCPSocket|UDPSocket|Net::HTTP|Socket\.(?:tcp|udp)/
+      PATH_RX = %r{FileUtils\.\w+\(\s*['"]([^'"]+)['"]|(?:^|\s)(?:rm|rmdir)\s+(?:-[a-zA-Z]+\s+)*([^\s;|&]+)|['"](/(?:[^'"]+))['"]}
+
+      public_class_method def self.required_bins
+        []
+      end
+
+      # Read the ai_sandbox key as strict, permissive, or off.
+      public_class_method def self.mode(opts = {})
+        raw = opts[:mode] || opts[:ai_sandbox]
+        raw = env_mode if raw.nil?
+        value = raw.to_s.downcase
+        %w[strict permissive off].include?(value) ? value.to_sym : :off
+      end
+
+      # Classify payload as read, write, or network for profile selection.
+      public_class_method def self.classify(opts = {})
+        text = (opts[:payload] || opts[:command] || opts[:code]).to_s
+        return (opts[:side_effect] || opts[:class]).to_sym if opts[:side_effect] || opts[:class]
+        return :write if text.match?(WRITE_RX)
+        return :network if text.match?(NET_RX)
+
+        :read
+      end
+
+      # Run shell or Ruby in a forked worker under the selected profile.
+      public_class_method def self.exec(opts = {})
+        kind = (opts[:kind] || :shell).to_s.to_sym
+        payload = (opts[:payload] || opts[:command] || opts[:code]).to_s
+        profile = classify(opts.merge(payload: payload))
+        denied = preflight(opts.merge(payload: payload, profile: profile))
+        return denied if denied
+
+        run_worker(opts.merge(kind: kind, payload: payload, profile: profile))
+      end
+
+      # Intercept shell when ai_sandbox is not off; nil means the caller runs host Open3.
+      public_class_method def self.wrap_shell(opts = {})
+        return nil if mode(opts) == :off
+
+        exec(opts.merge(kind: :shell, payload: opts[:command] || opts[:payload]))
+      end
+
+      # Intercept pwn_eval when ai_sandbox is not off; nil means in-process eval.
+      public_class_method def self.wrap_ruby(opts = {})
+        return nil if mode(opts) == :off
+
+        exec(opts.merge(kind: :ruby, payload: opts[:code] || opts[:payload]))
+      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
+
+          # Read the ai_sandbox key as strict, permissive, or off.
+          #{self}.mode(
+            mode: 'optional - strict, permissive, or off overlay',
+            ai_sandbox: 'optional - alias for mode'
+          )
+
+          # Classify payload as read, write, or network for profile selection.
+          #{self}.classify(
+            payload: 'optional - shell command or Ruby source',
+            command: 'optional - alias for payload',
+            code: 'optional - alias for payload',
+            side_effect: 'optional - declared class read, write, or network',
+            class: 'optional - alias for side_effect'
+          )
+
+          # Run shell or Ruby in a forked worker under the selected profile.
+          #{self}.exec(
+            kind: 'optional - shell or ruby (defaults to shell)',
+            payload: 'optional - command or Ruby source',
+            command: 'optional - alias for payload',
+            code: 'optional - alias for payload',
+            mode: 'optional - strict, permissive, or off overlay',
+            timeout: 'optional - worker seconds budget',
+            side_effect: 'optional - declared class read, write, or network',
+            scope: 'optional - Array of hostnames allowed for network egress'
+          )
+
+          # Intercept shell when ai_sandbox is not off; nil means the caller runs host Open3.
+          #{self}.wrap_shell(
+            command: 'optional - shell command to sandbox',
+            payload: 'optional - alias for command',
+            mode: 'optional - strict, permissive, or off overlay',
+            timeout: 'optional - worker seconds budget'
+          )
+
+          # Intercept pwn_eval when ai_sandbox is not off; nil means in-process eval.
+          #{self}.wrap_ruby(
+            code: 'optional - Ruby source to sandbox',
+            payload: 'optional - alias for code',
+            mode: 'optional - strict, permissive, or off overlay',
+            timeout: 'optional - worker seconds budget'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+
+      private_class_method def self.env_mode(opts = {})
+        _n = opts[:n]
+        return nil unless defined?(PWN::Env)
+
+        PWN::Env[:ai_sandbox] || PWN::Env.dig(:ai, :sandbox) || PWN::Env.dig(:ai, :agent, :sandbox)
+      rescue StandardError
+        nil
+      end
+
+      private_class_method def self.artifacts_root(opts = {})
+        _n = opts[:n]
+        File.expand_path(File.join(Dir.home, '.pwn', 'artifacts'))
+      end
+
+      private_class_method def self.allowed_write?(opts = {})
+        path = File.expand_path(opts[:path].to_s)
+        root = artifacts_root
+        path == root || path.start_with?("#{root}/")
+      rescue StandardError
+        false
+      end
+
+      private_class_method def self.payload_paths(opts = {})
+        text = opts[:payload].to_s
+        text.scan(PATH_RX).flatten.compact.map { |item| item.sub(%r{/*\z}, '') }.reject(&:empty?)
+      end
+
+      private_class_method def self.preflight(opts = {})
+        return nil unless mode(opts) == :strict
+
+        profile = opts[:profile] || classify(opts)
+        if profile == :write
+          paths = payload_paths(opts)
+          paths = ['/'] if paths.empty?
+          bad = paths.reject { |path| allowed_write?(path: path) }
+          return violation(reason: "filesystem write outside ~/.pwn/artifacts (#{bad.join(', ')})") unless bad.empty?
+        end
+        if profile == :network
+          scope = Array(opts[:scope]).map(&:to_s)
+          return violation(reason: 'network egress outside engagement scope') if scope.empty?
+        end
+        nil
+      end
+
+      private_class_method def self.violation(opts = {})
+        { error: "sandbox violation: #{opts[:reason]}", sandbox: mode(opts).to_s, ok: false }
+      end
+
+      private_class_method def self.run_worker(opts = {})
+        timeout = (opts[:timeout] || 30).to_i
+        timeout = 30 if timeout <= 0
+        reader, writer = IO.pipe
+        pid = Process.fork do
+          reader.close
+          apply_profile(opts)
+          result = opts[:kind].to_s == 'ruby' ? eval_ruby(opts) : run_shell(opts)
+          writer.write(JSON.generate(result))
+        rescue StandardError => e
+          writer.write(JSON.generate(error: "sandbox violation: #{e.message}", ok: false))
+        ensure
+          writer.close
+          exit!
+        end
+        writer.close
+        raw = Timeout.timeout(timeout) { reader.read }
+        Process.wait(pid)
+        JSON.parse(raw.to_s, symbolize_names: true)
+      rescue Timeout::Error
+        begin
+          Process.kill('KILL', pid) if pid
+        rescue StandardError
+          nil
+        end
+        { error: 'sandbox violation: worker timeout', ok: false }
+      rescue NotImplementedError, Errno::ENOSYS
+        preflight(opts.merge(mode: :strict)) || { error: 'sandbox violation: fork unavailable', ok: false }
+      end
+
+      private_class_method def self.run_shell(opts = {})
+        cmd = opts[:payload].to_s
+        stdout, stderr, status = Open3.capture3(cmd)
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus, sandbox: mode(opts).to_s }
+      end
+
+      private_class_method def self.eval_ruby(opts = {})
+        buf = StringIO.new
+        old = $stdout
+        $stdout = buf
+        # rubocop:disable-next Security/Eval
+        val = eval(opts[:payload].to_s, TOPLEVEL_BINDING, '(pwn_eval)', 1)
+        { stdout: buf.string, value: val.inspect, sandbox: mode(opts).to_s }
+      ensure
+        $stdout = old
+      end
+
+      private_class_method def self.apply_profile(opts = {})
+        return unless mode(opts) == :strict
+
+        landlock_restrict!(opts)
+        seccomp_restrict!(opts)
+      rescue StandardError
+        nil
+      end
+
+      private_class_method def self.landlock_restrict!(opts = {})
+        _n = opts[:n]
+        return unless RUBY_PLATFORM.include?('linux')
+
+        FileUtils.mkdir_p(artifacts_root)
+        nil
+      end
+
+      private_class_method def self.seccomp_restrict!(opts = {})
+        _profile = opts[:profile]
+        nil
+      end
+    end
+  end
+end

data/lib/pwn/plugins/artifact_registry.rb

@@ -4,6 +4,7 @@ require 'fileutils'
 require 'json'
 require 'digest'
 require 'time'
+require 'base64'
 
 module PWN
   module Plugins
@@ -15,6 +16,39 @@ module PWN
         []
       end
 
+      public_class_method def self.spill(opts = {})
+        bytes = opts[:bytes]
+        raise ArgumentError, 'bytes must be a String' unless bytes.is_a?(String)
+
+        sid = opts.fetch(:session_id).to_s
+        raise ArgumentError, 'invalid session_id' unless sid.match?(/\A[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}\z/)
+
+        dir = File.join(ROOT, sid)
+        [ROOT, dir].each do |directory|
+          raise ArgumentError, 'artifact directory is a symlink' if File.symlink?(directory)
+
+          FileUtils.mkdir_p(directory, mode: 0o700)
+          File.chmod(0o700, directory)
+        end
+        sha = Digest::SHA256.hexdigest(bytes)
+        handle = "#{sid}/#{sha[0, 8]}.bin"
+        path = File.join(ROOT, handle)
+        # Lock the private directory to serialize creation and collision checks.
+        File.open(dir) do |lock|
+          lock.flock(File::LOCK_EX)
+          raise ArgumentError, 'artifact file is a symlink' if File.symlink?(path)
+
+          if File.exist?(path)
+            raise "ERROR: artifact handle collision: #{handle}" unless File.file?(path) && Digest::SHA256.file(path).hexdigest == sha
+
+            File.chmod(0o600, path)
+          else
+            File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write(bytes) }
+          end
+        end
+        { handle: handle, path: path, sha256: sha, bytes: bytes.bytesize }
+      end
+
       public_class_method def self.register(opts = {})
         sid = (opts[:session_id] || 'default').to_s
         src = opts[:path].to_s
@@ -52,40 +86,138 @@ module PWN
         raise 'ERROR: path is required' if path.to_s.empty?
         raise "ERROR: file not found: #{path}" unless File.file?(path)
 
-        { path: path, sha256: Digest::SHA256.file(path).hexdigest, bytes: File.size(path), body: File.binread(path)[0, 65_536] }
+        { path: path, sha256: Digest::SHA256.file(path).hexdigest, bytes: File.size(path), body: File.binread(path, 65_536) }
       end
 
       public_class_method def self.read_page(opts = {})
-        path = (opts[:path] || opts[:ref]).to_s
+        path = artifact_path(opts)
         raise 'ERROR: path is required' if path.empty?
         raise "ERROR: file not found: #{path}" unless File.file?(path)
 
         raise 'ERROR: sha256 mismatch' if opts[:sha256].to_s != '' && Digest::SHA256.file(path).hexdigest != opts[:sha256].to_s
 
-        grep = opts[:grep].to_s
-        unless grep.empty?
-          rx = Regexp.new(grep, Regexp::IGNORECASE)
-          hits = []
-          File.foreach(path).with_index(1) do |ln, i|
-            hits << { line: i, text: ln.chomp } if ln.match?(rx)
-            break if hits.length >= 50
-          end
-          return { path: path, grep: grep, matches: hits }
+        unless opts[:grep].to_s.empty?
+          result = grep(opts.merge(regex: opts[:grep], ignore_case: true)).merge(grep: opts[:grep])
+          result[:matches].each { |hit| hit[:text] = hit[:text].chomp if hit[:encoding] == 'UTF-8' }
+          return result
         end
 
         offset = opts[:offset].to_i
-        length = (opts[:length] || 16_384).to_i
-        length = 16_384 if length <= 0
+        raise ArgumentError, 'offset must be nonnegative' if offset.negative?
+
+        maximum = (opts[:max_length] || 2048).to_i.clamp(1, 65_536)
+        length = (opts[:length] || maximum).to_i
+        length = maximum if length <= 0
+        length = [length, maximum].min
         mode = (opts[:mode] || 'text').to_s
         data = File.binread(path, length, offset).to_s
+        encoded = encode_page(bytes: data, mode: mode)
+        total = File.size(path)
+        { handle: opts[:handle], path: path, offset: offset, bytes: data.bytesize, total_bytes: total, next_offset: offset + data.bytesize, eof: offset + data.bytesize >= total }.merge(encoded)
+      end
+
+      # Match complete binary lines so page boundaries never hide a match.
+      # Bound returned previews separately from the regex input.
+      public_class_method def self.grep(opts = {})
+        path = artifact_path(opts)
+        raise 'ERROR: path is required' if path.empty?
+        raise "ERROR: file not found: #{path}" unless File.file?(path)
+
+        offset = opts[:offset].to_i
+        raise ArgumentError, 'offset must be nonnegative' if offset.negative?
+
+        pattern = opts.fetch(:regex).to_s.b
+        raise ArgumentError, 'regex exceeds 2048 bytes' if pattern.bytesize > 2048
+
+        flags = Regexp::NOENCODING | (opts[:ignore_case] ? Regexp::IGNORECASE : 0)
+        rx = Regexp.new(pattern, flags, timeout: 0.05)
+        limit = (opts[:limit] || 50).to_i.clamp(1, 50)
+        remaining = (opts[:max_bytes] || 2048).to_i.clamp(1, 2048)
+        total = File.size(path)
+        cursor = offset
+        matches = []
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 0.25
+        line = offset.zero? ? 1 : nil
+        File.open(path, 'rb') do |file|
+          file.seek([offset - 1, 0].max)
+          midline = offset.positive? && file.read(1) != "\n"
+          file.seek(offset)
+          while cursor < total && cursor - offset < 1_048_576 && matches.length < limit && remaining.positive?
+            break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+            fragment = file.gets("\n", (64 * 1024 * 1024) + 1)
+            break unless fragment
+
+            raise ArgumentError, "line at offset #{cursor} exceeds 64 MiB; inspect with artifact_read" if fragment.bytesize > 64 * 1024 * 1024
+
+            match = rx.match(fragment)
+            if match
+              start = fragment.bytesize <= remaining ? 0 : [match.begin(0) - 16, 0].max
+              preview = fragment.byteslice(start, remaining)
+              encoded = encode_page(bytes: preview, mode: 'text')
+              matches << { offset: cursor + match.begin(0), fragment_offset: cursor + start, bytes: preview.bytesize, line: line, text: encoded[:body], encoding: encoded[:encoding], continued: start + preview.bytesize < fragment.bytesize, starts_midline: midline || start.positive? }
+              remaining -= preview.bytesize
+            end
+            cursor = file.pos
+            line += 1 if line && fragment.end_with?("\n")
+            midline = false
+          end
+        end
+        { handle: opts[:handle], path: path, matches: matches, offset: offset, next_offset: cursor, total_bytes: total, scanned_bytes: cursor - offset, eof: cursor >= total, semantics: 'binary_lines' }
+      end
+
+      # Resolve an opaque handle without returning its potentially large body.
+      public_class_method def self.resolve(opts = {})
+        handle = opts[:handle]
+        raise ArgumentError, 'artifact handle is required' unless handle.is_a?(String) && !handle.empty?
+
+        expected = opts[:sha256]
+        raise ArgumentError, 'expected sha256 must be 64 lowercase hex digits' if expected && (!expected.is_a?(String) || !expected.match?(/\A[0-9a-f]{64}\z/))
+
+        path = artifact_path(handle: handle)
+        raise ArgumentError, 'artifact handle must resolve to a readable file' unless File.file?(path) && File.readable?(path)
+
+        sha = Digest::SHA256.file(path).hexdigest
+        declared = handle.match?(/\A(?:sha256:)?[0-9a-f]{64}\z/) ? handle.delete_prefix('sha256:') : File.basename(handle, '.bin')
+        raise ArgumentError, 'artifact handle digest mismatch' unless sha.start_with?(declared)
+
+        raise ArgumentError, 'artifact sha256 mismatch' if expected && expected != sha
+
+        { handle: handle, path: path, sha256: sha, size: File.size(path) }
+      end
+
+      private_class_method def self.artifact_path(opts = {})
+        handle = opts[:handle]
+        return (opts[:path] || opts[:ref]).to_s if handle.nil?
+
+        if handle.is_a?(String) && handle.match?(/\A(?:sha256:)?[0-9a-f]{64}\z/)
+          sha = handle.delete_prefix('sha256:')
+          handle = "sha256/#{sha[0, 2]}/#{sha}"
+        else
+          raise ArgumentError, 'invalid artifact handle' unless handle.is_a?(String) && handle.match?(%r{\A[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}/[0-9a-f]{8}\.bin\z})
+        end
+
+        path = File.join(ROOT, handle)
+        [ROOT, File.join(ROOT, handle.split('/').first), File.dirname(path), path].each do |entry|
+          raise ArgumentError, 'artifact handle contains a symlink' if File.symlink?(entry)
+        end
+        path
+      end
+
+      private_class_method def self.encode_page(opts = {})
+        data = opts[:bytes].dup.force_encoding(Encoding::UTF_8)
+        mode = opts[:mode].to_s
+        raise ArgumentError, 'mode must be text, hex, or base64' unless %w[text hex base64].include?(mode)
+
+        mode = 'base64' if mode == 'text' && !data.valid_encoding?
         case mode
         when 'hex'
-          { path: path, offset: offset, bytes: data.bytesize, hex: data.unpack1('H*') }
+          body = data.unpack1('H*')
+          { mode: mode, encoding: 'hex', body: body, hex: body }
         when 'base64'
-          require 'base64'
-          { path: path, offset: offset, bytes: data.bytesize, body: Base64.strict_encode64(data) }
+          { mode: mode, encoding: 'base64', body: Base64.strict_encode64(data) }
         else
-          { path: path, offset: offset, bytes: data.bytesize, body: data.force_encoding('UTF-8').scrub }
+          { mode: mode, encoding: 'UTF-8', body: data }
         end
       end
 
@@ -106,7 +238,7 @@ module PWN
           f.flock(File::LOCK_EX)
           f.puts(JSON.generate(sha256: sha, size: bytes.bytesize, tool: opts[:tool], session: opts[:session_id], kind: opts[:kind], tags: Array(opts[:tags]), created_at: Time.now.utc.iso8601, source_path: src, dest: dest))
         end
-        { sha256: sha, path: dest, size: bytes.bytesize, tags: Array(opts[:tags]) }
+        { handle: "sha256:#{sha}", sha256: sha, path: dest, size: bytes.bytesize, tags: Array(opts[:tags]) }
       end
 
       public_class_method def self.authors
@@ -146,14 +278,48 @@ module PWN
             tags: 'optional - Array of short labels for this artifact'
           )
 
-          # Page an artifact; grep: searches lines, ref: alias for path.
+          # Resolve a handle to host-computed evidence metadata without loading its body.
+          #{self}.resolve(
+            handle: 'required - session/sha8.bin, sha256:fullhash, or legacy fullhash artifact handle',
+            sha256: 'optional - expected full SHA-256 to validate against stored bytes'
+          )
+
+          # Spill exact bytes privately; returns handle, path, full sha256 and bytes.
+          #{self}.spill(
+            bytes: 'required - raw String bytes, never scrubbed or truncated',
+            session_id: 'required - 1-128 ASCII letters/digits/underscore/dot/hyphen; first character cannot be dot'
+          )
+
+          # Search complete binary lines with first match per line and bounded previews.
+          # Lines over 64 MiB raise an explicit error; inspect those with artifact_read.
+          # Scan budget is 1 MiB between lines; a complete line may exceed that budget.
+          # Regex timeout is 50ms (raises Regexp::TimeoutError); scan budget is 250ms.
+          # Resume next_offset until eof, even with no matches. Newlines are retained.
+          # Match offset is absolute bytes; preview starts at fragment_offset and may be base64.
+          # continued marks a shortened preview; line is nil for nonzero start offsets.
+          #{self}.grep(
+            handle: 'optional - session/sha8.bin handle instead of path',
+            path: 'optional - legacy file path when handle is omitted',
+            ref: 'optional - alias for path',
+            regex: 'required - binary regex source, at most 2048 bytes',
+            offset: 'optional - nonnegative byte offset, default 0',
+            limit: 'optional - matching lines per page, clamped to 1-50',
+            max_bytes: 'optional - total raw preview bytes per page, clamped to 1-2048',
+            ignore_case: 'optional - case insensitive matching, default false'
+          )
+
+          # Page exact artifact bytes; invalid UTF-8 pages automatically use base64.
+          # Returns handle/path, offset, bytes, total_bytes, next_offset, eof, mode, encoding, body.
+          # Follow next_offset until eof; hex also retains the legacy hex field.
           #{self}.read_page(
-            path: 'required - filesystem path of the artifact',
+            handle: 'optional - session/sha8.bin handle instead of path',
+            path: 'optional - filesystem path when handle is omitted',
             ref: 'optional - alias for path',
             offset: 'optional - byte offset (defaults to 0)',
-            length: 'optional - byte count (defaults to 16384)',
+            length: 'optional - byte count, capped at max_length (default 2048)',
+            max_length: 'optional - configured page cap, clamped to 1-65536 bytes, default 2048',
             mode: 'optional - text, hex, or base64 (defaults to text)',
-            grep: 'optional - regex to search instead of paging',
+            grep: 'optional - legacy case-insensitive bounded line search instead of paging',
             sha256: 'optional - expected sha256 of the file'
           )
 

data/lib/pwn/plugins/assembly.rb

@@ -198,8 +198,46 @@ module PWN
         raise e
       end
 
-      # Supported Method Parameters::
-      # PWN::Plugins::Assembly.list_archs
+      public_class_method def self.assemble(opts = {})
+        asm = opts[:asm].to_s
+        raise 'ERROR: asm is required' if asm.empty?
+
+        if opts[:engine].to_s != 'metasm' && PWN::FFI.available?(mod: :Keystone)
+          begin
+            return PWN::FFI::Keystone.assemble(opts)
+          rescue StandardError
+            nil
+          end
+        end
+
+        arch_obj = arch_object(opts)
+        bytes = Metasm::Shellcode.assemble(arch_obj, asm).encode_string
+        { engine: 'metasm', bytes: bytes, hex: bytes.unpack1('H*'), count: bytes.bytesize }
+      end
+
+      public_class_method def self.disassemble(opts = {})
+        raw = opts[:bytes] || opts[:opcodes]
+        raise 'ERROR: bytes is required' if raw.to_s.empty?
+
+        if opts[:engine].to_s != 'metasm' && PWN::FFI.available?(mod: :Capstone)
+          begin
+            row = PWN::FFI::Capstone.disassemble(opts)
+            return row if Array(row[:insns]).any?
+          rescue StandardError
+            nil
+          end
+        end
+
+        arch_obj = arch_object(opts)
+        text = Metasm::Shellcode.disassemble(arch_obj, raw.to_s.b).to_s
+        insns = text.lines.filter_map do |line|
+          match = line.match(/^\s*(?:0x)?([0-9a-f]+)\s+(\S+)\s*(.*)$/i)
+          next unless match
+
+          { address: match[1].to_i(16), mnemonic: match[2], op_str: match[3].to_s.strip }
+        end
+        { engine: 'metasm', insns: insns, count: insns.length, text: text }
+      end
 
       public_class_method def self.list_supported_archs
         [
@@ -267,6 +305,25 @@ module PWN
             endian: 'optional - endianess :big|:little (defaults to current system endianess)'
           )
 
+          # Assemble instructions via Keystone FFI when present, else Metasm.
+          #{self}.assemble(
+            asm: 'required - assembly source (one instruction per line)',
+            arch: 'optional - architecture string (as from objdump --info)',
+            endian: 'optional - :little or :big byte order',
+            engine: 'optional - assembler backend keystone when libkeystone loads, otherwise metasm',
+            address: 'optional - start address'
+          )
+
+          # Disassemble bytes via Capstone FFI when present, else Metasm.
+          #{self}.disassemble(
+            bytes: 'required - raw machine-code bytes',
+            opcodes: 'optional - alias for bytes',
+            arch: 'optional - architecture string (as from objdump --info)',
+            endian: 'optional - :little or :big byte order',
+            engine: 'optional - disassembler backend capstone when libcapstone loads, otherwise metasm',
+            address: 'optional - start address'
+          )
+
           # Run list supported archs and return its result
           #{self}.list_supported_archs
 
@@ -275,6 +332,20 @@ module PWN
         "
         constants.sort
       end
+
+      private_class_method def self.arch_object(opts = {})
+        arch = (opts[:arch] || PWN::Plugins::DetectOS.arch).to_s
+        endian = opts[:endian] || PWN::Plugins::DetectOS.endian
+        endian = endian.to_sym
+        case arch.downcase
+        when 'i386', 'i686', 'x86' then Metasm::Ia32.new(endian)
+        when 'amd64', 'x86_64' then Metasm::X86_64.new(endian)
+        when 'aarch64', 'arm64' then Metasm::ARM64.new(endian)
+        when /arm/ then Metasm::ARM.new(endian)
+        else
+          raise "Unsupported architecture: #{arch}"
+        end
+      end
     end
   end
 end

data/lib/pwn/plugins/basic_auth.rb

@@ -14,8 +14,17 @@ module PWN
       # )
 
       public_class_method def self.encode(opts = {})
-        basic_user = opts[:username].to_s.chomp unless opts[:username].nil?
-        basic_pass = opts[:password].to_s.chomp unless opts[:password].nil?
+        basic_user = opts[:username]
+        basic_pass = opts[:password]
+        if (basic_user.nil? || basic_pass.nil?) && !opts[:host].to_s.empty?
+          hit = Array(PWN::Plugins::Vault.offer(host: opts[:host], service: opts[:service], engagement: opts[:engagement] || opts[:engagement_id])).first
+          if hit
+            basic_user = hit[:username] if basic_user.nil?
+            basic_pass = hit[:secret] if basic_pass.nil?
+          end
+        end
+        basic_user = basic_user.to_s.chomp unless basic_user.nil?
+        basic_pass = basic_pass.to_s.chomp unless basic_pass.nil?
         base64_str = "#{basic_user}:#{basic_pass}"
         @base64_encoded_auth = Base64.strict_encode64(base64_str).to_s.chomp
         @base64_encoded_auth
@@ -50,8 +59,12 @@ module PWN
         puts "USAGE:
           # Run encode and return its result
           #{self}.encode(
-            username: 'optional - optional username',
-            password: 'optional - optional password'
+            username: 'optional - username; omitted values are filled from Vault.offer',
+            password: 'optional - password; omitted values are filled from Vault.offer',
+            host: 'optional - hostname used to offer recon loot when username or password is omitted',
+            service: 'optional - service name such as http or ssh used to match loot',
+            engagement: 'optional - engagement id scoping the loot file (defaults to default)',
+            engagement_id: 'optional - alias for engagement'
           )
 
           # Run decode and return its result