AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents when working with code in this repository.
4 
5## Project Overview
6 
7WPScan is a WordPress security scanner written in Ruby. It provides WordPress-specific scanning capabilities including vulnerability detection, enumeration, and password attacks.
8 
9**Key characteristics:**
10- Ruby gem with CLI tool
11- Architecture based on Controllers, Finders, and Models (MVC-like pattern)
12- Uses local database (in `$XDG_CACHE_HOME/wpscan/db` or `~/.cache/wpscan/db`, or `~/.wpscan/db` for existing installations) that syncs with WPScan API
13- Scanner framework lives in `lib/wpscan/` (Target, Browser, Controller::Base, Scan, Finders, Formatter, etc.) alongside the WordPress-specific code
14- Supports WordPress-specific security scanning features
15 
16## Development Best Practices
17 
18### Code Style
19- **Always run rubocop after making changes** to ensure code style compliance
20- Run `bundle exec rubocop -a` to auto-fix issues
21- For specific files: `bundle exec rubocop -a file1.rb file2.rb`
22- The project uses RuboCop for Ruby style enforcement
23 
24## Development Commands
25 
26### Setup
27```bash
28bundle install
29```
30 
31### Running Tests
32```bash
33# Run all tests except slow ones (default for PRs)
34bundle exec rspec --tag ~slow
35 
36# Run full test suite (includes slow tests, only runs on master)
37bundle exec rspec
38 
39# Run specific test file
40bundle exec rspec spec/path/to/file_spec.rb
41 
42# Run with coverage
43bundle exec rspec  # Coverage enabled by default via .simplecov
44```
45 
46### Code Quality
47```bash
48# Run rubocop
49bundle exec rubocop
50 
51# Auto-fix rubocop issues
52bundle exec rubocop -a
53 
54# IMPORTANT: Always run rubocop after making code changes
55# Run on specific files being modified:
56bundle exec rubocop -a path/to/file1.rb path/to/file2.rb
57```
58 
59### Building
60```bash
61# Build the gem (runs rubocop & rspec automatically)
62bundle exec rake build
63 
64# Install gem locally
65gem install pkg/wpscan-*.gem
66```
67 
68### Running WPScan Locally
69```bash
70# From source (outside git repo to avoid load path conflicts)
71ruby -Ilib bin/wpscan --url https://example.com
72 
73# Or after installing as gem
74wpscan --url https://example.com
75```
76 
77### Database Operations
78```bash
79# Update local database
80wpscan --update
81 
82# The database is stored in $XDG_CACHE_HOME/wpscan/db or ~/.cache/wpscan/db (new installations)
83# or ~/.wpscan/db (existing installations)
84```
85 
86## Architecture
87 
88### Core Components
89 
90**Entry Point:**
91- `bin/wpscan` - CLI executable that chains controllers together
92- Controllers are chained using `<<` operator and executed in order
93 
94**Controllers (app/controllers/):**
95Controllers orchestrate the scanning process. The `Core` controller (app/controllers/core.rb) is implicitly handled by the scanner framework via `WPScan::Scan.new` and runs before the explicitly chained controllers. The explicit chain in bin/wpscan executes in this order:
961. `VulnApi` - API token setup for vulnerability data
972. `CustomDirectories` - Custom wp-content/plugins directory detection
983. `InterestingFindings` - Header analysis, robots.txt, readme files
994. `WpVersion` - WordPress version detection
1005. `MainTheme` - Active theme detection
1016. `Enumeration` - Plugins, themes, users, etc (see CLI options)
1027. `PasswordAttack` - Brute force attacks
1038. `Aliases` - Handle legacy CLI options
104 
105Note: The `Core` controller handles database updates, WordPress detection, and banner display during the `before_scan` phase.
106 
107**Finders (app/finders/):**
108Finders implement detection strategies for various WordPress components. Each finder type has multiple strategies (passive, aggressive, mixed):
109- `WpVersion` - Detects WordPress version
110- `MainTheme` - Detects active theme
111- `Plugins` - Plugin enumeration strategies
112- `Themes` - Theme enumeration strategies
113- `Users` - User enumeration (author ID brute forcing, API endpoints, etc)
114- `InterestingFindings` - Backup files, debug logs, etc
115- `ConfigBackups` - Config backup file detection (wp-config.php backups)
116- `DbExports` - Database export file detection
117- `Medias` - Media/attachment enumeration via brute forcing
118- `Timthumbs` - Timthumb script detection at known locations
119- `Passwords` - Authentication mechanisms (wp-login, XML-RPC)
120 
121**Models (app/models/):**
122Domain objects representing WordPress components:
123- `WpItem` - Base class for plugins/themes
124- `Plugin`, `Theme` - Specific WordPress items
125- `WpVersion` - WordPress version with vulnerability info
126- `InterestingFinding` - Security-relevant findings
127- `ConfigBackup` - Detected wp-config.php backup files
128- `DbExport` - Detected database export files
129- `Media` - Media attachments found on the site
130- `Timthumb` - Timthumb script instances
131- `XMLRPC` - XML-RPC interface details
132 
133**Database (lib/wpscan/db/):**
134- `Updater` - Syncs local database with WPScan API
135- `VulnApi` - API client for vulnerability data
136- `DynamicFinders` - Auto-generated finders from database metadata
137- `Fingerprints` - Version detection fingerprints
138- Database stored in `$XDG_CACHE_HOME/wpscan/db/` or `~/.cache/wpscan/db/` (new installations) or `~/.wpscan/db/` (existing installations) by default (overridden in specs to `spec/fixtures/db/`)
139 
140### Important Patterns
141 
142**Scanner framework:**
143The scanner framework lives under `WPScan::` alongside the WordPress-specific code. Core framework classes — `WPScan::Target`, `WPScan::Browser`, `WPScan::Controller::{Base,Core}`, `WPScan::ParsedCli`, `WPScan::Vulnerability`, `WPScan::Model::{InterestingFinding,XMLRPC}`, etc. — are single unified classes, not split across framework/WordPress layers. WordPress-specific behavior is mixed in via modules (e.g. `WPScan::Target::Platform::WordPress` is included into `WPScan::Target`). Option parsing delegates to the external `opt_parse_validator` gem.
144 
145**Dynamic Finders:**
146Finders can be dynamically generated from database metadata (see `lib/wpscan/db/dynamic_finders/`). This allows version detection strategies to be data-driven.
147 
148**Slug Classification:**
149WordPress slugs (plugin/theme names) are converted to Ruby class names via `classify_slug` helper (lib/wpscan/helper.rb). Handles edge cases:
150- Slugs starting with digits get prefixed with `D_` (e.g., `123-plugin` becomes `D_123Plugin`)
151- Special characters are converted to underscores
152- Slugs with all non-latin characters become `HexSlug_` followed by hex-encoded bytes
153 
154**API Requests Tracking:**
155The codebase tracks API requests via `WPScan.api_requests` class variable to monitor usage against API limits.
156 
157## Testing
158 
159### Test Structure
160- Tests use RSpec with WebMock for HTTP stubbing
161- Fixtures in `spec/fixtures/`
162- Shared examples in `spec/shared_examples/`
163- Coverage via SimpleCov (configured in `.simplecov`)
164 
165### Key Testing Helpers (spec/spec_helper.rb)
166- `rspec_parsed_options(args)` - Parse CLI arguments
167- `df_expected_all` - Dynamic finder test expectations
168- `vuln_api_data_for(path)` - Load vulnerability API fixtures
169- `redefine_constant(constant, value)` - Override WPScan constants for testing
170 
171### Test Tags
172- `--tag ~slow` - Excludes slow tests (default for CI on PRs)
173- Full suite runs only on master pushes
174 
175## Common Gotchas
176 
177**Active Support Must Be First:**
178`active_support/all` must be required before other gems to avoid encoding issues with JSON (see lib/wpscan.rb:4-6).
179 
180**Running Outside Git Repo:**
181When using `wpscan` from source, run it outside the git repo to avoid load path conflicts.
182 
183**Database Location:**
184Tests override `DB_DIR` to `spec/fixtures/db/`. Production uses `$XDG_CACHE_HOME/wpscan/db` or `~/.cache/wpscan/db` (new installations) or `~/.wpscan/db` (existing installations).
185 
186**Port Normalization:**
187WebMock adapter has custom port normalization for Typhoeus (spec/spec_helper.rb:63-96) to handle default ports.
188 
189## API Integration
190 
191**WPScan API:**
192- Requires API token (via `--api-token` or `WPSCAN_API_TOKEN` env var or config file)
193- Free tier: 25 requests/day
194- One request per WordPress version, plugin, and theme detected
195- Response tracking via `Typhoeus.on_complete` hook in lib/wpscan.rb
196 
197**Configuration Files:**
198WPScan loads options from (in order):
1991. `$XDG_CONFIG_HOME/wpscan/scan.json` or `$XDG_CONFIG_HOME/wpscan/scan.yml` (if `XDG_CONFIG_HOME` is set)
2002. `~/.config/wpscan/scan.json` or `~/.config/wpscan/scan.yml` (if `XDG_CONFIG_HOME` is not set)
2013. `~/.wpscan/scan.json` or `~/.wpscan/scan.yml`
2024. `pwd/.wpscan/scan.json` or `pwd/.wpscan/scan.yml`
203 
204Use snake_case for CLI options in config (e.g., `api_token`, `max_threads`).
205