pwn 0.5.615 → 0.5.618

data/bin/pwn_gqrx_scanner

@@ -72,6 +72,33 @@ PWN::Driver::Parser.new do |options|
   options.on('-wLOC', '--location=LOC', '<Optional - Location string to include in AI analysis (e.g. "New York, NY", 90210, GPS coords, etc.)>') do |l|
     opts[:location] = l
   end
+  options.on('--fft-scan', '<Optional - Use fast FFT-based panoramic scanning via #fast_scan_range (much faster) instead of #scan_range. Applies to profile or --scan-ranges>') do |f|
+    opts[:fft_scan] = f
+  end
+
+  options.on('-SRATE', '--sample-rate=RATE', '<Optional --fft-scan - Visible span/sample_rate in Hz (default 1_000_000)>') do |s|
+    opts[:sample_rate] = s
+  end
+
+  options.on('-NINT', '--nfft=INT', '<Optional --fft-scan - FFT bin size (default 2048)>') do |n|
+    opts[:nfft] = n
+  end
+
+  options.on('-AINT', '--avg=INT', '<Optional --fft-scan - FFT averages (default 2)>') do |a|
+    opts[:avg] = a
+  end
+
+  options.on('-CSEC', '--capture-secs=SEC', '<Optional --fft-scan - Capture seconds per chunk (default 0.03)>') do |c|
+    opts[:capture_secs] = c
+  end
+
+  options.on('--keep-spectrum', '<Optional --fft-scan - Keep full spectrum data in output (large)>') do |k|
+    opts[:keep_spectrum] = k
+  end
+
+  options.on('-ODB', '--strength-offset-db=FLOAT', '<Optional - Power offset in dB (default 0.0)>') do |o|
+    opts[:strength_offset_db] = o
+  end
 end.parse!
 
 begin
@@ -146,24 +173,54 @@ begin
   # Merge opts one last time to ensure parameters passed to the driver are included
   opts.merge!(band_plans[profile.to_sym]) unless profile.nil?
 
-  PWN::SDR::GQRX.scan_range(
-    gqrx_sock: gqrx_sock,
-    ranges: ranges,
-    demodulator_mode: demodulator_mode,
-    bandwidth: bandwidth,
-    audio_gain_db: audio_gain_db,
-    squelch: squelch,
-    precision: precision,
-    strength_lock: strength_lock,
-    rf_gain: rf_gain,
-    intermediate_gain: intermediate_gain,
-    baseband_gain: baseband_gain,
-    keep_looping: keep_looping,
-    scan_log: scan_log,
-    decoder: decoder,
-    location: location
-  )
-  puts 'Scan Complete.'
+  fft_scan = opts[:fft_scan]
+  sample_rate = opts[:sample_rate] || 1_000_000
+  sample_rate = sample_rate.to_i
+  nfft = opts[:nfft] || 2048
+  nfft = nfft.to_i
+  avgv = opts[:avg] || 2
+  avgv = avgv.to_i
+  capture_secs = opts[:capture_secs] || 0.03
+  capture_secs = capture_secs.to_f
+  keep_spectrum = opts[:keep_spectrum] ? true : false
+  strength_offset_db = opts[:strength_offset_db]
+  strength_offset_db = strength_offset_db.to_f unless strength_offset_db.nil?
+
+  if fft_scan
+    puts '[*] --fft-scan requested: using fast FFT panoramic mode (#fast_scan_range)'
+    fast_resp = PWN::SDR::GQRX.fast_scan_range(
+      gqrx_sock: gqrx_sock,
+      ranges: ranges,
+      sample_rate: sample_rate,
+      nfft: nfft,
+      avg: avgv,
+      capture_secs: capture_secs,
+      strength_lock: strength_lock,
+      keep_spectrum: keep_spectrum,
+      strength_offset_db: strength_offset_db,
+      scan_log: scan_log
+    )
+    puts "FFT Scan complete: #{fast_resp[:total]} signals found."
+  else
+    PWN::SDR::GQRX.scan_range(
+      gqrx_sock: gqrx_sock,
+      ranges: ranges,
+      demodulator_mode: demodulator_mode,
+      bandwidth: bandwidth,
+      audio_gain_db: audio_gain_db,
+      squelch: squelch,
+      precision: precision,
+      strength_lock: strength_lock,
+      rf_gain: rf_gain,
+      intermediate_gain: intermediate_gain,
+      baseband_gain: baseband_gain,
+      keep_looping: keep_looping,
+      scan_log: scan_log,
+      decoder: decoder,
+      location: location
+    )
+    puts 'Scan Complete.'
+  end
 rescue StandardError => e
   raise e
 rescue Interrupt

