███╗   ██╗███████╗██████╗ ██╗   ██╗
   ████╗  ██║██╔════╝██╔══██╗██║   ██║
   ██╔██╗ ██║█████╗  ██████╔╝██║   ██║
   ██║╚██╗██║██╔══╝  ██╔══██╗╚██╗ ██╔╝
   ██║ ╚████║███████╗██║  ██║ ╚████╔╝ 
   ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝  ╚═══╝  

   ██╗   ██╗██╗██████╗ ███████╗██████╗ 
   ██║   ██║██║██╔══██╗██╔════╝██╔══██╗
   ██║   ██║██║██████╔╝█████╗  ██████╔╝
   ╚██╗ ██╔╝██║██╔═══╝ ██╔══╝  ██╔══██╗
    ╚████╔╝ ██║██║     ███████╗██║  ██║
     ╚═══╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝

NERV-VIPER: Advanced Security Engine for Web Applications

Observe → Decide → Act → Detect

What is NERV-VIPER?

NERV-VIPER is a CLI tool that autonomously explores web applications and finds bugs. Point it at a URL — it launches a browser, navigates pages, clicks buttons, fills forms, and reports every issue it finds.

Two exploration modes:

• AI-guided (via 5-Model Cloud Roster) — qwen3-coder-next:cloud decides what to click, type, and explore, while ALL models enhance and validate reports independently with synthesis
• Systematic (fallback) — BFS crawl of all links, buttons, and forms

Bug detection covers:

• 🔴 Console errors & unhandled JS exceptions
• 🌐 Network failures (4xx, 5xx, timeouts)
• 🖼️ Broken images
• ♿ Accessibility issues (missing alt text, unlabeled inputs)
• ⚡ Performance problems (slow TTFB, slow DOM load)
• 🔒 Security red flags (HTTP forms, inline handlers)
• 📐 UI issues (horizontal overflow)

Quick Start

# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Run a scan
node bin/nerv.js run https://example.com

# Verify your token/plan
nerv --token

Global install (optional)

npm link
nerv run https://example.com

Usage

nerv run <url> [options]

Options:
  --headed             Run browser visibly (not headless)
  --max-actions <n>    Maximum actions to perform (default: 30)
  --max-time <s>       Maximum time in seconds (default: 700)
  --model <name>       Ollama model to use (default: mistral)
  --no-ai              Disable AI, use systematic exploration only
  -o, --output <dir>   Output directory for reports (default: ./reports)
  --token [key]        Show subscription status or update token
  -v, --verbose        Enable verbose debug logging

Examples

# Quick scan with defaults
nerv run https://myapp.com

# Thorough scan with visible browser
nerv run https://myapp.com --headed --max-actions 50 --max-time 700

# Systematic scan (no Ollama needed)
nerv run https://myapp.com --no-ai --max-actions 40

# Use deepseek-coder instead of mistral
nerv run https://myapp.com --model deepseek-coder

# Check subscription status
nerv --token

# Update access token
nerv --token NV-PLAN-XXXX-XXXX

AI Mode (Multi-Model Integration)

When you use the --ai flag, NERV-VIPER will automatically:

1. Detect if Ollama is installed on your system
2. Install Ollama if missing (works on Windows, macOS, and Linux)
3. Start the Ollama daemon in the background
4. Iteratively Pull all 5 cloud models if they are missing (qwen3-coder-next:cloud, kimi-k2.5:cloud, glm-5:cloud, qwen3.5:397b-cloud, gemma4:31b-cloud)

# Just use --ai — Nerv handles the rest
nerv https://example.com --ai

No manual setup required. If Ollama or the models are missing, Nerv will prompt you to install them automatically.

Manual install (optional): If you prefer to set up Ollama yourself, visit ollama.com and run ollama pull qwen3-coder-next:cloud.

NERV-VIPER auto-detects Ollama. If it's not running or --ai is not passed, NERV-VIPER falls back to systematic rule-based mode.

Subscription Management

NERV-VIPER uses a token-based subscription system to manage AI and rule-based scan limits.

Verify or Update Token

Use the --token command to check your current status or apply a new access key:

# View current plan, status, and remaining scans
nerv --token

# Update to a new access key (after plan upgrade)
nerv --token NV-PLAN-XXXX-XXXX-XXXX

Upgrading Your Plan

If you reach your daily or monthly limits, you can upgrade your plan at: 👉 https://www.nerv.co.in

After upgrading, you will receive a new Access Key. Use nerv --token <key> to activate it.

Report Format

Reports are saved as JSON in ./reports/:

{
  "meta": {
    "tool": "NERV-VIPER Security Engine",
    "version": "3.5.2",
    "timestamp": "2026-04-14T...",
    "targetUrl": "https://example.com"
  },
  "summary": {
    "totalBugs": 5,
    "critical": 0,
    "high": 2,
    "medium": 2,
    "low": 1,
    "byType": {
      "console_error": 2,
      "network_error": 1,
      "accessibility": 2
    },
    "pagesVisited": 8,
    "actionsPerformed": 30,
    "durationSeconds": 45
  },
  "bugs": [ ... ],
  "visitedUrls": [ ... ]
}

Architecture

bin/nerv.js          CLI entry point (Commander.js)
src/
├── index.js         Main orchestrator
├── agent.js         Agent loop (observe → decide → act → detect)
├── crawler.js       Playwright browser control
├── ollama.js        Ollama LLM integration
├── detector.js      Bug detection (console, network, DOM, perf, security)
├── reporter.js      JSON report generation
└── logger.js        ANSI-colored console output

Requirements

• Node.js ≥ 18
• Playwright (auto-installed)
• Ollama (optional, for AI mode)
  • Recommended models: mistral, deepseek-coder
  • Works on 8GB Mac

License

MIT