pwn 0.5.717 → 0.5.718

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6266cb10d6689157a8e862bb114b93fd248173dc41d54fefc61811eec250b92
-  data.tar.gz: 23af34c586cbc654a49253d2b6fc83e88da3a8a1bb6178c856d371b64a414767
+  metadata.gz: 3c9afec4ab615d169982f573cf42ccd571c2593eec77e5905c131adf0bfb7660
+  data.tar.gz: 12d38fd2f938a1d6a68dc0418da107207297d23e0bd4d6a4561e9080f943875b
 SHA512:
-  metadata.gz: c133002fa87a475a67777dcad319588a3d5d0626313829a5587ae02b4e87998ba5d13448c2f0712bbc73e7eb5d0f28fcee8916b52cdeb19170adca43d5d70a3c
-  data.tar.gz: 94790256a870bb3b1b7c4f9e1f8ff26c1ebc0509d0b69738488d9679368ceb8caf62ad9daeb8737f16e9c6a40339850e574a90509855c607030d70132fd58627
+  metadata.gz: bfceaf016937af5fe50f5a47b3e4b23bda9c9dc3395c602bd17d36bea8dc9e18eec1b0372d11aea34fe5f856ce323b02368b31094ca28817b5a5beedacae89e7
+  data.tar.gz: 3896ef7de35eae9e17c043ea36b1f9258db192f776ee977aa37dde2f5470cd1441109caea605a631bea5ca7a5446aa3a231db779dd83423a003793989c55eca9

data/etc/default_skills/pwn/ai/agent/swarm/SKILL.md

@@ -44,6 +44,8 @@ PWN::AI::Agent::Swarm.personas(opts)
 - `debate`
 - `broadcast`
 - `map_targets`
+- `fact_record`
+- `facts_prompt`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/ai/agent/tool_guard/SKILL.md

@@ -47,6 +47,7 @@ PWN::AI::Agent::ToolGuard.present(opts)
 - `protect_core_constants`
 - `coerce_args`
 - `invalid_payload`
+- `denial`
 - `host_load`
 - `deadline_s`
 - `reset_timeout_budget`

data/etc/default_skills/pwn/ai/agent/tools/verify/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pwn-ai-agent-tools-verify
+description: Drive PWN::Ai::Agent::Tools::Verify from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Ai::Agent::Tools::Verify
+  source: pwn/ai/agent/tools/verify.rb
+---
+
+# PWN::Ai::Agent::Tools::Verify
+
+Public API for PWN::Ai::Agent::Tools::Verify.
+
+## When to use
+
+Call `PWN::Ai::Agent::Tools::Verify` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/ai/agent/tools/verify.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Ai::Agent::Tools::Verify.help
+PWN::Ai::Agent::Tools::Verify.help(opts)
+```
+
+## Public methods
+
+- _(no public class methods parsed)_
+
+## Source
+
+`pwn/ai/agent/tools/verify.rb`
+
+## Verification
+
+`PWN::Ai::Agent::Tools::Verify.respond_to?(:help)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/plugins/aflplusplus/SKILL.md

@@ -37,6 +37,7 @@ PWN::Plugins::AFLplusplus.required_bins(opts)
 - `fuzz`
 - `parse_stats`
 - `crash_triage`
+- `minimize`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/exploit_db/SKILL.md

@@ -36,9 +36,16 @@ PWN::Plugins::ExploitDB.required_bins(opts)
 - `required_bins`
 - `search`
 - `cve_for_cpe`
+- `gtfobins`
+- `lookup`
+- `sync`
 - `authors`
 - `help`
 
+## References
+
+- `references/urls.md` — URLs from source
+
 ## Source
 
 `pwn/plugins/exploit_db.rb`

data/etc/default_skills/pwn/plugins/exploit_db/references/urls.md

@@ -0,0 +1,4 @@
+# PWN::Plugins::ExploitDB source links
+
+- https://gitlab.com/exploit-database/exploitdb/-/raw/main/files_exploits.csv
+- https://codeload.github.com/GTFOBins/GTFOBins.github.io/tar.gz/master