data/documentation/AI-Integration.md

@@ -1,36 +1,52 @@
-# AI & LLM Integration
+# AI / LLM Integration — `PWN::AI`
 
-PWN integrates deeply with multiple LLMs for both interactive and autonomous operation.
+One agent loop, five interchangeable engines. Swap providers by changing one
+line in `~/.pwn/config.yml`; the tool-calling contract is normalised so the
+agent code never cares which model is behind it.
 
-## Supported Providers
+![Multi-provider integration](diagrams/ai-integration-tool-calling.svg)
 
-- OpenAI
-- Anthropic
-- Google Gemini
-- xAI Grok (full OAuth device flow support, public client)
-- Ollama (local)
-- Others via extensible client design
+## Supported engines
 
-## Primary Entry Points
+| Engine | Client | Auth | Notes |
+|---|---|---|---|
+| `openai` | `PWN::AI::OpenAI` | `key:` | function-calling native |
+| `anthropic` | `PWN::AI::Anthropic` | `key:` | tool-use native |
+| `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) — see skill `xai_grok_oauth_device_flow` |
+| `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
+| `ollama` | `PWN::AI::Ollama` | none | local, `base_url:` + `model:` |
 
-- `PWN::AI::*` (OpenAI, Anthropic, Grok, etc.)
-- `PWN::AI::Agent` — the autonomous tool-calling harness
-- `pwn-ai` command inside REPL launches the TUI
+## Selecting an engine
 
-## Tool Calling
+```yaml
+# ~/.pwn/config.yml
+ai:
+  engine: grok
+  grok:
+    oauth: true   # first run opens https://accounts.x.ai/… device page
+```
 
-The agent can call:
-- `pwn_eval` (full PWN namespace + Ruby)
-- `shell`
-- skills
-- memory (recall/remember)
-- learning & metrics
+```ruby
+# at runtime
+PWN::Env[:ai][:engine] = :ollama
+```
 
-OAuth for Grok is configured via `PWN::Config` and follows modern device-code flows (no client secrets).
+## Direct client use (no agent)
 
-See:
-- [pwn-ai Agent](pwn-ai-Agent.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
-- `lib/pwn/ai/` in source
+```ruby
+resp = PWN::AI::Anthropic.chat(
+  messages: [{ role: 'user', content: 'Explain CVE-2024-1234 in one line' }]
+)
+puts resp[:content]
+```
 
-[[Diagrams]]
+## Model diversity in Swarm
+
+Because each persona in [`agents.yml`](Swarm.md) can override `engine:`, an
+`agent_debate` can literally pit Claude against Grok against a local Llama —
+real antagonism, not one model role-playing three voices.
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md)
+
+[← Home](Home.md)

data/documentation/AWS.md

