Documentation

Overview

BRS-XSS is an advanced XSS vulnerability scanner designed for security researchers and penetration testers. It combines context-aware payload selection with DOM analysis to detect both reflected and DOM-based XSS vulnerabilities.

Key capabilities:

• Context-aware scanning - Automatically detects injection context and selects appropriate payloads
• DOM XSS detection - Headless browser analysis via Playwright
• WAF evasion - Built-in techniques to bypass common WAFs
• BRS-KB integration - Access to thousands of curated payloads
• Professional reports - PDF, SARIF, JSON, HTML output formats

Installation

PyPI (Recommended)

pip install brs-xss

From GitHub

pip install git+https://github.com/EPTLLC/BRS-XSS.git

Development Setup

git clone https://github.com/EPTLLC/BRS-XSS.git
cd BRS-XSS
pip install -e ".[dev]"

Docker

docker pull ghcr.io/eptllc/brs-xss:latest
docker run --rm ghcr.io/eptllc/brs-xss scan https://target.tld

Playwright (for DOM analysis)

# Install Playwright browsers
playwright install chromium

CLI Commands

BRS-XSS provides a comprehensive CLI interface.

Main Commands

Command	Description
brs-xss scan	Scan URL for XSS vulnerabilities
brs-xss kb	Knowledge base operations
brs-xss version	Show version information

Scanning

Basic Scan

brs-xss scan https://example.com/search?q=test

Deep Scan with DOM Analysis

brs-xss scan https://example.com --deep

Scan Options

Option	Description
--deep	Enable deep scanning with DOM analysis
--timeout	Request timeout in seconds (default: 30)
--max-depth	Maximum crawl depth (default: 3)
--output, -o	Output file path
--safe-mode	Conservative scanning (lower impact)
--verbose, -v	Verbose output

Knowledge Base

BRS-XSS integrates with BRS-KB for payload management.

View KB Info

brs-xss kb info

List Contexts

brs-xss kb list

Show Context Details

brs-xss kb show html_content

Reports

BRS-XSS generates professional security reports.

Supported Formats

• PDF - Professional report with executive summary
• SARIF - Static Analysis Results Interchange Format (CI/CD)
• JSON - Machine-readable format
• HTML - Interactive web report

Generate Report

# JSON output
brs-xss scan https://example.com -o results.json

# HTML report
brs-xss scan https://example.com -o report.html

Web UI

BRS-XSS includes a React-based web interface for interactive scanning.

Start Web UI

# Start backend and frontend
cd web_ui
python -m backend.main &
cd frontend && npm run dev

Features

• Real-time scan progress
• Interactive vulnerability explorer
• System resource monitoring
• Scan history and management
• Telegram notifications

Configuration

BRS-XSS can be configured via YAML files or environment variables.

Configuration File

# config/default.yaml
scanner:
  timeout: 30
  max_depth: 3
  user_agent: "BRS-XSS/4.0.0"

performance:
  mode: standard  # stealth, standard, maximum
  
kb:
  api_url: "https://brs-kb.easypro.tech/api"

Environment Variables

Variable	Description
BRS_XSS_SAFE_MODE	Enable safe mode (true/false)
BRS_KB_API_KEY	BRS-KB API key
BRS_XSS_TIMEOUT	Default timeout

CI/CD Integration

GitHub Actions

name: Security Scan
on: [push]

jobs:
  xss-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install BRS-XSS
        run: pip install brs-xss
      - name: Run Scan
        run: brs-xss scan ${{ github.event.repository.html_url }} -o results.json --safe-mode

GitLab CI

xss_scan:
  stage: test
  image: python:3.11-slim
  script:
    - pip install brs-xss
    - brs-xss scan $CI_PROJECT_URL -o results.json --safe-mode
  artifacts:
    reports:
      sast: results.json

Python API

BRS-XSS can be used programmatically in Python.

Basic Usage

from brsxss import Scanner

async def scan_target():
    scanner = Scanner()
    results = await scanner.scan_url(
        "https://example.com/search?q=test"
    )
    
    for vuln in results:
        if vuln.get("vulnerable"):
            print(f"Found: {vuln['parameter']} - {vuln['payload']}")

import asyncio
asyncio.run(scan_target())

With Configuration

from brsxss import Scanner
from brsxss.core.config import ScanConfig

config = ScanConfig(
    timeout=60,
    max_depth=5,
    enable_dom_analysis=True
)

scanner = Scanner(config=config)
results = await scanner.scan_url(url)