pwn 0.5.708 → 0.5.710

data/lib/pwn/migrate.rb

@@ -679,40 +679,50 @@ module PWN
 
     public_class_method def self.help
       puts "USAGE:
-        # Is ~/.pwn older than this pwn release's schema?
-        #{self}.needed?             # => true/false (cheap; used by refresh_env)
+        # Run installed schema and return its result
+        #{self}.installed_schema
 
-        # Read-only per-file compatibility report.
-        #{self}.status              # => { schema_installed:, schema_current:, files:[…], incompatible:[…] }
-        #{self}.check               # human-readable to $stdout
+        # Run needed and return its result
+        #{self}.needed?
 
-        # Apply schema migrations + (optionally) autofix incompatible files.
-        # Always takes a timestamped backup under ~/.pwn/backup/<ts>/ first.
+        # Run status and return its result
+        #{self}.status
+
+        # Human-readable ~/.pwn state doctor.  Read-only.  Called from
+        #{self}.check(
+          io: 'optional - IO to write the report to (default $stdout)'
+        )
+
+        # Run run and return its result
         #{self}.run(
-          fix:     'optional - also autofix per-file (default false)',
-          backup:  'optional - default true',
-          dry_run: 'optional - default false',
-          key:     'optional - vault key (default: ~/.pwn/pwn.yaml.decryptor)',
-          iv:      'optional - vault iv'
+          fix: 'optional - also autofix incompatible files (default: schema-migrations only)',
+          backup: 'optional - take timestamped backup of ~/.pwn first (default true)',
+          dry_run: 'optional - report what WOULD happen, write nothing (default false)',
+          key: 'optional - vault key   (default: read ~/.pwn/pwn.yaml.decryptor)',
+          iv: 'optional - vault iv    (default: read ~/.pwn/pwn.yaml.decryptor)',
+          io: 'optional - IO to write to (default $stdout)'
         )
 
-        # pwn.yaml specifically — deep-merge missing keys from the
-        # current release template UNDER the user's values, re-encrypt.
-        #{self}.vault_drift         # => { missing: [dotted.paths], … } or nil
-        #{self}.backfill_vault
+        # Run vault drift and return its result
+        #{self}.vault_drift(
+          key: 'optional - vault key, iv: optional - vault iv'
+        )
 
-        # Data:
-        #{self}::SCHEMA_VERSION     # bump when a ~/.pwn file shape changes
-        #{self}::STATE_FILES        # rel-path → owner → verifier → fix
-        #{self}::MIGRATIONS         # ordered idempotent transforms
+        # Run backfill vault and return its result
+        #{self}.backfill_vault(
+          key: 'optional - optional, iv: optional, dry_run: false, io: $stdout',
+          io: 'optional - io value consumed by #backfill_vault',
+          dry_run: 'optional - dry run value consumed by #backfill_vault',
+          iv: 'optional - iv value consumed by #backfill_vault'
+        )
 
-        # From the shell:
-        pwn setup --migrate                # == #{self}.run
-        pwn setup --migrate --fix          # == #{self}.run(fix: true)
-        pwn setup --migrate --dry-run
+        # Run env template and return its result
+        #{self}.env_template
 
+        # Print the AUTHOR(S) string for this module.
         #{self}.authors
       "
+      constants.sort
     end
   end
 end

data/lib/pwn/module_skills.rb

@@ -435,14 +435,45 @@ module PWN
     end
 
     public_class_method def self.help
-      puts <<~USAGE
-        USAGE:
-          #{self}.enumerate
-          #{self}.refresh!
-          #{self}.drift
-          #{self}.install(pwn_skills_path: '~/.pwn/skills')
-          #{self}.authors
-      USAGE
+      puts "USAGE:
+        # Run enumerate and return its result
+        #{self}.enumerate(
+          lib_root: 'optional - lib root value consumed by #enumerate'
+        )
+
+        # Run relpath and return its result
+        #{self}.relpath(
+          source: 'optional - source value consumed by #relpath',
+          const: 'optional - const value consumed by #relpath'
+        )
+
+        # Run render and return its result
+        #{self}.render(
+          module: 'optional - module value consumed by #render (defaults to opts)'
+        )
+
+        # Run refresh and return its result
+        #{self}.refresh!(
+          dest: 'required - dest value consumed by #refresh!',
+          lib_root: 'optional - lib root value consumed by #refresh!'
+        )
+
+        # Run drift and return its result
+        #{self}.drift(
+          dest: 'required - dest value consumed by #drift',
+          lib_root: 'optional - lib root value consumed by #drift'
+        )
+
+        # Run install and return its result
+        #{self}.install(
+          pwn_skills_path: 'required - pwn skills path value consumed by #install',
+          source: 'optional - source value consumed by #install'
+        )
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
+      constants.sort
     end
   end
 end

