pwn 0.5.613 → 0.5.615

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

@@ -31,7 +31,7 @@ module PWN
               pwn        : #{pwn_version}
               session_id : #{session_id || '(none)'}
 
-            #{memory_block}#{skills_block}TOOL USE
+            #{memory_block}#{skills_block}#{learning_block}#{metrics_block}TOOL USE
               Use the provided function tools to act on the host. A reply with
               no tool_calls is treated as your FINAL answer to the user.
               Prefer `pwn_eval` for anything in the PWN:: namespace and `shell`
@@ -70,15 +70,35 @@ module PWN
           return '' unless defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) && !PWN::Skills.empty?
 
           lines = PWN::Skills.map do |name, meta|
-            first = meta[:content].to_s.lines.first.to_s.strip
+            first = meta[:content].to_s.lines.reject { |l| l.strip.empty? || l.start_with?('---') }.first.to_s.strip
             first = first[0, 100]
-            "  - #{name}: #{first}"
+            rc = Array(meta[:references]).length
+            ref_tag = rc.positive? ? " [#{rc} refs]" : ''
+            "  - #{name}: #{first}#{ref_tag}"
           end
           "SKILLS (call skill_view to read full body)\n#{lines.join("\n")}\n\n"
         rescue StandardError
           ''
         end
 
+        private_class_method def self.learning_block
+          return '' unless defined?(PWN::AI::Agent::Learning)
+
+          ctx = PWN::AI::Agent::Learning.to_context(limit: 5).to_s
+          ctx.strip.empty? ? '' : "LEARNING\n#{ctx}"
+        rescue StandardError
+          ''
+        end
+
+        private_class_method def self.metrics_block
+          return '' unless defined?(PWN::AI::Agent::Metrics)
+
+          ctx = PWN::AI::Agent::Metrics.to_context(limit: 8).to_s
+          ctx.strip.empty? ? '' : ctx
+        rescue StandardError
+          ''
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'pwn/ai/agent/registry'
+require 'pwn/ai/agent/learning'
+require 'pwn/ai/agent/metrics'
+
+# Expose the self-improvement engine to the model so it can actively
+# participate in the learning loop: log outcomes, trigger reflection,
+# promote successful workflows into reusable skills, and inspect its own
+# effectiveness metrics.
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_note_outcome',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_note_outcome',
+    description: 'Record the outcome of a task attempt so future pwn-ai ' \
+                 'runs learn from it. Successes reinforce approaches; ' \
+                 'failures become avoidance lessons injected into every ' \
+                 'subsequent system prompt.',
+    parameters: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'Short description of what was attempted.' },
+        success: { type: 'boolean', description: 'Did the attempt achieve its goal?' },
+        details: { type: 'string', description: 'Evidence, error text, or notes.' },
+        tags: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[task success]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Learning.note_outcome(
+      task: args[:task],
+      success: args[:success],
+      details: args[:details],
+      tags: args[:tags]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_reflect',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_reflect',
+    description: 'Analyse a completed session transcript and persist up to ' \
+                 '5 durable lessons into PWN::Memory. Uses LLM introspection ' \
+                 'when enabled, otherwise a heuristic extractor.',
+    parameters: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'PWN::Sessions id to analyse.' },
+        dry_run: { type: 'boolean', default: false }
+      },
+      required: %w[session_id]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Learning.reflect(
+      session_id: args[:session_id],
+      dry_run: args[:dry_run]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_distill_skill',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_distill_skill',
+    description: 'Promote a successful workflow into a reusable skill under ' \
+                 '~/.pwn/skills so it appears in every future system prompt.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'snake_case skill name.' },
+        session_id: { type: 'string', description: 'Session to mine for the procedure.' },
+        content: { type: 'string', description: 'Explicit markdown body (overrides session mining).' },
+        references: { type: 'array', items: { type: 'string' }, description: 'Optional URLs / CWE / CVE / ATT&CK / NIST references.' }
+      },
+      required: %w[name]
+    }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |args|
+    PWN::AI::Agent::Learning.distill_skill(
+      name: args[:name],
+      session_id: args[:session_id],
+      content: args[:content],
+      references: args[:references]
+    )
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'learning_stats',
+  toolset: 'learning',
+  schema: {
+    name: 'learning_stats',
+    description: 'Return self-effectiveness metrics: outcome success rate, ' \
+                 'skills known, memory size, and per-tool telemetry.',
+    parameters: { type: 'object', properties: {}, required: [] }
+  },
+  check: -> { defined?(PWN::AI::Agent::Learning) },
+  handler: lambda { |_args|
+    PWN::AI::Agent::Learning.stats.merge(
+      tool_metrics: PWN::AI::Agent::Metrics.summary(limit: 10)
+    )
+  }
+)

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

@@ -6,19 +6,30 @@ require 'pwn/ai/agent/registry'
 # Thin wrappers around the PWN::Skills store (~/.pwn/skills/*.md) so the
 # model can list/read/write reusable procedures. PromptBuilder injects
 # the index (name + first line); skill_view loads the full body on demand.
+#
+# Each skill may carry a :references Array (URLs, CWE/CVE/ATT&CK ids,
+# NIST 800-53 controls, docs) parsed from YAML front-matter or a
+# "## References" markdown section. References let the agent cite
+# authoritative sources when applying a skill and mirror the
+# PWN::SAST::*.security_references convention.
 
 PWN::AI::Agent::Registry.register(
   name: 'skill_list',
   toolset: 'skills',
   schema: {
     name: 'skill_list',
-    description: 'List available pwn-ai skills (name + first line of content).',
+    description: 'List available pwn-ai skills (name + first line + reference count).',
     parameters: { type: 'object', properties: {}, required: [] }
   },
   check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
   handler: lambda { |_args|
     PWN::Skills.map do |name, meta|
-      { name: name, type: meta[:type], summary: meta[:content].to_s.lines.first.to_s.strip[0, 120] }
+      {
+        name: name,
+        type: meta[:type],
+        summary: meta[:content].to_s.lines.first.to_s.strip[0, 120],
+        references: Array(meta[:references]).length
+      }
     end
   }
 )
