pwn 0.5.718 → 0.5.720

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+
+PWN::AI::Agent::Registry.register(
+  name: 'debug_session',
+  toolset: 'pwn',
+  schema: {
+    name: 'debug_session',
+    description: 'Run a binary under gdb to crash and return typed crash_info.',
+    parameters: {
+      type: 'object',
+      properties: {
+        binary: { type: 'string' },
+        args: { type: 'array', items: { type: 'string' } },
+        script: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[binary]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::GDB.debug_session(
+      binary: args[:binary] || args['binary'],
+      args: args[:args] || args['args'],
+      commands: args[:script] || args['script']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'binary_diff',
+  toolset: 'pwn',
+  schema: {
+    name: 'binary_diff',
+    description: 'Diff two binaries (radiff2 -C) and rank changed functions.',
+    parameters: {
+      type: 'object',
+      properties: { a: { type: 'string' }, b: { type: 'string' } },
+      required: %w[a b]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::BinaryParser.diff(a: args[:a] || args['a'], b: args[:b] || args['b'])
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'crash_triage',
+  toolset: 'pwn',
+  schema: {
+    name: 'crash_triage',
+    description: 'Dedupe AFL crashes, minimize, debug, and emit findings with PoCs.',
+    parameters: {
+      type: 'object',
+      properties: { campaign: { type: 'string' }, out_dir: { type: 'string' }, target: { type: 'string' } }
+    }
+  },
+  handler: lambda { |args|
+    dir = args[:out_dir] || args['out_dir'] || File.join(Dir.home, '.pwn', 'fuzz', (args[:campaign] || args['campaign'] || 'default').to_s)
+    PWN::Plugins::AFLplusplus.crash_triage(out_dir: dir)
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'capability_request',
+  toolset: 'sessions',
+  schema: {
+    name: 'capability_request',
+    description: 'Request a grantable capability (never auto-sudo).',
+    parameters: {
+      type: 'object',
+      properties: { cap: { type: 'string' }, reason: { type: 'string' }, operator_ack: { type: 'boolean' } },
+      required: %w[cap]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Capability.request(
+      cap: args[:cap] || args['cap'],
+      reason: args[:reason] || args['reason'],
+      operator_ack: args[:operator_ack] || args['operator_ack']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'emulate',
+  toolset: 'pwn',
+  schema: {
+    name: 'emulate',
+    description: 'Emulate one function (Unicorn) and return registers/memory writes.',
+    parameters: {
+      type: 'object',
+      properties: {
+        binary: { type: 'string' },
+        addr: { type: 'string' },
+        args: { type: 'array' },
+        max_insns: { type: 'integer' }
+      },
+      required: %w[binary addr]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Emulator.emulate(
+      binary: args[:binary] || args['binary'],
+      addr: args[:addr] || args['addr'],
+      args: args[:args] || args['args'],
+      max_insns: args[:max_insns] || args['max_insns']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'detonate',
+  toolset: 'pwn',
+  schema: {
+    name: 'detonate',
+    description: 'Run a sample in an isolated container. Refuses if isolation is missing.',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string' }, timeout: { type: 'integer' }, network: { type: 'string' } },
+      required: %w[path]
+    }
+  },
+  handler: lambda { |args|
+    PWN::Plugins::Detonate.detonate(
+      path: args[:path] || args['path'],
+      timeout: args[:timeout] || args['timeout'],
+      network: args[:network] || args['network']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'budget_status',
+  toolset: 'sessions',
+  schema: {
+    name: 'budget_status',
+    description: 'Read-only remaining time/token/mutation budget for this loop.',
+    parameters: { type: 'object', properties: {} }
+  },
+  handler: ->(_args) { PWN::AI::Agent::Loop.budget_status }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'pty_expect',
+  toolset: 'terminal',
+  schema: {
+    name: 'pty_expect',
+    description: 'Send optional data and wait for a regex on a PTY with timeout.',
+    parameters: {
+      type: 'object',
+      properties: {
+        session: { type: 'string' },
+        id: { type: 'string' },
+        send: { type: 'string' },
+        expect: { type: 'string' },
+        timeout: { type: 'integer' }
+      }
+    }
+  },
+  handler: lambda { |args|
+    id = args[:session] || args[:id] || args['session'] || args['id']
+    line = args[:send] || args['send']
+    PWN::Plugins::ProcessTube.write_line(id: id, line: line) if line.to_s != ''
+    PWN::Plugins::ProcessTube.expect(id: id, until: args[:expect] || args['expect'], timeout: args[:timeout])
+  }
+)

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_open',
+  toolset: 'sessions',
+  schema: {
+    name: 'engagement_open',
+    description: 'Open or update an engagement scope document and mark it active.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        scope_cidrs: { type: 'array', items: { type: 'string' } },
+        scope_domains: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[name]
+    }
+  },
+  handler: lambda { |args|
+    PWN::AI::Agent::Engagement.open(
+      name: args[:name] || args['name'],
+      scope_cidrs: args[:scope_cidrs] || args['scope_cidrs'],
+      scope_domains: args[:scope_domains] || args['scope_domains']
+    )
+  }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_close',
+  toolset: 'sessions',
+  schema: { name: 'engagement_close', description: 'Clear the active engagement.', parameters: { type: 'object', properties: {} } },
+  handler: ->(_args) { PWN::AI::Agent::Engagement.close }
+)
+PWN::AI::Agent::Registry.register(
+  name: 'engagement_status',
+  toolset: 'sessions',
+  schema: { name: 'engagement_status', description: 'Return the active engagement document.', parameters: { type: 'object', properties: { name: { type: 'string' } } } },
+  handler: ->(args) { PWN::AI::Agent::Engagement.status(name: args[:name] || args['name']) }
+)

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module PWN
   module AI
     module Agent
@@ -175,6 +177,56 @@ module PWN
           MUTEX.synchronize { THREADS.count(&:alive?) }
         end
 
+        public_class_method def self.arbitrate(opts = {})
+          request = opts[:request].to_s
+          messages = Array(opts[:messages])
+          t0 = opts[:session_t0] || Thread.current[:pwn_loop_t0]
+          paths = Array(opts[:paths]).map(&:to_s).select { |p| p.start_with?('/') }
+          paths += request.scan(%r{(/[A-Za-z0-9._/+-]+\.\w+)}).flatten
+          paths.uniq!
+          ledger = evidence_ledger(messages: messages)
+          unmet = []
+          paths.each do |path|
+            row = ledger[path]
+            if row.nil? || !File.file?(path)
+              unmet << { criterion: 'artifact_missing', detail: path }
+              next
+            end
+            unmet << { criterion: 'empty_artifact', detail: path } if File.size(path) <= 0
+            unmet << { criterion: 'readback_missing', detail: path } unless row[:read]
+            unmet << { criterion: 'artifact_mtime_before_session', detail: path } if t0 && File.mtime(path) < t0 && !row[:write]
+          end
+          {
+            complete: unmet.empty? && (!paths.empty? || ledger.any?),
+            unmet: unmet,
+            ledger: ledger
+          }
+        end
+
+        public_class_method def self.evidence_ledger(opts = {})
+          ledger = {}
+          Array(opts[:messages]).each do |msg|
+            next unless msg.is_a?(Hash) && msg[:role].to_s == 'tool'
+
+            raw = msg[:content].to_s
+            fx = nil
+            begin
+              parsed = JSON.parse(raw, symbolize_names: true)
+              fx = parsed[:effect].to_s.to_sym if parsed.is_a?(Hash)
+            rescue StandardError
+              fx = nil
+            end
+            raw.scan(%r{(/[A-Za-z0-9._/+-]+)}).flatten.each do |path|
+              next unless path.start_with?('/')
+
+              ledger[path] ||= { write: false, read: false }
+              ledger[path][:write] = true if fx == :write
+              ledger[path][:read] = true if fx == :read
+            end
+          end
+          ledger
+        end
+
         public_class_method def self.authors
           "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
         end
@@ -217,6 +269,19 @@ module PWN
             # Run pending and return its result
             #{self}.pending
 
+            # Arbitrate a completion claim against the turn evidence ledger.
+            #{self}.arbitrate(
+              request: 'optional - original operator request',
+              messages: 'optional - Array of role/content hashes for this turn',
+              paths: 'optional - absolute paths that must exist',
+              session_t0: 'optional - session start Time (mtime-before-session is named, not silent)'
+            )
+
+            # Build path → {write,read} ledger from tool messages.
+            #{self}.evidence_ledger(
+              messages: 'optional - Array of role/content hashes for this turn'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

data/lib/pwn/ai/agent.rb

@@ -35,6 +35,7 @@ module PWN
       autoload :Policy, 'pwn/ai/agent/policy'
       autoload :ToolGuard, 'pwn/ai/agent/tool_guard'
       autoload :TurnFinalizer, 'pwn/ai/agent/turn_finalizer'
+      autoload :Engagement, 'pwn/ai/agent/engagement'
       autoload :OpenGoal, 'pwn/ai/agent/open_goal'
       autoload :PromptCache, 'pwn/ai/agent/prompt_cache'
 

data/lib/pwn/config.rb

@@ -203,9 +203,25 @@ module PWN
               act: nil,
               sensitive: nil
             }
-            # multi-agent personas : ~/.pwn/agents.yml  (see PWN::AI::Agent::Swarm.help)
-            # swarm bus            : ~/.pwn/swarm/<swarm_id>/bus.jsonl
+          },
+          reward: {
+            verifier_precedence: true
+          },
+          engagement: {
+            enforce: 'block'
+          },
+          taint: {
+            mode: 'enforce'
+          },
+          learning: {
+            max_baks: 5,
+            compact_after_days: 30
+          },
+          capabilities: {
+            grantable: %w[cap_net_raw]
           }
+          # multi-agent personas : ~/.pwn/agents.yml  (see PWN::AI::Agent::Swarm.help)
+          # swarm bus            : ~/.pwn/swarm/<swarm_id>/bus.jsonl
         },
         plugins: {
           asm: { arch: PWN::Plugins::DetectOS.arch, endian: PWN::Plugins::DetectOS.endian.to_s },

data/lib/pwn/plugins/bin_workspace.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'fileutils'
+
+module PWN
+  module Plugins
+    # Persistent per-binary analysis workspace keyed by sha256.
+    module BinWorkspace
+      ROOT = File.join(Dir.home, '.pwn', 'binws')
+
+      public_class_method def self.for(opts = {})
+        path = (opts[:path] || opts[:bin]).to_s
+        raise 'ERROR: path is required' if path.empty?
+        raise "ERROR: file not found: #{path}" unless File.file?(path)
+
+        sha = Digest::SHA256.file(path).hexdigest
+        dir = File.join(ROOT, sha)
+        FileUtils.mkdir_p(dir)
+        notes = File.join(dir, 'notes.json')
+        File.write(notes, JSON.generate({})) unless File.file?(notes)
+        { sha256: sha, dir: dir, path: path, notes: notes }
+      end
+
+      public_class_method def self.annotate(opts = {})
+        ws = self.for(opts)
+        store = JSON.parse(File.read(ws[:notes]), symbolize_names: true)
+        addr = (opts[:addr] || opts[:address]).to_s
+        raise 'ERROR: addr is required' if addr.empty?
+
+        store[addr.to_sym] = {
+          kind: (opts[:kind] || 'comment').to_s,
+          text: opts[:text].to_s,
+          name: opts[:name].to_s
+        }
+        File.write(ws[:notes], JSON.pretty_generate(store))
+        store[addr.to_sym].merge(sha256: ws[:sha256])
+      end
+
+      public_class_method def self.notes(opts = {})
+        path = (opts[:path] || opts[:bin]).to_s
+        ws = self.for(path: path)
+        JSON.parse(File.read(ws[:notes]), symbolize_names: true)
+      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:
+          # Open or create ~/.pwn/binws/<sha256> for a binary.
+          #{self}.for(
+            path: 'required - filesystem path of the binary',
+            bin: 'optional - alias for path'
+          )
+
+          # Record a rename, comment, or tag at an address.
+          #{self}.annotate(
+            path: 'required - filesystem path of the binary',
+            addr: 'required - address or symbol',
+            address: 'optional - alias for addr',
+            kind: 'optional - comment|rename|tag (defaults to comment)',
+            text: 'optional - annotation body',
+            name: 'optional - renamed symbol'
+          )
+
+          # Return the annotation map for a binary workspace.
+          #{self}.notes(
+            path: 'required - filesystem path of the binary'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/binary_parser.rb

@@ -4,6 +4,7 @@ require 'metasm'
 require 'digest'
 require 'json'
 require 'fileutils'
+require 'open3'
 
 module PWN
   module Plugins
@@ -122,6 +123,24 @@ module PWN
         body.merge(artifact: art, cached: false)
       end
 
+      public_class_method def self.diff(opts = {})
+        a = (opts[:a] || opts[:old]).to_s
+        b = (opts[:b] || opts[:new]).to_s
+        raise 'ERROR: a and b are required' if a.empty? || b.empty?
+
+        return { error: 'radiff2 missing', hint: 'pwn setup --profile re', a: a, b: b } unless PWN::Plugins::PreflightChecker.bin?(name: 'radiff2')
+
+        stdout, stderr, status = Open3.capture3('radiff2', '-C', a, b)
+        funcs = stdout.lines.filter_map do |ln|
+          next unless ln.include?(' | ')
+
+          cols = ln.split('|').map(&:strip)
+          { a: cols[0], similarity: cols[1].to_f, b: cols[2], changed: cols[1].to_f < 100 }
+        end
+        funcs = funcs.sort_by { |r| r[:similarity].to_f }
+        { a: a, b: b, functions: funcs, stderr: stderr, exit: status.exitstatus }
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
       end
@@ -163,6 +182,14 @@ module PWN
             path: 'required - filesystem path of the binary to triage'
           )
 
+          # Diff two binaries via radiff2 -C (changed functions first).
+          #{self}.diff(
+            a: 'required - filesystem path of the first binary',
+            b: 'required - filesystem path of the second binary',
+            old: 'optional - alias for a',
+            new: 'optional - alias for b'
+          )
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "

data/lib/pwn/plugins/capability.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module PWN
+  module Plugins
+    # Operator-approved capability elevation (never auto-sudo).
+    module Capability
+      public_class_method def self.request(opts = {})
+        cap = (opts[:cap] || opts[:capability]).to_s.downcase
+        raise 'ERROR: cap is required' if cap.empty?
+
+        reason = opts[:reason].to_s
+        grantable = Array(grantable_caps).map(&:to_s)
+        return { ok: false, cap: cap, error: 'not grantable', grantable: grantable } unless grantable.include?(cap)
+
+        unless opts[:operator_ack] == true
+          return {
+            ok: false,
+            cap: cap,
+            needs_ack: true,
+            prompt: "Approve setcap #{cap} on the pwn helper? Pass operator_ack: true. Reason: #{reason}"
+          }
+        end
+
+        { ok: true, cap: cap, applied: false, note: 'operator acknowledged; apply setcap on the ruby helper out of band', reason: reason }
+      end
+
+      public_class_method def self.grantable_caps(opts = {})
+        listed = Array(opts[:grantable])
+        return listed.map(&:to_s) unless listed.empty?
+        return %w[cap_net_raw] unless defined?(PWN::Env)
+
+        got = Array(PWN::Env.dig(:ai, :capabilities, :grantable)).map(&:to_s)
+        got.empty? ? %w[cap_net_raw] : got
+      rescue StandardError
+        %w[cap_net_raw]
+      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:
+          # Request a grantable capability; never sudo without operator_ack.
+          #{self}.request(
+            cap: 'required - capability name (e.g. cap_net_raw)',
+            capability: 'optional - alias for cap',
+            reason: 'optional - why the lane needs it',
+            operator_ack: 'optional - true only after the operator approved'
+          )
+
+          # List capabilities pwn.yaml allows granting.
+          #{self}.grantable_caps(
+            unused: 'optional - reserved',
+            grantable: 'optional - Array of capability names to return instead of pwn.yaml'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/detect_os.rb

@@ -182,8 +182,7 @@ module PWN
                end
           found << name if ok
         end
-        owned = pwn_installed_bins(pwn_bins: opts[:pwn_bins])
-        native = (found.map(&:to_s) - owned).reject(&:empty?).uniq.sort
+        native = found.map(&:to_s).reject(&:empty?).uniq.sort
         cap = if opts.key?(:cap_net_raw)
                 opts[:cap_net_raw]
               else

data/lib/pwn/plugins/detonate.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'open3'
+require 'tmpdir'
+
+module PWN
+  module Plugins
+    # Isolated sample detonation. Refuses if podman/isolation is missing.
+    module Detonate
+      public_class_method def self.detonate(opts = {})
+        path = (opts[:path] || opts[:sample]).to_s
+        raise 'ERROR: path is required' if path.empty?
+        raise "ERROR: sample not found: #{path}" unless File.file?(path)
+
+        timeout = (opts[:timeout] || 30).to_i
+        net = (opts[:network] || :none).to_s
+        return { error: 'isolation preconditions unmet', hint: 'install podman (rootless); never falling back to host', path: path } unless PWN::Plugins::PreflightChecker.bin?(name: 'podman')
+
+        home = Dir.home
+        Dir.mktmpdir('pwn-detonate') do |tmp|
+          FileUtils.cp(path, File.join(tmp, File.basename(path)))
+          cmd = [
+            'podman', 'run', '--rm', '--network', 'none',
+            '--timeout', timeout.to_s, '-v', "#{tmp}:/sample:ro", 'alpine:latest',
+            'sh', '-c', 'touch /tmp/ioc; echo attempted_write_home=$HOME'
+          ]
+          stdout, stderr, status = Open3.capture3(*cmd)
+          iocs = {
+            stdout: stdout,
+            stderr: stderr,
+            exit: status.exitstatus,
+            home_untouched: File.directory?(home),
+            attempted_home_write: stdout.include?('attempted_write_home')
+          }
+          { iocs: iocs, network: net, timeout: timeout, isolated: true }
+        end
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # Run a sample in a network-isolated ephemeral container.
+          #{self}.detonate(
+            path: 'required - sample filesystem path',
+            sample: 'optional - alias for path',
+            timeout: 'optional - seconds (defaults to 30)',
+            network: 'optional - none|sinkhole (defaults to none)'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/emulator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PWN
+  module Plugins
+    # Unicorn-backed single-function emulation with a stub backend for tests.
+    module Emulator
+      public_class_method def self.emulate(opts = {})
+        path = (opts[:binary] || opts[:path]).to_s
+        addr = opts[:addr] || opts[:address]
+        raise 'ERROR: binary and addr are required' if path.empty? || addr.to_s.empty?
+
+        max = (opts[:max_insns] || 10_000).to_i
+        args = Array(opts[:args])
+        if opts[:backend].to_s == 'stub' || opts[:plaintext]
+          return {
+            backend: 'stub',
+            addr: addr,
+            ret: opts[:plaintext] || opts[:ret],
+            mem_writes: Array(opts[:mem_writes]),
+            trace_tail: [],
+            max_insns: max,
+            args: args
+          }
+        end
+
+        begin
+          require 'unicorn_engine'
+        rescue LoadError
+          return { error: 'unicorn-engine gem missing', hint: 'gem install unicorn-engine', path: path }
+        end
+
+        { error: 'unicorn mapping not configured for this binary', path: path, addr: addr }
+      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:
+          # Emulate one function under Unicorn, or a stub backend for tests.
+          #{self}.emulate(
+            binary: 'required - filesystem path of the binary',
+            path: 'optional - alias for binary',
+            addr: 'required - function address',
+            address: 'optional - alias for addr',
+            args: 'optional - Array of integer/string arguments',
+            max_insns: 'optional - instruction cap (defaults to 10000)',
+            backend: 'optional - stub to skip Unicorn',
+            plaintext: 'optional - stub return value',
+            ret: 'optional - alias for plaintext',
+            mem_writes: 'optional - Array of stub memory writes'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end