data/lib/pwn/plugins/aflplusplus.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'digest'
+
+module PWN
+  module Plugins
+    # AFL++ campaign wrapper.
+    module AFLplusplus
+      public_class_method def self.required_bins
+        %w[afl-fuzz]
+      end
+
+      public_class_method def self.fuzz(opts = {})
+        PWN::Plugins::PreflightChecker.require_bin!(name: 'afl-fuzz')
+        in_dir = opts[:in_dir] || opts[:corpus]
+        out_dir = opts[:out_dir] || opts[:output]
+        target = opts[:target]
+        raise 'ERROR: in_dir, out_dir, and target are required' if in_dir.to_s.empty? || out_dir.to_s.empty? || target.to_s.empty?
+
+        cmd = ['afl-fuzz', '-i', in_dir.to_s, '-o', out_dir.to_s, '--', target.to_s]
+        cmd.concat(Array(opts[:args]))
+        stdout, stderr, status = Open3.capture3(*cmd)
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus }
+      end
+
+      public_class_method def self.crash_triage(opts = {})
+        out_dir = (opts[:out_dir] || opts[:output]).to_s
+        raise 'ERROR: out_dir is required' if out_dir.empty?
+
+        crashes = Dir[File.join(out_dir, '**/crashes/id:*')]
+        hashes = crashes.map { |p| [p, Digest::SHA256.file(p).hexdigest] }
+        {
+          crashes: crashes,
+          unique: hashes.map(&:last).uniq,
+          asan: crashes.any? { |p| File.binread(p).include?('AddressSanitizer') }
+        }
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # List host binaries this module expects to be installed.
+          #{self}.required_bins
+
+          # Run fuzz and return its result
+          #{self}.fuzz(
+            in_dir: 'required - in dir value consumed by #fuzz (defaults to opts[:corpus])',
+            corpus: 'optional - corpus value consumed by #fuzz',
+            out_dir: 'required - out dir value consumed by #fuzz (defaults to opts[:output])',
+            output: 'optional - output value consumed by #fuzz',
+            target: 'required - hostname, IP, or CIDR to scan',
+            args: 'optional - Array args value consumed by #fuzz'
+          )
+
+          # Dedup AFL++ crash files by sha256 and note AddressSanitizer hits.
+          #{self}.crash_triage(
+            out_dir: 'required - AFL output directory containing crashes/',
+            output: 'optional - alias for out_dir'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end

data/lib/pwn/plugins/android.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require 'fileutils'
+require 'tmpdir'
 module PWN
   module Plugins
     # PWN module used to interact w/ Android Devices
@@ -1275,6 +1277,33 @@ module PWN
         raise e
       end
 
+      public_class_method def self.apk_pipeline(opts = {})
+        apk = opts[:apk].to_s
+        raise 'ERROR: apk is required' if apk.empty?
+
+        out = opts[:out_dir] || File.join(Dir.tmpdir, "pwn-apk-#{Process.pid}")
+        FileUtils.mkdir_p(out)
+        decoded = File.join(out, 'apktool')
+        jadx_out = File.join(out, 'jadx')
+        steps = []
+        if PWN::Plugins::PreflightChecker.bin?(name: 'apktool')
+          system('apktool', 'd', '-f', '-o', decoded, apk)
+          steps << :apktool
+        end
+        if PWN::Plugins::PreflightChecker.bin?(name: 'jadx')
+          FileUtils.mkdir_p(jadx_out)
+          system('jadx', '-d', jadx_out, apk)
+          steps << :jadx
+        end
+        manifest = File.join(decoded, 'AndroidManifest.xml')
+        perms = []
+        if File.file?(manifest)
+          txt = File.read(manifest)
+          perms = txt.scan(/android:name="([^"]+)"/).flatten.grep(/PERMISSION|permission/)
+        end
+        { out_dir: out, steps: steps, apk: apk, permissions: perms, manifest: (File.file?(manifest) ? manifest : nil) }
+      end
+
       # Author(s):: 0day Inc. <support@0dayinc.com>
 
       public_class_method def self.authors