@@ -28,7 +39,7 @@ PWN::AI::Agent::Registry.register(
   toolset: 'skills',
   schema: {
     name: 'skill_view',
-    description: 'Read the full content of a named skill.',
+    description: 'Read the full content of a named skill, including its references.',
     parameters: {
       type: 'object',
       properties: { name: { type: 'string' } },
@@ -41,7 +52,13 @@ PWN::AI::Agent::Registry.register(
     meta = PWN::Skills[key]
     raise ArgumentError, "no such skill: #{key}" unless meta
 
-    { name: key, type: meta[:type], path: meta[:path], content: meta[:content] }
+    {
+      name: key,
+      type: meta[:type],
+      path: meta[:path],
+      references: Array(meta[:references]),
+      content: meta[:content]
+    }
   }
 )
 
@@ -51,12 +68,20 @@ PWN::AI::Agent::Registry.register(
   schema: {
     name: 'skill_create',
     description: 'Save a new reusable skill (markdown procedure) to ~/.pwn/skills/. ' \
-                 'It will be listed in every future pwn-ai system prompt.',
+                 'It will be listed in every future pwn-ai system prompt. Optionally ' \
+                 'attach references (URLs, CWE/CVE ids, MITRE ATT&CK, NIST 800-53, docs).',
     parameters: {
       type: 'object',
       properties: {
         name: { type: 'string', description: 'lowercase, hyphens/underscores only' },
-        content: { type: 'string', description: 'Full markdown body of the skill.' }
+        content: { type: 'string', description: 'Full markdown body of the skill.' },
+        references: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional list of reference URLs / identifiers (CWE-79, T1059, ' \
+                       'https://..., NIST SI-3, etc.). Written as YAML front-matter and ' \
+                       'a "## References" section.'
+        }
       },
       required: %w[name content]
     }
@@ -66,11 +91,72 @@ PWN::AI::Agent::Registry.register(
     name = args[:name].to_s.gsub(/[^a-z0-9_-]/i, '_')
     raise ArgumentError, 'name is required' if name.empty?
 
+    body = args[:content].to_s
+    refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+
+    unless refs.empty?
+      # YAML front-matter (only if body doesn't already have one)
+      unless body.start_with?("---\n")
+        fm = "---\nreferences:\n#{refs.map { |r| "  - #{r}" }.join("\n")}\n---\n"
+        body = fm + body
+      end
+      # ## References section (only if not already present)
+      body = "#{body.rstrip}\n\n## References\n#{refs.map { |r| "- #{r}" }.join("\n")}\n" unless body =~ /^\#{1,3}\s*References\s*$/i
+    end
+
     dir = PWN::Config.pwn_skills_path
     FileUtils.mkdir_p(dir)
     path = File.join(dir, "#{name}.md")
-    File.write(path, args[:content].to_s)
+    File.write(path, body)
     PWN::Config.load_skills(pwn_skills_path: dir) # refresh PWN::Skills const
-    { saved: true, path: path, total: PWN::Skills.keys.length }
+    { saved: true, path: path, references: refs, total: PWN::Skills.keys.length }
+  }
+)
+
+PWN::AI::Agent::Registry.register(
+  name: 'skill_add_reference',
+  toolset: 'skills',
+  schema: {
+    name: 'skill_add_reference',
+    description: 'Append one or more references (URL, CWE/CVE id, MITRE ATT&CK ' \
+                 'technique, NIST control, doc link) to an existing skill.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Existing skill name.' },
+        references: { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[name references]
+    }
+  },
+  check: -> { defined?(PWN::Skills) && PWN::Skills.is_a?(Hash) },
+  handler: lambda { |args|
+    key  = args[:name].to_s.to_sym
+    meta = PWN::Skills[key]
+    raise ArgumentError, "no such skill: #{key}" unless meta
+
+    new_refs = Array(args[:references]).map(&:to_s).map(&:strip).reject(&:empty?)
+    raise ArgumentError, 'references must be a non-empty array' if new_refs.empty?
+
+    body     = File.read(meta[:path])
+    existing = Array(meta[:references])
+    add      = (new_refs - existing)
+
+    if body =~ /^(\#{1,3}\s*References\s*)$/i
+      # Append bullets right after the References heading block (end of file safest)
+      body = "#{body.rstrip}\n#{add.map { |r| "- #{r}" }.join("\n")}\n" unless add.empty?
+    else
+      body = "#{body.rstrip}\n\n## References\n#{(existing + add).uniq.map { |r| "- #{r}" }.join("\n")}\n"
+    end
+
+    File.write(meta[:path], body)
+    PWN::Config.load_skills(pwn_skills_path: File.dirname(meta[:path]))
+    {
+      saved: true,
+      name: key,
+      path: meta[:path],
+      added: add,
+      references: Array(PWN::Skills[key][:references])
+    }
   }
 )

data/lib/pwn/ai/agent.rb

@@ -23,6 +23,8 @@ module PWN
       autoload :Result,        'pwn/ai/agent/result'
       autoload :PromptBuilder, 'pwn/ai/agent/prompt_builder'
       autoload :Loop,          'pwn/ai/agent/loop'
+      autoload :Metrics,       'pwn/ai/agent/metrics'
+      autoload :Learning,      'pwn/ai/agent/learning'
 
       # Display a List of Every PWN::AI Module