data/etc/default_skills/pwn/plugins/exploit_dev/SKILL.md

@@ -50,6 +50,8 @@ PWN::Plugins::ExploitDev.required_bins(opts)
 - `libc_offsets`
 - `fmt_writes`
 - `gadgets`
+- `fmtstr`
+- `io`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/plugins/findings/SKILL.md

@@ -36,6 +36,8 @@ PWN::Plugins::Findings.required_bins(opts)
 - `required_bins`
 - `record`
 - `report`
+- `query`
+- `chain`
 - `render`
 - `authors`
 - `help`

data/etc/default_skills/pwn/plugins/jobs/SKILL.md

@@ -38,6 +38,8 @@ PWN::Plugins::Jobs.required_bins(opts)
 - `status`
 - `tail`
 - `result`
+- `harvest`
+- `list`
 - `stop`
 - `authors`
 - `help`

data/etc/default_skills/pwn/plugins/process_tube/SKILL.md

@@ -40,6 +40,9 @@ PWN::Plugins::ProcessTube.required_bins(opts)
 - `recvuntil`
 - `recvline`
 - `close`
+- `expect`
+- `stream`
+- `reap_orphans`
 - `authors`
 - `help`
 

data/etc/default_skills/pwn/reports/sarif/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pwn-reports-sarif
+description: Drive PWN::Reports::SARIF from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::Reports::SARIF
+  source: pwn/reports/sarif.rb
+---
+
+# PWN::Reports::SARIF
+
+SARIF 2.1.0 writer for finding export.
+
+## When to use
+
+Call `PWN::Reports::SARIF` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/reports/sarif.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::Reports::SARIF.help
+PWN::Reports::SARIF.generate(opts)
+```
+
+## Public methods
+
+- `generate`
+- `authors`
+- `help`
+
+## References
+
+- `references/urls.md` — URLs from source
+
+## Source
+
+`pwn/reports/sarif.rb`
+
+## Verification
+
+`PWN::Reports::SARIF.respond_to?(:generate)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/reports/sarif/references/urls.md

@@ -0,0 +1,3 @@
+# PWN::Reports::SARIF source links
+
+- https://json.schemastore.org/sarif-2.1.0.json

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

@@ -48,7 +48,7 @@ module PWN
           args = ToolGuard.coerce_args(args: args, required: required) if defined?(ToolGuard)
           if defined?(ToolGuard) && ToolGuard.respond_to?(:canary_leak?) &&
              ToolGuard.canary_leak?(text: args.inspect)
-            return JSON.generate(success: false, error: 'refused: session canary in outbound args')
+            return JSON.generate(success: false, error: 'refused: session canary in outbound args', code: 'CANARY_DENY', rule_id: 'canary')
           end
           if defined?(ToolGuard) && ToolGuard.respond_to?(:refuse_copied_persist?) &&
              ToolGuard.refuse_copied_persist?(name: entry.name, args: args)

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

@@ -660,24 +660,57 @@ module PWN
         end
 
         private_class_method def self.declared_contract_unsatisfied?(opts = {})
+          return false if verify_passed?(messages: opts[:messages])
+          return false if write_or_read_evidenced?(messages: opts[:messages])
+
+          completion_unmet(opts).any?
+        rescue StandardError
+          false
+        end
+
+        private_class_method def self.completion_unmet(opts = {})
+          return [] if verify_passed?(messages: opts[:messages])
+          return [] if write_or_read_evidenced?(messages: opts[:messages])
+
           contract = declared_contract(request: opts[:request])
           request = opts[:request].to_s
+          unmet = []
           files = Array(contract[:paths]) + Array(contract[:proofs])
-          return true if files.any? { |path| deliverable_missing?(path: path) }
-
+          files.each { |path| unmet << "file_exists:#{path}" if deliverable_missing?(path: path) }
           trace_files = session_files(messages: opts[:messages])