@@ -1287,330 +1316,127 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-
+          # Run adb net connect and return its result
           #{self}.adb_net_connect(
             adb_path: 'required - path to adb binary',
             target: 'required - target host or IP to connect',
             port: 'optional - defaults to tcp 5555'
           )
 
-          adb_response = #{self}.adb_sh(
+          # Run adb sh and return its result
+          #{self}.adb_sh(
             adb_path: 'required - path to adb binary',
-            command: 'adb command to execute'
-            as_root: 'optional - boolean (defaults to false)',
+            command: 'required - adb command to execute',
+            as_root: 'optional - boolean (defaults to false)'
           )
 
+          # Run adb push and return its result
           #{self}.adb_push(
             adb_path: 'required - path to adb binary',
             file: 'required - source file to push',
-            dest: 'required - destination path to push file',
-            as_root: 'optional - boolean (defaults to false)',
+            dest: 'required - destination path to save pushed file',
+            as_root: 'optional - boolean (defaults to false)'
           )
 
+          # Run adb pull and return its result
           #{self}.adb_pull(
             adb_path: 'required - path to adb binary',
             file: 'required - source file to pull',
-            dest: 'required - destination path to pull file',
-            as_root: 'optional - boolean (defaults to false)',
+            dest: 'required - destination path to save pulled file',
+            as_root: 'optional - boolean (defaults to false)'
           )
 
+          # Run take screenshot and return its result
           #{self}.take_screenshot(
             adb_path: 'required - path to adb binary',
             dest: 'optional - destination path to save screenshot file (defaults to /sdcard/screen.png)',
             as_root: 'optional - boolean (defaults to true)'
           )
 
+          # Run screen record and return its result
           #{self}.screen_record(
             adb_path: 'required - path to adb binary',
             dest: 'optional - destination path to save screen record file (defaults to /sdcard/screen.mp4)',
             as_root: 'optional - boolean (defaults to true)'
           )
 
-          installed_apps_arr = #{self}.list_installed_apps(
+          # Run list installed apps and return its result
+          #{self}.list_installed_apps(
             adb_path: 'required - path to adb binary',
-            as_root: 'optional - boolean (defaults to false)',
+            as_root: 'optional - boolean (defaults to false)'
           )
 
-          app_response = #{self}.dumpsys(
+          # Run dumpsys and return its result
+          #{self}.dumpsys(
             adb_path: 'required - path to adb binary',
             app: 'optional - application app to detail otherwise display all (i.e. display info from an android app returned from #list_install_apps method)',
-            as_root: 'optional - boolean (defaults to false)',
+            as_root: 'optional - boolean (defaults to false)'
           )
 
-          app_response = #{self}.open_app(
+          # Run open app and return its result
+          #{self}.open_app(
             adb_path: 'required - path to adb binary',
             app: 'required - application app to run (i.e. open an android app returned from #list_install_apps method)',
             as_root: 'optional - boolean (defaults to false)'
           )
 
+          # Run find hidden codes and return its result
           #{self}.find_hidden_codes(
             adb_path: 'required - path to adb binary',
-            from: 'required - start at keycode #'
+            from: 'required - start at keycode #',
             to: 'required - end at keycode #',
             interact: 'optional - defaults to false'
           )
 
+          # Run swipe and return its result
           #{self}.swipe(
             adb_path: 'required - path to adb binary',
             direction: 'required - direction to swipe (:up|:down|:left|:right)'
           )
 
+          # Run input and return its result
           #{self}.input(
             adb_path: 'required - path to adb binary',
             string: 'required - string to type'
           )
 
+          # see https://developer.android.com/reference/android/view/KeyEvent.html for more info
           #{self}.input_special(
             adb_path: 'required - path to adb binary',