@@ -0,0 +1,57 @@
+# `PWN::AWS` — Cloud Security (90 service wrappers)
+
+One thin module per AWS service, each wrapping the official `aws-sdk-*` gem
+with the PWN `opts = {}` convention so they compose in the REPL and in
+`pwn_eval`.
+
+![AWS cloud security](diagrams/aws-cloud-security.svg)
+
+## Credentials
+
+Standard AWS SDK chain: `~/.aws/credentials` profile, env vars
+(`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`), or
+instance profile. Optionally pin in `~/.pwn/config.yml` under `aws:`.
+
+## Quick enumeration
+
+```ruby
+PWN::AWS::STS.get_caller_identity
+PWN::AWS::IAM.list_users
+PWN::AWS::EC2.describe_instances(region: 'us-east-1')
+PWN::AWS::S3.list_buckets
+PWN::AWS::Lambda.list_functions
+```
+
+CLI: `pwn_aws_describe_resources -r us-east-1 -o out/`
+
+## Service groups
+
+| Group | Modules |
+|---|---|
+| Identity | `IAM` `STS` `CognitoIdentity` `CognitoIdentityProvider` `CognitoSync` `DirectoryService` |
+| Compute | `EC2` `ECS` `ECR` `Lambda` `LambdaPreview` `Batch` `Lightsail` `ElasticBeanstalk` `AutoScaling` `ApplicationAutoScaling` `AppStream` |
+| Storage | `S3` `Glacier` `EFS` `StorageGateway` `Snowball` |
+| Data | `DynamoDB` `DynamoDBStreams` `RDS` `Redshift` `ElastiCache` `SimpleDB` `ElasticsearchService` |
+| Network | `Route53` `Route53Domains` `ElasticLoadBalancing` `ElasticLoadBalancingV2` `APIGateway` `CloudFront` `DirectConnect` `WAF` `WAFRegional` `Shield` |
+| Crypto | `KMS` `CloudHSM` `ACM` |
+| Ops / Logs | `CloudTrail` `CloudWatch` `CloudWatchLogs` `CloudWatchEvents` `ConfigService` `SSM` `Health` `Inspector` `XRay` |
+| Dev | `CodeBuild` `CodeCommit` `CodeDeploy` `CodePipeline` |
+| Messaging | `SNS` `SQS` `SES` `Pinpoint` `Kinesis` `KinesisAnalytics` `Firehose` |
+| ML / Media | `Rekognition` `Polly` `MachineLearning` `Lex` `ElasticTranscoder` |
+| Infra | `CloudFormation` `CloudSearch` `CloudSearchDomain` `OpsWorks` `OpsWorksCM` `ServiceCatalog` `DataPipleline` `EMR` `SWF` `States` |
+| IoT / Other | `IoT` `IoTDataPlane` `DeviceFarm` `GameLift` `Workspaces` `Support` `Budgets` `ImportExport` `SMS` `DatabaseMigrationService` `ApplicationDiscoveryService` `MarketplaceCommerceAnalytics` `MarketplaceMetering` |
+
+## Offensive patterns
+
+- **Enumerate** → `IAM` policies, `EC2` userdata, `Lambda` env vars, `S3`
+  bucket ACLs, `SSM` parameters.
+- **Misconfig** → public `S3`, wildcard `IAM` actions, unencrypted `RDS`,
+  missing `CloudTrail`.
+- **Escalate** → `iam:PassRole` + `lambda:Invoke`, `ssm:SendCommand`,
+  `ec2:RunInstances` with instance profile.
+- **Persist** → new access key, Lambda backdoor, EC2 userdata.
+
+Record everything with `extro_observe(source: 'aws', …)` so
+[Extrospection](Extrospection.md) can correlate later.
+
+[← Home](Home.md)

data/documentation/Agent-Tool-Registry.md