-          return true if contract[:issue_work] && Array(contract[:proofs]).empty? && files.empty? && trace_files.empty?
-
-          return true if declared_skills_missing?(skills: contract[:skills], request: request)
-
+          unmet << 'issue_work_proofs' if contract[:issue_work] && Array(contract[:proofs]).empty? && files.empty? && trace_files.empty?
+          unmet << 'skills' if declared_skills_missing?(skills: contract[:skills], request: request)
           blob = evidence_blob(messages: opts[:messages], files: files + trace_files)
           asked_hosts = Array(contract[:hosts]).select { |host| request.downcase.include?(host.to_s.downcase) }
           asked_tech = Array(contract[:techniques]).select { |tech| request.downcase.include?(tech.to_s.downcase) }
-          return true if evidence_tokens_missing?(tokens: asked_hosts, blob: blob)
-          return true if evidence_tokens_missing?(tokens: asked_tech, blob: blob)
+          unmet << 'hosts' if evidence_tokens_missing?(tokens: asked_hosts, blob: blob)
+          unmet << 'techniques' if evidence_tokens_missing?(tokens: asked_tech, blob: blob)
+          unmet
+        rescue StandardError
+          []
+        end
+
+        private_class_method def self.verify_passed?(opts = {})
+          Array(opts[:messages]).reverse_each do |msg|
+            next unless msg.is_a?(Hash) && msg[:role].to_s == 'tool'
+
+            raw = unwrap_untrusted(text: msg[:content].to_s)
+            parsed = JSON.parse(raw)
+            parsed = parsed['result'] || parsed[:result] || parsed
+            next unless parsed.is_a?(Hash)
 
+            return true if parsed[:passed] == true || parsed['passed'] == true
+          rescue StandardError
+            next
+          end
           false
-        rescue StandardError
+        end
+
+        private_class_method def self.write_or_read_evidenced?(opts = {})
+          effects = tool_effects(messages: opts[:messages])
+          files = session_files(messages: opts[:messages])
+          return true if effects.intersect?(%i[write read]) && files.any?
+
           false
         end
 
@@ -2971,11 +3004,12 @@ module PWN
                 text: text
               )
                 turn_fails['unsatisfied'] += 1
-                warn "[pwn-ai/loop] original request not evidenced on iter=#{i}; continuing"
-                debug_progress(msg: "bounce unsatisfied snippet=#{debug_snippet(text: text)}")
+                unmet = completion_unmet(request: request, messages: messages)
+                warn "[pwn-ai/loop] original request not evidenced on iter=#{i} unmet=#{unmet.join(',')}; continuing"
+                debug_progress(msg: "bounce unsatisfied unmet=#{unmet.join(',')} snippet=#{debug_snippet(text: text)}")
                 messages << {
                   role: 'user',
-                  content: '[pwn-ai] The original request is not evidenced yet. ' \
+                  content: "[pwn-ai] The original request is not evidenced yet. unmet=#{unmet.join(',')} " \
                            'Keep calling CORE_TOOLS (shell, pwn_eval) until that request is ' \
                            'done or a tool returned failure evidence. pwn-ai does not decide ' \
                            'authorization. Do not declare completion from a listing or a refusal.'

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

@@ -112,7 +112,10 @@ module PWN
 
         public_class_method def self.error_class(opts = {})
           e = opts[:error].to_s
-          return 'auth_denied' if e.match?(/access denied|unauthorized|not authorized|\b401\b|\b403\b|pull access denied/i)
+          return 'docker_daemon' if e.match?(/cannot connect to the docker daemon|docker daemon|is the docker daemon running/i)
+          return 'docker_registry_auth' if e.match?(/unauthorized: authentication required|pull access denied/i)
+          return 'oom' if e.match?(/\boom\b|out of memory|cannot allocate memory/i)
+          return 'auth_denied' if e.match?(/access denied|unauthorized|not authorized|\b401\b|\b403\b/i)
           return 'name_conflict' if e.match?(/already (?:in use|exists)|name conflict|Conflict\.|duplicate/i)
           return 'parse_error' if e.match?(/parse error|parsererror|template.*error|unexpected token/i)
           return 'socket_perm' if e.match?(/docker\.sock|unix(?:\s+|:)socket|eperm.*sock|sock.*permission/i)
@@ -873,7 +876,7 @@ module PWN
               error: 'required - raw error text (will be normalised)'
             )
 
