Usage
vulcn crawl [url] [options]
Arguments
| Argument | Description | Required |
|---|
url | Target URL (overrides target in .vulcn.yml) | No |
Options
| Option | Description | Default |
|---|
-d, --depth <n> | Maximum crawl depth | from config |
-m, --max-pages <n> | Maximum pages to visit | from config |
-b, --browser <browser> | Browser to use (chromium, firefox, webkit) | from config |
--headless | Run in headless mode | from config |
--no-headless | Run with visible browser | - |
-t, --timeout <ms> | Page timeout in milliseconds | from config |
--no-same-origin | Allow following cross-origin links | - |
--run | Auto-run scans after crawl | false |
.vulcn.yml under scan.* and crawl.*.
Description
The crawl command automates the discovery of forms and injectable inputs across a web application. It reads the target from .vulcn.yml and generates one session file per discovered form in the sessions/ directory.
This is essential for automated scanning — point it at a target, let it discover attack surfaces, and optionally chain directly into scanning with --run.
How It Works
- Reads target from
.vulcn.yml (or CLI arg) and crawl settings
- Visits pages and discovers all links (BFS)
- Follows links up to
--depth levels deep
- Identifies forms and standalone inputs on each page
- Generates a session file per form with all injectable inputs marked
- Captures
CapturedRequest HTTP metadata for each form (used by Tier 1 HTTP fast scan)
- Saves sessions to
sessions/
- Optionally chains into
vulcn run with --run
The CapturedRequest metadata enables Tier 1 scanning — HTTP-level payload
testing via fetch() at ~50ms/payload. This runs automatically when you
vulcn run a crawled session. See Browser Driver for
details. Examples
Basic Crawl
Reads target and settings from .vulcn.yml, crawls the site, saves sessions to sessions/.
Override Target URL
vulcn crawl https://example.com
Deep Crawl
Follow links 3 levels deep, visiting up to 50 pages.
Crawl → Scan Pipeline
Crawls the site, then automatically runs security tests on every discovered form using the payload types configured in .vulcn.yml.
Authenticated Crawl
Crawl pages behind login using stored credentials:
# First store credentials
vulcn store admin password
# Then crawl — auth is auto-discovered from auth/state.enc
vulcn crawl
auth/state.enc is found, Vulcn will:
- Decrypt the credentials file using
VULCN_KEY or an interactive prompt
- Launch a browser and navigate to the login URL
- Auto-detect the login form and fill credentials
- Capture the browser’s storage state (cookies + localStorage)
- Use the authenticated context for crawling
Benchmarking Against DVWA
# Start DVWA
docker run -d -p 8080:80 vulnerables/web-dvwa
# Initialize project
vulcn init http://localhost:8080
# Store DVWA credentials
vulcn store admin password
# Authenticated crawl + scan
vulcn crawl --run
The --run flag is the fastest way to go from zero to a full security
assessment. It chains crawling directly into scanning without any manual
session management.
Output
The crawl command generates session files named by page and form:
✔ Crawl complete: 5 pages, 3 forms found
✔ Saved 3 session(s) to sessions/
📋 Generated Sessions
1. Crawl: /search — form 1 (query)
1 injectable input(s), 3 steps
2. Crawl: /login — form 1 (username, password)
2 injectable input(s), 4 steps
3. Crawl: /contact — form 1 (name, email, message)
3 injectable input(s), 5 steps
Next steps:
vulcn run
name: "Crawl: /search — form 1 (query)"
driver: browser
driverConfig:
startUrl: https://example.com/search
browser: chromium
headless: true
steps:
- id: step-1
type: browser.navigate
url: https://example.com/search
- id: step-2
type: browser.input
selector: 'form:nth-of-type(1) [name="query"]'
value: test
injectable: true
- id: step-3
type: browser.click
selector: form:nth-of-type(1) button
See Also
- vulcn store — Store credentials for authenticated crawling
- vulcn run — Run security tests on generated sessions
- vulcn record — Manually record browser interactions
