pwn 0.5.708 → 0.5.710

data/lib/pwn/bounty/lifecycle_authz_replay.rb

@@ -248,33 +248,52 @@ module PWN
       # Display Usage Information
 
       public_class_method def self.help
-        <<~HELP
-          Usage:
-            plan = PWN::Bounty::LifecycleAuthzReplay.load_plan(
-              yaml_path: '/path/to/lifecycle_authz_replay.yaml'
-            )
-
-            run_obj = PWN::Bounty::LifecycleAuthzReplay.start_run(
-              plan: plan,
-              output_dir: '/tmp/evidence-bundles'
-            )
-
-            PWN::Bounty::LifecycleAuthzReplay.record_observation(
-              run_obj: run_obj,
-              checkpoint: 'post_change_t0',
-              actor: 'revoked_user',
-              surface: 'repo_settings_page',
-              status: :accessible,
-              request: { method: 'GET', path: '/org/repo/settings' },
-              response: { http_status: 200 },
-              notes: 'Still reachable after remove action',
-              artifact_paths: ['/tmp/screenshot.png']
-            )
-
-            summary = PWN::Bounty::LifecycleAuthzReplay.finalize_run(
-              run_obj: run_obj
-            )
-        HELP
+        puts "USAGE:
+          # Run load plan and return its result
+          #{self}.load_plan(
+            yaml_path: 'required - /path/to/lifecycle_authz_replay.yaml'
+          )
+
+          # Run start run and return its result
+          #{self}.start_run(
+            yaml_path: 'optional - /path/to/lifecycle_authz_replay.yaml',
+            output_dir: 'required - /tmp/evidence_bundle',
+            plan: 'required - normalized_plan_hash',
+            run_id: 'required - run id value consumed by #start_run'
+          )
+
+          # Run record observation and return its result
+          #{self}.record_observation(
+            run_obj: 'required - run obj value consumed by #record_observation',
+            checkpoint: 'required - checkpoint value consumed by #record_observation',
+            actor: 'required - actor value consumed by #record_observation',
+            surface: 'required - repo_settings_page',
+            status: 'required - status value consumed by #record_observation',
+            request: 'optional - { method: GET, path: /org/repo/settings }',
+            response: 'optional - { http_status: 200 }',
+            notes: 'optional - Still reachable after collaborator removal',
+            artifact_paths: 'optional - Array [/tmp/screen.png]'
+          )
+
+          # Run finalize run and return its result
+          #{self}.finalize_run(
+            run_obj: 'required - run obj value consumed by #finalize_run'
+          )
+
+          # Run normalize plan and return its result
+          #{self}.normalize_plan(
+            plan: 'optional - plan value consumed by #normalize_plan',
+            campaign: 'required - { id: acme-revoke }',
+            actors: 'optional - [owner, revoked_user]',
+            surfaces: 'optional - surfaces value consumed by #normalize_plan',
+            checkpoints: 'required - [pre_change, post_change_t0]',
+            plan_id_hint: 'required - plan id hint value consumed by #normalize_plan'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
       end
 
       private_class_method def self.find_stale_access_findings(opts = {})

data/lib/pwn/bounty.rb

@@ -16,6 +16,10 @@ module PWN
     end
 
     public_class_method def self.help
+      puts "USAGE:
+        # Display a List of Every PWN::Bounty Module
+        #{self}.authors
+      "
       constants.sort
     end
   end

data/lib/pwn/config.rb

@@ -1050,39 +1050,105 @@ module PWN
 
     public_class_method def self.help
       puts "USAGE:
+        # Run env template and return its result
+        #{self}.env_template
+
+        # Run default env and return its result
         #{self}.default_env(
           pwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml'
         )
 
+        # Run redact sensitive artifacts and return its result
         #{self}.redact_sensitive_artifacts(
           config: 'optional - Hash to redact sensitive artifacts from.  Defaults to PWN::Env'
         )
 