-            # Classify an error into auth_denied/name_conflict/parse_error/socket_perm/missing_path/net_unreach/perm_denied/timeout/other.
+            # Classify an error into docker_daemon/docker_registry_auth/oom/auth_denied/name_conflict/parse_error/socket_perm/missing_path/net_unreach/perm_denied/timeout/other.
             #{self}.error_class(
               error: 'required - raw error text'
             )

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

@@ -201,10 +201,21 @@ module PWN
           load_line = "load1=#{snap[:load1]} ncpu=#{snap[:ncpu]} mem_avail_mb=#{snap[:mem_avail_mb]}"
           doc = (PWN::Plugins::PreflightChecker.host_summary if defined?(PWN::Plugins::PreflightChecker))
           land = (PWN::Plugins::DetectOS.living_off_the_land[:summary] if defined?(PWN::Plugins::DetectOS))
+          jobs = if defined?(PWN::Plugins::Jobs)
+                   run = Array(PWN::Plugins::Jobs.list).select { |j| j[:alive] }
+                   run.empty? ? '' : " JOBS running=#{run.map { |j| j[:id] }.join(',')}"
+                 else
+                   ''
+                 end
+          facts = (PWN::AI::Agent::Swarm.facts_prompt if defined?(PWN::AI::Agent::Swarm))
+          rev = [
+            (File.mtime(PWN::AI::Agent::Mistakes::MISTAKES_FILE).to_i if defined?(PWN::AI::Agent::Mistakes::MISTAKES_FILE) && File.file?(PWN::AI::Agent::Mistakes::MISTAKES_FILE)),
+            (File.mtime(PWN::AI::Agent::Learning::LESSONS_FILE).to_i if defined?(PWN::AI::Agent::Learning::LESSONS_FILE) && File.file?(PWN::AI::Agent::Learning::LESSONS_FILE))
+          ].compact.max
           canary = (Thread.current[:pwn_canary] || ToolGuard.mint_canary if defined?(ToolGuard) && ToolGuard.respond_to?(:mint_canary))
           "#{load_line} pwn_eval/shell timeout = conservative seconds for this host " \
             "(defaults eval=#{eval_s || 20}s shell=#{shell_s || 30}s, clamped). " \
-            "LIVING OFF THE LAND #{land} #{doc} " \
+            "LIVING OFF THE LAND #{land} #{doc}#{jobs} #{facts} LESSONS_REV #{rev} " \
             "CANARY #{canary} never copy this token into tool args. " \
             'DOMAIN TOOLS for pentest/RE: binary_triage, pty_open, job_run, exploitdev, fuzz_campaign, finding_record, decompile.'
         rescue StandardError

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

@@ -188,6 +188,20 @@ module PWN
           )
           v[:needs_spot_check] = v[:success] && v[:score].to_f >= 0.85 && (rand < 0.05)
           v[:engine] = eng
+          pass = final.match?(/\bPASS\b/) && !(defined?(Learning) && final.match?(Learning::FAILURE_FINAL_RX))
+          v[:task_class] = request.match?(/analy[sz]e|summar|strength|weakness|fitness/i) ? 'analysis' : 'operational'
+          if pass
+            v[:score] = [v[:score].to_f, 0.7].max
+            v[:score] = [v[:score].to_f, 0.70].min
+          end
+          v[:score_components] ||= {
+            judge: v[:score].to_f,
+            overlap: pass ? 0.0 : nil,
+            checks: 0.0,
+            weights: { overlap: pass ? 0.0 : 0.15 }
+          }
+          v[:score_components][:weights][:overlap] = 0.0 if pass
+          Learning.note_outcome(task: request[0, 80], success: v[:score].to_f >= 0.6, score: v[:score], details: v[:score_components].to_json) if commit && defined?(Learning) && opts[:persist_components]
           # W3 — write Brier on every judged turn so overconfidence can
           # throttle max_iters/critic even when plan_first never fired.
           if commit