-            event: 'required - special event to invoke (
-              :zoom_in|
-              :zoom_out|
-              :zenkaku_hankaku|
-              :yen|
-              :window|
-              :wakeup|
-              :voice_assist|
-              :tv_zoom_mode|
-              :tv_timer_programming|
-              :tv_terrestrial_digital|
-              :tv_terrestrial_analog|
-              :tv_satellite_teletext|
-              :tv_satellite_service|
-              :tv_satellite|
-              :tv_satellite_bs|
-              :tv_satellite_cs|
-              :tv_radio_service|
-              :tv_power|
-              :tv_number_entry|
-              :tv_network|
-              :tv_media_context_menu|
-              :tv_input_vga1|
-              :tv_input_hdmi1|
-              :tv_input_hdmi2|
-              :tv_input_hdmi3|
-              :tv_input_hdmi4|
-              :tv_input_composite1|
-              :tv_input_composite2|
-              :tv_input_component1|
-              :tv_input_component2|
-              :tv_input|
-              :tv_data_service|
-              :tv_contents_menu|
-              :tv_audio_desc|
-              :tv_audio_desc_mix_up|
-              :tv_audio_desc_mix_down|
-              :tv_antenna_cable|
-              :tv|
-              :sysrq|
-              :switch_charset|
-              :stem_primary|
-              :stem1|
-              :stem2|
-              :stem3|
-              :stb_power|
-              :stb_input|
-              :sleep|
-              :settings|
-              :scroll_lock|
-              :ro|
-              :prog_blue|
-              :prog_green|
-              :prog_red|
-              :prog_yellow|
-              :pairing|
-              :num_lock|
-              :numpad_subtract|
-              :numpad_multiply|
-              :numpad_left_paren|
-              :numpad_right_paren|
-              :numpad_equals|
-              :numpad_enter|
-              :numpad_dot|
-              :numpad_comma|
-              :numpad_add|
-              :numpad0|
-              :numpad1|
-              :numpad2|
-              :numpad3|
-              :numpad4|
-              :numpad5|
-              :numpad6|
-              :numpad7|
-              :numpad8|
-              :numpad9|
-              :num|
-              :nav_in|
-              :nav_next|
-              :nav_out|
-              :nav_previous|
-              :music|
-              :muhenkan|
-              :meta_left|
-              :meta_right|
-              :media_top_menu|
-              :media_step_forward|
-              :media_step_back|
-              :media_skip_forward|
-              :media_skip_back|
-              :media_record|
-              :media_play|
-              :media_eject|
-              :media_close|
-              :media_audio_track|
-              :manner_mode|
-              :last_channel|
-              :language_switch|
-              :katakana_hiragana|
-              :kana|
-              :insert|
-              :info|
-              :henkan|
-              :help|
-              :guide|
-              :del|
-              :f1|
-              :f2|
-              :f3|
-              :f4|
-              :f5|
-              :f6|
-              :f7|
-              :f8|
-              :f9|
-              :f10|
-              :f11|
-              :f12|
-              :escape|
-              :eisu|
-              :dvr|
-              :ctrl_left|
-              :ctrl_right|
-              :cut|
-              :copy|
-              :paste|
-              :contacts|
-              :chan_down|
-              :chan_up|
-              :captions|
-              :caps_lock|
-              :calendar|
-              :calculator|
-              :gamepad1|
-              :gamepad2|
-              :gamepad3|
-              :gamepad4|
-              :gamepad5|
-              :gamepad6|
-              :gamepad7|
-              :gamepad8|
-              :gamepad9|
-              :gamepad10|
-              :gamepad11|
-              :gamepad12|
-              :gamepad13|
-              :gamepad14|
-              :gamepad15|
-              :gamepad16|
-              :gamepad_a|
-              :gamepad_b|
-              :gamepad_c|
-              :gamepad_l1|
-              :gamepad_l2|
-              :gamepad_mode|
-              :gamepad_r1|
-              :gamepad_r2|
-              :gamepad_select|
-              :gamepad_start|
-              :gamepad_thumbl|
-              :gamepad_thumbr|
-              :gamepad_x|
-              :gamepad_y|
-              :gamepad_z|
-              :brightness_up|
-              :brightness_down|
-              :break|
-              :bookmark|
-              :avr_power|
-              :avr_input|
-              :assist|
-              :app_switch|
-              :threeDmode|
-              :eleven|
-              :twelve|
-              :unknown|
-              :soft_left|
-              :soft_right|
-              :soft_sleep|
-              :home|
-              :forward|
-              :back|
-              :call|
-              :endcall|
-              :dpad_up|
-              :dpad_down|
-              :dpad_left|
-              :dpad_right|
-              :dpad_down_left|
-              :dpad_down_right|
-              :dpad_up_left|
-              :dpad_up_right|
-              :dpad_center|
-              :volume_up|
-              :volume_down|
-              :power|
-              :camera|
-              :clear|
-              :alt_left|
-              :alt_right|
-              :shift_left|
-              :shift_right|
-              :tab|
-              :sym|
-              :explorer|
-              :envelope|
-              :enter|
-              :backspace|
-              :headsethook|
-              :focus|
-              :menu|
-              :top_menu|
-              :notification|
-              :search|
-              :media_play_pause|
-              :media_stop|
-              :media_next|
-              :media_previous|
-              :media_rewind|
-              :media_fast_forward|
-              :mute|
-              :page_up|
-              :page_down|
-              :pictsymbols|
-              :move_home|
-              :move_end
-            )
-            see https://developer.android.com/reference/android/view/KeyEvent.html for more info'
+            event: 'required - special event to invoke ('
           )
 