-        #{self}.pwn_skills_path
+        # Run init driver options and return its result
+        #{self}.init_driver_options
+
+        # Run refresh env and return its result
+        #{self}.refresh_env(
+          pwn_env_path: 'required - pwn env path value consumed by #refresh_env',
+          pwn_dec_path: 'required - pwn dec path value consumed by #refresh_env',
+          key: 'optional - key value consumed by #refresh_env',
+          iv: 'optional - iv value consumed by #refresh_env'
+        )
 
-        #{self}.sanitize_skill_name(name: '...')
+        # Run pwn skills path and return its result
+        #{self}.pwn_skills_path(
+          pwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml'
+        )
 
+        # Run sanitize skill name and return its result
+        #{self}.sanitize_skill_name(
+          name: 'required - binary or identifier name'
+        )
+
+        # Run parse skill frontmatter and return its result
+        #{self}.parse_skill_frontmatter(
+          content: 'optional - content value consumed by #parse_skill_frontmatter'
+        )
+
+        # Run parse skill references and return its result
+        #{self}.parse_skill_references(
+          content: 'optional - content value consumed by #parse_skill_references'
+        )
+
+        # Run write skill and return its result
         #{self}.write_skill(
-          name: 'required', content: 'required',
-          description: 'optional', references: 'optional Array',
-          license: 'optional', metadata: 'optional Hash',
-          allowed_tools: 'optional Array', pwn_skills_path: 'optional'
+          name: 'required - free-form; sanitised to [a-z0-9-]',
+          content: 'required - markdown body (WITHOUT frontmatter)',
+          description: 'optional - 1..1024 chars; derived from body when omitted',
+          references: 'optional - Array of URLs / CWE / CVE / ATT&CK / NIST ids',
+          license: 'optional - SPDX id or free text',
+          metadata: 'optional - Hash of arbitrary metadata',
+          allowed_tools: 'optional - Array of toolset names',
+          pwn_skills_path: 'optional - override skills root (defaults to pwn_skills_path)'
         )
 
-        #{self}.load_skills(pwn_skills_path: 'optional')
+        # Run migrate legacy skills and return its result
+        #{self}.migrate_legacy_skills(
+          pwn_skills_path: 'optional - override skills root (defaults to pwn_skills_path)',
+          delete_legacy: 'optional - remove flat file after migration (default true)'
+        )
 
-        #{self}.migrate_legacy_skills(pwn_skills_path: 'optional', delete_legacy: true)
+        # Run default skill names and return its result
+        #{self}.default_skill_names(
+          source: 'optional - source value consumed by #default_skill_names',
+          root: 'optional - root value consumed by #default_skill_names'
+        )
 
-        #{self}.install_default_skills(pwn_skills_path: 'optional')
-        #{self}.default_skill_names
+        # Run default skills dir and return its result
+        #{self}.default_skills_dir
 
-        #{self}.refresh_env(
-          pwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml',
-        pwn_dec_path: 'optional - Path to pwn.yaml.decryptor file.  Defaults to ~/.pwn/pwn.yaml.decryptor'
+        # Seed bundled skills into ~/.pwn/skills (or pwn_skills_path:)
+        #{self}.install_default_skills(
+          pwn_skills_path: 'optional - pwn skills path value consumed by #install_default_skills',
+          source: 'optional - source value consumed by #install_default_skills'
+        )
+
+        # Run load skills and return its result
+        #{self}.load_skills(
+          pwn_skills_path: 'optional - Path to skills folder.  Defaults to ~/.pwn/skills',
+          references: 'optional - frontmatter:, loaded:?, error:? }'
         )
 
+        # Run pwn memory path and return its result
+        #{self}.pwn_memory_path
+
+        # Run load memory and return its result
+        #{self}.load_memory
+
+        # Run pwn sessions path and return its result
+        #{self}.pwn_sessions_path
+
+        # Run pwn cron path and return its result
+        #{self}.pwn_cron_path
+
+        # Print the AUTHOR(S) string for this module.
         #{self}.authors
       "