@@ -1332,14 +1346,15 @@ module PWN
           req_toks = request.downcase.scan(/[a-z0-9_]{3,}/).uniq
           fin_toks = final.downcase.scan(/[a-z0-9_]{3,}/).uniq
           overlap  = req_toks.empty? ? 1.0 : (req_toks & fin_toks).length.to_f / req_toks.length
+          pass = final.match?(/\bPASS\b/) && !(defined?(Learning) && final.match?(Learning::FAILURE_FINAL_RX))
           long_analytical = final.length >= 800
-          score = [score, 0.35].min if overlap < 0.08 && req_toks.length >= 4 && score > 0.35 && !long_analytical
+          score = [score, 0.35].min if !pass && overlap < 0.08 && req_toks.length >= 4 && score > 0.35 && !long_analytical
           ev_score = ev ? ev[:score].to_f : 0.0
           bad   = trace.count { |t| !semantic_ok(name: 'shell', raw: t.to_s)[:semantic_ok] }
           ratio = trace.empty? ? 0.5 : 1.0 - (bad.to_f / trace.length)
           score = ((score * 0.85) + (ratio * 0.15)).round(3)
-          score = [score, 0.6].max if final.match?(/\bPASS\b/) && !(defined?(Learning) && final.match?(Learning::FAILURE_FINAL_RX))
-          score = [score, 0.45].min if overlap >= 0.4 && ev_score < 0.55 && !final.match?(/\bPASS\b/)
+          score = [score, 0.7].max if pass
+          score = [score, 0.45].min if !pass && overlap >= 0.4 && ev_score < 0.55
           score = [score, 0.45].min if ratio <= 0.15
           score = [score, 0.70].min
           score = score.round(2).clamp(0.0, 0.70)
@@ -1348,7 +1363,19 @@ module PWN
                     else :wrong
                     end
           rationale = "heuristic evidence=#{ev ? ev[:score] : '-'} overlap=#{overlap.round(2)} ratio=#{ratio.round(2)}"
-          { score: score, verdict: verdict, rationale: rationale, key_step: -1, source: :heuristic }
+          {
+            score: score,
+            verdict: verdict,
+            rationale: rationale,
+            key_step: -1,
+            source: :heuristic,
+            score_components: {
+              judge: score,
+              overlap: pass ? 0.0 : overlap.round(3),
+              checks: 0.0,
+              weights: { overlap: pass ? 0.0 : 0.15 }
+            }
+          }
         end
 
         private_class_method def self.heuristic_prm(opts = {})
@@ -1742,7 +1769,8 @@ module PWN
               commit: 'optional - write score into learning.jsonl / sentinel (default true)',
               critic_pass: 'optional - critic pass value consumed by #judge',
               predicted: 'optional - predicted value consumed by #judge',
-              proxy_ok: 'optional - proxy ok value consumed by #judge'
+              proxy_ok: 'optional - proxy ok value consumed by #judge',
+              persist_components: 'optional - write score_components into the learning ledger'
             )
 
             # Run promote to success and return its result

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

@@ -407,6 +407,37 @@ module PWN
           end.map(&:value)
         end
 
+        public_class_method def self.fact_record(opts = {})
+          eng = (opts[:engagement_id] || 'default').to_s
+          dir = File.join(Dir.home, '.pwn', 'engagements', eng)
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, 'facts.jsonl')
+          row = {
+            kind: (opts[:kind] || 'host').to_s,
+            value: opts[:value],
+            source_session: opts[:source_session].to_s,
+            confidence: (opts[:confidence] || 0.7).to_f,
+            at: Time.now.utc.iso8601
+          }
+          File.open(path, 'a') { |f| f.puts(JSON.generate(row)) }
+          row.merge(path: path)
+        end
+
+        public_class_method def self.facts_prompt(opts = {})
+          eng = (opts[:engagement_id] || 'default').to_s
+          path = File.join(Dir.home, '.pwn', 'engagements', eng, 'facts.jsonl')
+          return '' unless File.file?(path)
+
+          rows = File.readlines(path).filter_map do |ln|
+            JSON.parse(ln, symbolize_names: true)
+          rescue JSON::ParserError
+            nil
+          end
+          return '' if rows.empty?
+
+          "FACTS #{rows.map { |r| "#{r[:kind]}=#{r[:value]}" }.join(' ')}"
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors
@@ -490,6 +521,20 @@ module PWN
               ports: 'optional - comma/space separated ports (defaults to 80,443)'
             )
 