-          app_response = #{self}.close_app(
+          # Run close app and return its result
+          #{self}.close_app(
             adb_path: 'required - path to adb binary',
-            app: 'required - application app to run (i.e. open an android app returned from #list_install_apps method)',
+            app: 'required - application app to close (i.e. open an android app returned from #list_install_apps method)',
             as_root: 'optional - boolean (defaults to false)'
           )
 
+          # Run invoke event listener and return its result
           #{self}.invoke_event_listener(
             adb_path: 'required - path to adb binary',
             as_root: 'optional - boolean (defaults to false)',
+            app: 'optional - app value consumed by #invoke_event_listener'
           )
 
+          # Run adb net disconnect and return its result
           #{self}.adb_net_disconnect(
             adb_path: 'required - path to adb binary',
-            target: 'required - target host or IP to connect',
+            target: 'required - target host or IP to disconnect',
             port: 'optional - defaults to tcp 5555'
           )
 
+          # Run apk pipeline and return its result
+          #{self}.apk_pipeline(
+            apk: 'required - apk value consumed by #apk_pipeline',
+            out_dir: 'optional - out dir value consumed by #apk_pipeline'
+          )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/plugins/artifact_registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module PWN
+  module Plugins
+    # ~/.pwn/artifacts/<session>/ loot index for session_recall.
+    module ArtifactRegistry
+      ROOT = File.join(Dir.home, '.pwn', 'artifacts')
+
+      public_class_method def self.required_bins
+        []
+      end
+
+      public_class_method def self.register(opts = {})
+        sid = (opts[:session_id] || 'default').to_s
+        src = opts[:path].to_s
+        raise 'ERROR: path is required' if src.empty?
+        raise "ERROR: file not found: #{src}" unless File.file?(src)
+
+        dir = File.join(ROOT, sid)
+        FileUtils.mkdir_p(dir)
+        dest = File.join(dir, File.basename(src))
+        FileUtils.cp(src, dest)
+        meta = File.join(dir, 'index.jsonl')
+        File.open(meta, 'a') { |f| f.puts(JSON.generate(path: dest, kind: opts[:kind], src: src, at: Time.now.utc.iso8601)) }
+        dest
+      end
+
+      public_class_method def self.list(opts = {})
+        sid = (opts[:session_id] || 'default').to_s
+        meta = File.join(ROOT, sid, 'index.jsonl')
+        return [] unless File.file?(meta)
+
+        File.readlines(meta).filter_map do |ln|
+          JSON.parse(ln, symbolize_names: true)
+        rescue JSON::ParserError
+          nil
+        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:
+          # List host binaries this module expects to be installed.
+          #{self}.required_bins
+
+          # Run register and return its result
+          #{self}.register(
+            session_id: 'optional - session id value consumed by #register',
+            path: 'required - filesystem path to read or write',
+            kind: 'optional - kind value consumed by #register'
+          )
+
+          # Run list and return its result
+          #{self}.list(
+            session_id: 'optional - session id value consumed by #list'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end