+      constants.sort
     end
   end
 end

data/lib/pwn/cron.rb

@@ -1518,26 +1518,303 @@ module PWN
 
     # Display Usage for this Module
     public_class_method def self.help
-      puts <<~USAGE
-                USAGE:
-                  PWN::Cron.create(schedule: '0 * * * *', prompt: 'Run daily recon on target.com using NmapIt and report', name: 'daily-recon')
-                  PWN::Cron.list
-                  res = PWN::Cron.run(id: 'abc123')
-                  PWN::Cron.enable(id: 'abc123')
-                  PWN::Cron.disable(id: 'abc123')
-                  PWN::Cron.remove(id: 'abc123')
-                  # OS-native persistence (systemd --user / launchd / schtasks / crontab)
-                  PWN::Cron.install_scheduler
-                  PWN::Cron.uninstall_scheduler
-                  PWN::Cron.sync_scheduler
-                  PWN::Cron.scheduler_backend
-        PWN::Cron.install_defaults  # seed S1/P3/W2/M1 curriculum jobs (idempotent)
-        PWN::Cron.ensure_worker     # start/restart the background scheduler
-        PWN::Cron.worker_status
-        PWN::Cron.tick              # fire currently-due jobs once
-
-                  #{self}.authors
-      USAGE
+      puts "USAGE:
+        # Run cron dir and return its result
+        #{self}.cron_dir
+
+        # Run list and return its result
+        #{self}.list
+
+        # Run create and return its result
+        #{self}.create(
+          name: 'optional - binary or identifier name (defaults to job-)',
+          schedule: 'required - required e.g. 0 * * * * or 30m or every 2h',
+          prompt: 'optional - pwn-ai prompt to run',
+          ruby: 'optional - ruby snippet to eval',
+          script: 'optional - path to external script',
+          delivery: 'optional - log|stdout (default log)',
+          enabled: 'optional - enabled value consumed by #create',
+          install_crontab: 'optional - install crontab value consumed by #create'
+        )
+
+        # Executes the job (for pwn-ai prompt it will use current active AI engine
+        #{self}.run(
+          id: 'required - id value consumed by #run'
+        )
+
+        # Run remove and return its result
+        #{self}.remove(
+          id: 'optional - id value consumed by #remove'
+        )
+
+        # Run enable and return its result
+        #{self}.enable(
+          id: 'optional - id value consumed by #enable'
+        )
+
+        # Run disable and return its result
+        #{self}.disable(
+          id: 'optional - id value consumed by #disable'
+        )
+
+        # Install a crontab line that invokes this job via pwn
+        #{self}.install_crontab_entry
+
+        # Run install defaults and return its result
+        #{self}.install_defaults
+
+        # Runtime paths follow cron_dir (and therefore a stubbed CRON_DIR)
+        #{self}.jobs_file
+
+        # Run pid file and return its result
+        #{self}.pid_file
+
+        # Run worker log and return its result
+        #{self}.worker_log
+
+        # Run due and return its result
+        #{self}.due?(
+          schedule: 'required - 5-field cron or relative (30m, every 2h)',
+          last_run: 'optional - Time / iso8601 / nil',
+          now: 'optional - Time (default Time.now)'
+        )
+
+        # Run due jobs and return its result
+        #{self}.due_jobs(
+          now: 'optional - now value consumed by #due_jobs (defaults to Time.now)'
+        )
+
+        # Fires every currently-due enabled job via run(). Returns the list
+        #{self}.run_due(
+          now: 'optional - now value consumed by #run_due (defaults to Time.now)',
+          jobs: 'optional - jobs value consumed by #run_due'
+        )
+
+        # Run worker status and return its result
+        #{self}.worker_status
+
+        # Idempotent. With restart:true (default) a live worker is replaced
+        #{self}.start_worker(
+          interval: 'optional - interval value consumed by #start_worker',
+          foreground: 'optional - foreground value consumed by #start_worker',
+          restart: 'optional - restart value consumed by #start_worker (defaults to foreground)'
+        )
+
+        # Run stop worker and return its result
+        #{self}.stop_worker
+
+        # Single tick used by the loop AND by tests (no sleep)
+        #{self}.tick(
+          now: 'optional - now value consumed by #tick'
+        )
+
+        # Blocking poll loop. `once: true` runs a single tick then returns
+        #{self}.worker_loop(
+          interval: 'optional - interval value consumed by #worker_loop',
+          once: 'optional - once value consumed by #worker_loop'
+        )
+
+        # any setup action so YAML-only default jobs actually fire
+        #{self}.ensure_worker(
+          interval: 'optional - interval value consumed by #ensure_worker (defaults to DEFAULT_INTERVAL)'
+        )
+
+        # Append an @reboot line so the worker comes back after a reboot
+        #{self}.install_worker_crontab
+
+        # Run os type and return its result
+        #{self}.os_type
+
+        # Run windows and return its result
+        #{self}.windows?
+
+        # Run scheduler file and return its result
+        #{self}.scheduler_file
+
+        # Run scheduler config and return its result
+        #{self}.scheduler_config
+
+        # Run cron enabled and return its result
+        #{self}.cron_enabled?
+
+        # Run persist scheduler config and return its result
+        #{self}.persist_scheduler_config(
+          backend: 'optional - backend value consumed by #persist_scheduler_config'
+        )
+
+        # Run apply native and return its result
+        #{self}.apply_native?(
+          apply: 'optional - apply value consumed by #apply_native?'
+        )
+
+        # Run which bin and return its result
+        #{self}.which_bin(
+          name: 'required - binary or identifier name'
+        )
+
+        # Run crontab available and return its result
+        #{self}.crontab_available?
+
+        # Run systemd user available and return its result
+        #{self}.systemd_user_available?
+
+        # Run schtasks available and return its result
+        #{self}.schtasks_available?
+
+        # Run scheduler backend and return its result
+        #{self}.scheduler_backend(
+          backend: 'optional - backend value consumed by #scheduler_backend',
+          os: 'optional - os value consumed by #scheduler_backend'
+        )
+
+        # Run native unit dir and return its result
+        #{self}.native_unit_dir(
+          backend: 'optional - backend value consumed by #native_unit_dir'
+        )
+
+        # Run ruby lib dir and return its result
+        #{self}.ruby_lib_dir
+
+        # Run ruby eval argv and return its result
+        #{self}.ruby_eval_argv(
+          snippet: 'optional - snippet value consumed by #ruby_eval_argv'
+        )
+
+        # Run ruby eval shell and return its result
+        #{self}.ruby_eval_shell(
+          log: 'optional - log value consumed by #ruby_eval_shell'
+        )
+
+        # Convert a 5-field cron expression into a portable calendar hash
+        #{self}.cron_to_calendar(
+          schedule: 'optional - schedule value consumed by #cron_to_calendar'
+        )
+
+        # Run systemd on calendar and return its result
+        #{self}.systemd_on_calendar(
+          calendar: 'optional - calendar value consumed by #systemd_on_calendar',
+          schedule: 'optional - schedule value consumed by #systemd_on_calendar'
+        )
+
+        # Run launchd calendar interval and return its result
+        #{self}.launchd_calendar_interval(
+          calendar: 'optional - calendar value consumed by #launchd_calendar_interval',
+          schedule: 'optional - schedule value consumed by #launchd_calendar_interval'
+        )
+
+        # Run schtasks spec and return its result
+        #{self}.schtasks_spec(
+          calendar: 'optional - calendar value consumed by #schtasks_spec',
+          schedule: 'optional - schedule value consumed by #schtasks_spec'
+        )
+
+        # Run install scheduler and return its result
+        #{self}.install_scheduler(
+          enabled: 'optional - enabled value consumed by #install_scheduler',
+          backend: 'optional - optional force',
+          apply: 'optional - optional (default true unless PWN_CRON_DIR is set',
+          sync_jobs: 'optional - sync jobs value consumed by #install_scheduler'
+        )
+
+        # Run uninstall scheduler and return its result
+        #{self}.uninstall_scheduler(
+          backend: 'optional - backend value consumed by #uninstall_scheduler',
+          persist: 'optional - persist value consumed by #uninstall_scheduler'
+        )
+
+        # Run sync scheduler and return its result
+        #{self}.sync_scheduler
+
+        # Run scheduler status and return its result
+        #{self}.scheduler_status
+
+        # Run install native job and return its result
+        #{self}.install_native_job(
+          job: 'optional - job value consumed by #install_native_job',
+          backend: 'optional - backend value consumed by #install_native_job'
+        )
+
+        # Run remove native job and return its result
+        #{self}.remove_native_job(
+          job: 'optional - job value consumed by #remove_native_job',
+          id: 'optional - id value consumed by #remove_native_job',
+          name: 'optional - binary or identifier name',
+          backend: 'optional - backend value consumed by #remove_native_job'
+        )
+
+        # Run sync native jobs and return its result
+        #{self}.sync_native_jobs(
+          backend: 'optional - backend value consumed by #sync_native_jobs'
+        )
+
+        # ---- crontab -------------------------------------------------------
+        #{self}.install_crontab_worker
+
+        # Run install crontab job and return its result
+        #{self}.install_crontab_job(
+          job: 'optional - job value consumed by #install_crontab_job'
+        )
+
+        # Run uninstall crontab and return its result
+        #{self}.uninstall_crontab
+
+        # Run uninstall crontab job and return its result
+        #{self}.uninstall_crontab_job(
+          job: 'optional - job value consumed by #uninstall_crontab_job'
+        )
+
+        # ---- systemd --user ------------------------------------------------
+        #{self}.install_systemd_user_worker
+
+        # Run install systemd user job and return its result
+        #{self}.install_systemd_user_job(
+          job: 'optional - job value consumed by #install_systemd_user_job'
+        )
+
+        # Run uninstall systemd user and return its result
+        #{self}.uninstall_systemd_user
+
+        # Run uninstall systemd user job and return its result
+        #{self}.uninstall_systemd_user_job(
+          job: 'optional - job value consumed by #uninstall_systemd_user_job'
+        )
+
+        # ---- launchd -------------------------------------------------------
+        #{self}.install_launchd_worker
+
+        # Run install launchd job and return its result
+        #{self}.install_launchd_job(
+          job: 'optional - job value consumed by #install_launchd_job'
+        )
+
+        # Run uninstall launchd and return its result
+        #{self}.uninstall_launchd
+
+        # Run uninstall launchd job and return its result
+        #{self}.uninstall_launchd_job(
+          job: 'optional - job value consumed by #uninstall_launchd_job'
+        )
+
+        # ---- schtasks (Windows) -------------------------------------------
+        #{self}.install_schtasks_worker
+
+        # Run install schtasks job and return its result
+        #{self}.install_schtasks_job(
+          job: 'optional - job value consumed by #install_schtasks_job'
+        )
+
+        # Run uninstall schtasks and return its result
+        #{self}.uninstall_schtasks
+
+        # Run uninstall schtasks job and return its result
+        #{self}.uninstall_schtasks_job(
+          job: 'optional - job value consumed by #uninstall_schtasks_job'
+        )
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
+      constants.sort
     end
   end
 end