+            # Append a typed engagement fact (port, cred, host, vuln).
+            #{self}.fact_record(
+              engagement_id: 'optional - engagement id (defaults to default)',
+              kind: 'optional - port|cred|host|vuln (defaults to host)',
+              value: 'required - fact value',
+              source_session: 'optional - session id that discovered the fact',
+              confidence: 'optional - 0.0..1.0 (defaults to 0.7)'
+            )
+
+            # One-line FACTS block for the system prompt.
+            #{self}.facts_prompt(
+              engagement_id: 'optional - engagement id (defaults to default)'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "

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

@@ -4,6 +4,7 @@ require 'digest'
 require 'json'
 require 'fileutils'
 require 'securerandom'
+require 'time'
 
 module PWN
   module AI
@@ -163,16 +164,31 @@ module PWN
 
         public_class_method def self.invalid_payload(opts = {})
           hint = opts[:hint].to_s
+          tok = opts[:offending_token].to_s
           {
             stdout: '',
             stderr: hint,
             exit: 2,
             error: 'invalid_payload',
+            code: (opts[:code] || 'SYNTAX_DENY').to_s,
+            rule_id: (opts[:rule_id] || 'payload').to_s,
+            offending_token: tok,
+            suggestion: opts[:suggestion].to_s,
             hint: hint,
             shell: opts[:shell] || shell_name
           }
         end
 
+        public_class_method def self.denial(opts = {})
+          {
+            code: opts[:code].to_s,
+            rule_id: opts[:rule_id].to_s,
+            token: opts[:token].to_s,
+            offending_token: opts[:offending_token] || opts[:token].to_s,
+            suggestion: opts[:suggestion].to_s
+          }
+        end
+
         public_class_method def self.host_load(opts = {})
           return { ncpu: 1, load1: 0.0, mem_avail_mb: 0 } unless opts.is_a?(Hash)
 
@@ -407,8 +423,11 @@ module PWN
           scope = YAML.safe_load_file(path, permitted_classes: [Symbol]) || {}
           return nil if scope.nil? || scope.empty?
 
-          allow = Array(scope['cidr_allowlist'] || scope[:cidr_allowlist]).map(&:to_s)
-          domains = Array(scope['domain_allowlist'] || scope[:domain_allowlist]).map(&:to_s)
+          expiry = (scope['expiry'] || scope[:expiry]).to_s
+          return denial(code: 'SCOPE_DENY', rule_id: 'expiry', token: expiry, suggestion: 'renew ~/.pwn/scope.yaml expiry') unless expiry.empty? || Time.parse(expiry) >= Time.now
+
+          allow = Array(scope['cidr_allowlist'] || scope[:cidr_allowlist] || scope['cidrs'] || scope[:cidrs]).map(&:to_s)
+          domains = Array(scope['domain_allowlist'] || scope[:domain_allowlist] || scope['domains'] || scope[:domains]).map(&:to_s)
           return nil if allow.empty? && domains.empty?
 
           ips = cmd.scan(/\b\d{1,3}(?:\.\d{1,3}){3}\b/)
@@ -418,7 +437,7 @@ module PWN
           hit = bad_ip || bad_host
           return nil unless hit
 
-          "Refused: #{hit} is outside ~/.pwn/scope.yaml allowlists."
+          denial(code: 'SCOPE_DENY', rule_id: 'allowlist', token: hit, suggestion: 'use an in-scope host or CIDR')
         rescue StandardError
           nil
         end
@@ -552,10 +571,23 @@ module PWN
               required: 'optional - Array required value consumed by #coerce_args'
             )
 
-            # Run invalid payload and return its result
+            # Build a machine-readable invalid_payload denial (SYNTAX_DENY by default).
             #{self}.invalid_payload(
