Skip to main content

​
Prerequisites

Requirements: - Node.js v18 or higher - npm, pnpm, or yarn

​
Installation

1

Install the CLI

npm install -g vulcn
2

Initialize configuration

Create a vulcn.config.yml file with default plugins:
vulcn init
This creates a config file with the official detection plugins pre-configured:
# vulcn.config.yml
version: "1"
plugins:
  - name: "@vulcn/plugin-payloads"
    config:
      builtin: true
  - name: "@vulcn/plugin-detect-xss"
    config:
      detectDialogs: true
      detectConsole: true
      severity: high
settings:
  browser: chromium
  headless: true
3

Install browsers (optional)

Vulcn uses Playwright for browser automation. Browsers are installed automatically on first use, but you can install them manually:
vulcn install
Or install all browsers:
vulcn install --all

​
Record Your First Session

1

Start recording

Open a browser and record your interactions with the target application:
vulcn record https://example.com --output session.vulcn.yml
The browser opens and records everything you do. Fill out forms, click buttons, navigate pages—Vulcn captures it all.
2

Interact with the app

In the browser:
  1. Navigate to a page with input fields
  2. Fill out a form (login, search, comment, etc.)
  3. Submit the form
  4. Close the browser when done
3

Session saved

Your interactions are saved to session.vulcn.yml:
name: Session 2026-02-06
startUrl: https://example.com
browser: chromium
steps:
  - id: step_001
    type: navigate
    url: https://example.com
    timestamp: 1707192000000
  - id: step_002
    type: fill
    selector: input[name="search"]
    value: test query
    timestamp: 1707192005000
  - id: step_003
    type: click
    selector: button[type="submit"]
    timestamp: 1707192010000

​
Run Security Tests

1

Execute tests

Run the recorded session with security payloads:
vulcn run session.vulcn.yml
By default, Vulcn uses the xss-basic payload set and the @vulcn/plugin-detect-xss plugin for detection.
2

Choose specific payloads

Test with specific payload sets:
vulcn run session.vulcn.yml --payload xss-basic sqli-basic
Or use PayloadsAllTheThings:
vulcn run session.vulcn.yml --payload payloadbox:xss
3

Review findings

If vulnerabilities are found, you’ll see output like:
🔍 Running security tests
   Session: Session 2026-02-06
   Payloads: xss-basic
   Payload count: 15
   Browser: chromium
   Headless: true

⚠️  FINDING: XSS Confirmed: alert() executed
   Step: step_002
   Payload: <script>alert('XSS')</script>...
   URL: https://example.com/search

📊 Results
   Steps executed: 3
   Payloads tested: 45
   Duration: 12.3s

🚨 1 findings detected!

[HIGH] XSS Confirmed: alert() executed
  Type: xss
  Step: step_002
  URL: https://example.com/search
  Payload: <script>alert('XSS')</script>

​
Explore Payloads

List all available built-in payloads: 
vulcn payloads
Output: 
📦 Available Payloads

XSS
  xss-basic        Basic XSS payloads (15 payloads)
  xss-event        Event handler XSS (12 payloads)
  xss-svg          SVG-based XSS (8 payloads)
  xss-polyglot     Polyglot XSS payloads (5 payloads)

SQL Injection
  sqli-basic       Basic SQLi payloads (10 payloads)
  sqli-error       Error-based SQLi (8 payloads)
  sqli-blind       Blind SQLi payloads (6 payloads)
  sqli-union       UNION-based SQLi (5 payloads)

Other
  ssrf-basic       SSRF payloads (5 payloads)
  xxe-basic        XXE payloads (4 payloads)
  cmd-basic        Command injection (6 payloads)
  path-traversal   Path traversal (8 payloads)
  open-redirect    Open redirect (4 payloads)

Total: 13 payload sets, 91 payloads

​
Next Steps

CLI Reference

Learn all available commands and options

Configuration

Customize Vulcn with vulcn.config.yml

Plugins

Add more detection capabilities with plugins

Custom Payloads

Load custom payloads from files