data/lib/pwn/driver.rb

@@ -69,26 +69,10 @@ module PWN
 
     public_class_method def self.help
       puts "USAGE:
-        # Load default driver options into PWN::Env
-        opts = PWN::Env[:driver_opts]
-        #{self}::Parser.new.parse(&:on).parse!
-
-        # Add more options by passing a block to the parser
-        opts = PWN::Env[:driver_opts]
-        #{self}::Parser.new do |options|
-          # Boolean option
-          options.on('-b', '--boolean') do |o|
-            opts[:boolean] = o
-          end
-
-          # String option
-          options.on('-sSTRING', '--string=STRING') do |o|
-            opts[:string] = o
-          end
-        end.parse!
-
+        # Print the AUTHOR(S) string for this module.
         #{self}.authors
       "
+      constants.sort
     end
   end
 end

data/lib/pwn/ffi/adalm_pluto.rb

@@ -455,22 +455,76 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # Run available and return its result
           #{self}.available?
+
+          # Run info and return its result
           #{self}.info
-          #{self}.list_uris
-          ctx = #{self}.open(uri: 'ip:192.168.2.1')   # or nil for default
-          #{self}.device_info(context: ctx)
-          #{self}.configure(context: ctx, freq_hz:, rate_hz: 2_500_000, gain_db: nil)
-          h = #{self}.start_rx(context: ctx, samples: 262_144)
-          iq = #{self}.read_sync(handle: h)            # cs16le interleaved String
-          #{self}.stop_rx(handle: h)
-          #{self}.close(context: ctx)
-
-          # one-shot
-          cap = #{self}.capture(freq_hz: 1090e6, rate_hz: 2_500_000, bytes: 1_048_576)
 