-              hint: 'optional - hint value consumed by #invalid_payload',
-              shell: 'optional - shell value consumed by #invalid_payload (defaults to shell_name)'
+              hint: 'optional - operator-facing hint string',
+              shell: 'optional - shell name (defaults to shell_name)',
+              code: 'optional - denial code (defaults to SYNTAX_DENY)',
+              rule_id: 'optional - rule identifier (defaults to payload)',
+              offending_token: 'optional - exact rejected token span',
+              suggestion: 'optional - how to rewrite the payload'
+            )
+
+            # Build a machine-readable guard denial (SCOPE_DENY, CANARY_DENY, ...).
+            #{self}.denial(
+              code: 'required - denial code such as SCOPE_DENY',
+              rule_id: 'optional - rule identifier',
+              token: 'optional - out-of-scope host or CIDR',
+              offending_token: 'optional - exact rejected token span',
+              suggestion: 'optional - how to stay in scope'
             )
 
             # Run host load and return its result

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

@@ -17,21 +17,42 @@ PWN::AI::Agent::Registry.register(
         evidence: { type: 'string' },
         poc: { type: 'string' },
         poc_artifacts: { type: 'array', items: { type: 'string' } },
-        session_id: { type: 'string' }
+        session_id: { type: 'string' },
+        op: { type: 'string' },
+        parent_id: { type: 'string' },
+        engagement_id: { type: 'string' }
       },
-      required: %w[title]
+      required: %w[]
     }
   },
   handler: lambda { |args|
-    PWN::Plugins::Findings.record(
-      title: args[:title] || args['title'],
-      severity: args[:severity] || args['severity'],
-      host: args[:host] || args['host'],
-      evidence: args[:evidence] || args['evidence'],
-      poc: args[:poc] || args['poc'],
-      poc_artifacts: args[:poc_artifacts] || args['poc_artifacts'],
-      session_id: args[:session_id] || args['session_id']
-    )
+    op = (args[:op] || args['op'] || 'record').to_s
+    case op
+    when 'query'
+      PWN::Plugins::Findings.query(host: args[:host] || args['host'])
+    when 'chain'
+      PWN::Plugins::Findings.chain(
+        parent_id: args[:parent_id] || args['parent_id'],
+        title: args[:title] || args['title'],
+        severity: args[:severity] || args['severity'],
+        poc_artifacts: args[:poc_artifacts] || args['poc_artifacts'],
+        poc: args[:poc] || args['poc'],
+        session_id: args[:session_id] || args['session_id']
+      )
+    when 'export'
+      PWN::Plugins::Findings.render(report_name: 'findings')
+    else
+      PWN::Plugins::Findings.record(
+        title: args[:title] || args['title'],
+        severity: args[:severity] || args['severity'],
+        host: args[:host] || args['host'],
+        evidence: args[:evidence] || args['evidence'],
+        poc: args[:poc] || args['poc'],
+        poc_artifacts: args[:poc_artifacts] || args['poc_artifacts'],
+        session_id: args[:session_id] || args['session_id'],
+        engagement_id: args[:engagement_id] || args['engagement_id']
+      )
+    end
   }
 )
 PWN::AI::Agent::Registry.register(

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

@@ -11,7 +11,7 @@ PWN::AI::Agent::Registry.register(
     parameters: {
       type: 'object',
       properties: {
-        action: { type: 'string', description: 'start|status|stop|triage' },
+        action: { type: 'string', description: 'start|status|stop|triage|minimize' },
         in_dir: { type: 'string' },
         out_dir: { type: 'string' },
         target: { type: 'string' },
@@ -37,6 +37,8 @@ PWN::AI::Agent::Registry.register(
       PWN::Plugins::Jobs.stop(id: args[:id] || args['id'])
     when 'triage'
       PWN::Plugins::AFLplusplus.crash_triage(out_dir: args[:out_dir] || args['out_dir'])
+    when 'minimize'
+      PWN::Plugins::AFLplusplus.minimize(crash: args[:crash] || args['crash'], out: args[:out] || args['out'], target: args[:target] || args['target'])
     else
       { error: "unknown action #{act}" }
     end