@@ -0,0 +1,56 @@
+# Agent Tool Registry
+
+`PWN::AI::Agent::Registry` (`lib/pwn/ai/agent/registry.rb`) collects every
+LLM-callable function into named **toolsets**. A persona is granted a subset of
+toolsets; the JSON-Schema for each tool is what the model actually sees.
+
+![Tool registry](diagrams/agent-tool-registry.svg)
+
+## Toolsets → Tools
+
+| Toolset | Tools | Backed by |
+|---|---|---|
+| `terminal` | `shell` | `Open3.capture3` on the host |
+| `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
+| `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
+| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` | `~/.pwn/skills/*.md` |
+| `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_reflect_toggle` | `PWN::AI::Agent::Learning` → `~/.pwn/learning.jsonl` |
+| `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` → `~/.pwn/extrospection.json` |
+| `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
+| `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
+
+## Adding a tool
+
+```ruby
+# lib/pwn/ai/agent/tools/my_thing.rb
+PWN::AI::Agent::Registry.register(
+  name: 'my_thing_do',
+  toolset: 'my_thing',
+  description: 'One-line summary the LLM will read.',
+  parameters: {
+    type: 'object',
+    properties: { target: { type: 'string' } },
+    required: ['target']
+  }
+) do |args|
+  PWN::Plugins::MyThing.do(target: args['target'])
+end
+```
+
+Drop the file in `lib/pwn/ai/agent/tools/`, it's auto-loaded on next launch.
+
+## Restricting a persona
+
+```yaml
+# ~/.pwn/agents.yml
+recon:
+  role: "Passive OSINT only. Never touch the target directly."
+  toolsets: [terminal, pwn, memory, extrospection]   # no swarm, no cron
+  engine: ollama
+```
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Swarm](Swarm.md)
+
+[← Home](Home.md)

data/documentation/Banner.md

@@ -0,0 +1,17 @@
+# `PWN::Banner` — Startup Art
+
+15 ANSI banners; one is picked at random every time the REPL starts. Purely
+cosmetic, entirely necessary.
+
+`Anon · Bubble · Cheshire · CodeCave · DontPanic · ForkBomb · FSociety ·
+JmpEsp · Matrix · Ninja · OffTheAir · Pirate · Radare2 · Radare2AI ·
+WhiteRabbit`
+
+```ruby
+puts PWN::Banner::Matrix.get
+welcome-banner          # REPL command: redraw a random one
+```
+
+Add your own: drop a module in `lib/pwn/banner/` implementing `self.get`.
+
+[← Home](Home.md)

data/documentation/Blockchain.md

@@ -0,0 +1,18 @@
+# `PWN::Blockchain` — BTC · ETH
+
+Lightweight helpers for on-chain recon and wallet interaction.
+Source: `lib/pwn/blockchain/*.rb`.
+
+| Module | Purpose |
+|---|---|
+| `PWN::Blockchain::BTC` | Address balance/UTXO lookup, tx broadcast, key helpers |
+| `PWN::Blockchain::ETH` | Address balance, contract call, event log query |
+
+Also exposed to the agent via `PWN::AI::Agent::BTC` for wallet-aware prompts.
+
+```ruby
+PWN::Blockchain::BTC.balance(address: 'bc1q…')
+PWN::Blockchain::ETH.call(contract: '0x…', method: 'owner()')
+```
+
+[← Home](Home.md)

data/documentation/Bounty.md

@@ -0,0 +1,21 @@
+# `PWN::Bounty` — Bug-Bounty Lifecycle Tooling
+
+| Module | Purpose |
+|---|---|
+| `PWN::Bounty::LifecycleAuthzReplay` | Record an authenticated browser session, then replay every request under a *different* principal to surface horizontal/vertical authz bugs |
+
+Pairs naturally with:
+
+- [`PWN::WWW::HackerOne`](WWW.md) / `BugCrowd` / `Synack` — programme navigation
+- `PWN::Plugins::HackerOne` — submissions API
+- [`PWN::Plugins::BurpSuite`](BurpSuite.md) — capture the session to replay
+
+```ruby
+PWN::Bounty::LifecycleAuthzReplay.start(
+  har_path: 'admin_session.har',
+  replay_as: { cookie: 'session=LOW_PRIV_TOKEN' },
+  proxy: 'http://127.0.0.1:8080'
+)
+```
+
+[← Home](Home.md) · [WWW](WWW.md)

data/documentation/BurpSuite.md

@@ -1,26 +1,51 @@
-# Burp Suite Integration
+# `PWN::Plugins::BurpSuite` ⭐
 
-**Preferred** web application proxy and scanner in PWN.
+The **preferred** web proxy / scanner in PWN (see
+[Burp vs ZAP](Diagrams.md#burp--vs-zap-selection)). Wraps Burp Suite
+Professional's headless mode + REST API.
 
-## Why Burp Over ZAP
+![Web application testing](diagrams/web-application-testing.svg)
 
-Burp Suite Professional offers richer scanning, more comprehensive plugin ecosystem, and better active/passive scanning capabilities for modern web apps. Use `PWN::Plugins::BurpSuite` by default.
+## Configure
 
-## Key Methods (incomplete list - inspect in REPL)
+```yaml
+# ~/.pwn/config.yml
+burp:
+  jar: /opt/burpsuite_pro/burpsuite_pro.jar
+  api_key: <REST-API-KEY>
+  bind_ip: 127.0.0.1
+  proxy_port: 8080
+  api_port: 1337
+```
 
-- `PWN::Plugins::BurpSuite.start(...)`
-- `PWN::Plugins::BurpSuite.stop`
-- `PWN::Plugins::BurpSuite.get_sitemap(...)`
-- `PWN::Plugins::BurpSuite.send_request(...)`
-- Live spidering and scanning orchestration
-- Integration with TransparentBrowser for proxied browsing
+## Core methods
 
-## Typical Usage via Agent
+```ruby
+burp = PWN::Plugins::BurpSuite.start(headless: true)
 
-> "Start BurpSuite, configure TransparentBrowser to proxy through it, spider target, run active scan, report findings."
+# drive traffic through it
+b = PWN::Plugins::TransparentBrowser.open(
+      browser_type: :headless, proxy: 'http://127.0.0.1:8080')
+b[:browser].goto 'https://target'
 
-See `lib/pwn/plugins/burp_suite.rb` for full API and source.
+# scan
+PWN::Plugins::BurpSuite.active_scan(burp_obj: burp,
+                                    target_url: 'https://target')
+issues = PWN::Plugins::BurpSuite.get_scan_issues(burp_obj: burp)
 
-Also see [Plugins](Plugins.md) and [pwn-ai Agent](pwn-ai-Agent.md).
+PWN::Plugins::BurpSuite.stop(burp_obj: burp)
+```
 
-[[Diagrams]]
+## CLI drivers
+
+- `pwn_burp_suite_pro_active_scan -t URL -o out/`
+- `pwn_burp_suite_pro_active_rest_api_scan` — pure REST, no JVM spawn
+
+## Why preferred over ZAP
+
+Richer scanner, larger BApp ecosystem, more reliable REST surface. `Zaproxy`
+remains as an OSS fallback and is API-compatible enough that swapping is a
+one-line change.
+
+[← Home](Home.md) · [Transparent-Browser](Transparent-Browser.md) ·
+[Plugins](Plugins.md)

data/documentation/CLI-Drivers.md

@@ -0,0 +1,58 @@
+# CLI Drivers — `bin/pwn_*`
+
+52 headless executables, each a thin `OptionParser` wrapper over one plugin
+(or one workflow). They exist so CI/CD can call PWN without a REPL or an LLM.
+
+![Driver anatomy](diagrams/driver-framework.svg)
+
+## Full list
+
+```text
+pwn                              pwn_jenkins_thinBackup_aws_s3
+pwn_android_war_dialer           pwn_jenkins_update_plugins
+pwn_autoinc_version              pwn_jenkins_useradd
+pwn_aws_describe_resources       pwn_mail_agent
+pwn_bdba_groups                  pwn_msf_postgres_login
+pwn_bdba_scan                    pwn_nessus_cloud_scan_crud
+pwn_burp_suite_pro_active_rest_api_scan   pwn_nessus_cloud_vulnscan
+pwn_burp_suite_pro_active_scan   pwn_nexpose
+pwn_char_base64_encoding         pwn_nmap_discover_tcp_udp
+pwn_char_dec_encoding            pwn_openvas_vulnscan
+pwn_char_hex_escaped_encoding    pwn_pastebin_sample_filter
+pwn_char_html_entity_encoding    pwn_phone
+pwn_char_unicode_escaped_encoding  pwn_rdoc_to_jsonl
+pwn_char_url_encoding            pwn_sast
+pwn_crt_sh                       pwn_serial_check_voicemail
+pwn_defectdojo_engagement_create pwn_serial_msr206
+pwn_defectdojo_importscan        pwn_serial_qualcomm_commands
+pwn_defectdojo_reimportscan      pwn_serial_son_micro_sm132_rfid
+pwn_diff_csv_files_w_column_exclude  pwn_shodan_graphql_introspection
+pwn_domain_reversewhois          pwn_shodan_search
+pwn_fuzz_net_app_proto           pwn_simple_http_server
+pwn_gqrx_scanner                 pwn_web_cache_deception
+pwn_jenkins_create_job           pwn_www_checkip
+pwn_jenkins_create_view          pwn_www_uri_buster
+pwn_jenkins_install_plugin       pwn_xss_dom_vectors
+                                 pwn_zaproxy_active_rest_api_scan
+                                 pwn_zaproxy_active_scan
+```
+
+Run any with `--help` for its flags.
+
+## Typical CI usage
+
+```yaml
+# .gitlab-ci.yml
+sast:
+  image: 0dayinc/pwn:latest
+  script:
+    - pwn_sast -d "$CI_PROJECT_DIR" -o sast_out/
+    - pwn_defectdojo_importscan -f sast_out/report.json -e "$DD_ENGAGEMENT"
+```
+
+## Write your own
+
+See [Drivers](Drivers.md) — copy any file in `bin/`, swap the plugin call,
+`rake install`, done.
+
+[← Home](Home.md)

data/documentation/Configuration.md

@@ -0,0 +1,66 @@
+# Configuration — `~/.pwn/config.yml`
+
+Everything configurable lives in one YAML file, loaded by `PWN::Config` at
+startup and available in-process as `PWN::Env`.
+
+## Minimal example
+
+```yaml
+# ~/.pwn/config.yml
+ai:
+  engine: anthropic          # openai | anthropic | grok | gemini | ollama
+  anthropic:
+    key: sk-ant-…
+  openai:
+    key: sk-…
+  grok:
+    oauth: true              # RFC-8628 device flow, no client_secret
+  ollama:
+    base_url: http://localhost:11434
+    model: llama3.1:70b
+  agent:
+    max_iters:      40       # tool-loop cap per turn
+    max_depth:      3        # swarm recursion cap
+    auto_reflect:   true     # Learning.auto_reflect after every final answer
+    auto_extrospect: true    # Extrospection.auto_extrospect likewise
+
+burp:
+  jar: /opt/burpsuite_pro/burpsuite_pro.jar
+  api_key: …
+
+metasploit:
+  host: 127.0.0.1
+  port: 55553
+  user: msf
+  pass: …
+```
+
+## Reading / writing at runtime
+
+```ruby
+PWN::Env[:ai][:engine]                 # => :anthropic
+PWN::Env[:ai][:agent][:auto_reflect]   # => true
+PWN::Config.reload!
+```
+
+## Sections PWN looks for
+
+| Key path | Consumed by |
+|---|---|
+| `ai.engine` | `PWN::AI::Agent::Loop` — which client to instantiate |
+| `ai.<engine>.key` / `.oauth` | `PWN::AI::OpenAI` / `Anthropic` / `Grok` / `Gemini` / `Ollama` |
+| `ai.agent.max_iters` | hard stop on tool-call rounds |
+| `ai.agent.max_depth` | `Swarm` recursion guard |
+| `ai.agent.auto_reflect` | toggle `Learning.auto_reflect` |
+| `ai.agent.auto_extrospect` | toggle `Extrospection.auto_extrospect` |
+| `burp.*` | `PWN::Plugins::BurpSuite` |
+| `metasploit.*` | `PWN::Plugins::Metasploit` |
+| `zap.*` | `PWN::Plugins::Zaproxy` |
+| `shodan.key` / `hunter.key` / … | respective OSINT plugins |
+| `aws.*` | `PWN::AWS::*` (falls back to standard AWS SDK env/instance-profile) |
+
+## Other files under `~/.pwn/`
+
+See [Persistence](Persistence.md) for the full map.
+
+[← Home](Home.md)

data/documentation/Contributing.md

@@ -1,31 +1,45 @@
 # Contributing
 
-Contributions that expand PWN's offensive capabilities are highly welcome.
+## Repo layout
 
-## How to Help
+```text
+lib/pwn/                # all namespaces
+lib/pwn/plugins/        # 66 plugin modules
+lib/pwn/ai/agent/       # agent core
+lib/pwn/ai/agent/tools/ # LLM tool registrations
+bin/                    # 52 pwn_* drivers
+spec/                   # RSpec (incl. conventions_spec)
+documentation/          # this wiki + diagrams
+```
 
-- New plugins (especially zero-day research, exploitation primitives, novel AI integrations)
-- Improvements to existing modules
-- New SAST signatures
-- AI skills (see [Skills-Memory-Learning](Skills-Memory-Learning.md))
-- Better documentation / wiki pages
-- Bridges to more commercial/open security tools
-- Bug reports with clear reproduction steps
+## Conventions (enforced by `spec/conventions_spec.rb`)
 
-## Process
+1. Every public module method is `public_class_method def self.name(opts = {})`.
+2. Every arg-accepting `def self.*` uses **exactly** `(opts = {})` — no
+   positional args, no keyword args.
+3. Every module has `self.help` returning a usage string.
+4. `# frozen_string_literal: true` at the top of every `.rb`.
 
-1. Review [CONTRIBUTING.md](../CONTRIBUTING.md) in the repo root.
-2. Open an issue or PR on https://github.com/0dayInc/pwn
-3. For large features, discuss first via email (support@0dayinc.com) or GitHub.
+## Quality gates
 
-## Code Style
+```bash
+rvmsudo rake            # rubocop + rspec — must be zero offenses
+```
 
-Follow RuboCop (project is clean). Write self-documenting methods with parameter descriptions matching existing plugin style.
+## Adding a plugin
 
-## Access
+1. `lib/pwn/plugins/my_thing.rb` following the conventions above.
+2. Autoload entry in `lib/pwn/plugins.rb`.
+3. `spec/lib/pwn/plugins/my_thing_spec.rb`.
+4. Optional `bin/pwn_my_thing` driver (see [Drivers](Drivers.md)).
+5. Optional agent tool in `lib/pwn/ai/agent/tools/` (see
+   [Agent Tool Registry](Agent-Tool-Registry.md)).
+6. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+   relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
-If you have access to additional commercial LLMs, scanners, or bug bounty programs you are willing to integrate, please reach out.
+## Commit / release
 
-Thank you for helping push the state of open offensive security tooling forward!
+`./git_commit.sh` bumps `PWN::VERSION`, regenerates
+`third_party/pwn_rdoc.jsonl`, runs the gates, and pushes.
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/Cron.md

@@ -0,0 +1,47 @@
+# Cron — Scheduled Autonomous Jobs
+
+`PWN::Cron` (`lib/pwn/cron.rb`) stores job definitions in
+`~/.pwn/cron/jobs.yml` and can install a matching system-`crontab` line that
+invokes `PWN::Cron.run(<id>)` on schedule.
+
+![Cron scheduling](diagrams/cron-scheduling.svg)
+
+## Job kinds
+
+| Kind | Executed as | Use for |
+|---|---|---|
+| `prompt:` | `pwn --ai "<prompt>"` one-shot | "Re-scan scope nightly and diff findings" |
+| `ruby:` | `TOPLEVEL_BINDING.eval` in-process | Direct `PWN::Plugins` calls |
+| `script:` | `exec` external file | Anything not in Ruby |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `cron_create(schedule:, prompt:/ruby:/script:, install_crontab:)` | Define a job |
+| `cron_list` | id · name · schedule · enabled · last_run · last_status |
+| `cron_run(id:)` | Fire immediately (updates last_run/last_status) |
+| `cron_enable` / `cron_disable` | Toggle without deleting |
+| `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab — `crontab -e` yourself) |
+
+## Example
+
+```ruby
+cron_create(
+  name: 'nightly_scope_sweep',
+  schedule: '0 2 * * *',
+  prompt: 'extro_snapshot, then NmapIt sweep 10.0.0.0/24, extro_observe every '\
+          'new open port, extro_correlate, and post a one-paragraph summary.',
+  install_crontab: true
+)
+```
+
+At 02:00 the system cron fires `PWN::Cron.run`, which spins up a headless
+`pwn-ai` turn. Because `auto_reflect` and `auto_extrospect` are on, the run
+also updates Learning/Metrics/Extrospection — so tomorrow's interactive
+session already knows what changed overnight.
+
+**See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
+[CLI Drivers](CLI-Drivers.md)
+
+[← Home](Home.md)