+          # Run list uris and return its result
+          #{self}.list_uris(
+            backends: 'optional - backends value consumed by #list_uris'
+          )
+
+          # Open a session or connection and return a handle.
+          #{self}.open(
+            uri: 'required - URI or URL string',
+            timeout_ms: 'optional - timeout ms value consumed by #open'
+          )
+
+          # Close a session previously returned by #open.
+          #{self}.close(
+            context: 'optional - context value consumed by #close'
+          )
+
+          # Run device info and return its result
+          #{self}.device_info(
+            context: 'required - context value consumed by #device_info'
+          )
+
+          # Run configure and return its result
+          #{self}.configure(
+            context: 'required - pointer from .open',
+            freq_hz: 'required - RX LO frequency Hz',
+            rate_hz: 'optional - sample rate (default 2_500_000)',
+            bw_hz: 'optional - RF bandwidth (default = rate_hz)',
+            gain_db: 'optional - manual gain dB; nil = slow_attack AGC',
+            gain_mode: 'optional - slow_attack|fast_attack|manual|hybrid'
+          )
+
+          # Run start rx and return its result
+          #{self}.start_rx(
+            context: 'required - pointer from .open',
+            samples: 'optional - samples-per-refill (default 262144)',
+            cyclic: 'optional - cyclic buffer (default false)'
+          )
+
+          # Run read sync and return its result
+          #{self}.read_sync(
+            handle: 'required - handle value consumed by #read_sync'
+          )
+
+          # Run stop rx and return its result
+          #{self}.stop_rx(
+            handle: 'optional - handle value consumed by #stop_rx'
+          )
+
+          # High-level one-shot: open → configure → start_rx → N refills → stop → close
+          #{self}.capture(
+            freq_hz: 'required - freq hz value consumed by #capture',
+            rate_hz: 'optional - rate hz value consumed by #capture',
+            bytes: 'optional - 1_048_576,   # approximate payload size',
+            uri: 'optional - URI or URL string',
+            gain_db: 'optional - gain db value consumed by #capture',
+            timeout_ms: 'optional - timeout ms value consumed by #capture',
+            bw_hz: 'optional - bw hz value consumed by #capture',
+            gain_mode: 'optional - gain mode value consumed by #capture'
+          )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
 
       class << self