Open Knowledge for Security Community
Advanced XSS Intelligence Database for Researchers and Scanners
- Why BRS-KB?
- Installation
- Quick Start
- Available Contexts
- Features
- CLI Tool
- REST API Server
- Web UI
- Security Scanner Plugins
- SIEM Integration
- CI/CD Pipeline
- Usage
- API Reference
- Examples
- Contributing
- Project Structure
- Testing
- Statistics
- Troubleshooting
- License
- Project Info
- Related Projects
- Support Policy
- Acknowledgments
Comprehensive, community-driven knowledge base for Cross-Site Scripting (XSS) vulnerabilities
| Feature | Description |
|---|---|
| 27 Contexts | Covering classic and modern XSS vulnerability types |
| 194+ Payloads | Categorized with severity, tags, and WAF bypass info |
| REST API | Built-in HTTP server for Web UI and integrations |
| Zero Dependencies | Pure Python 3.8+ |
| SIEM Compatible | CVSS scores, CWE/OWASP mappings, severity levels |
| Open Source | MIT licensed, community contributions welcome |
| Production Ready | 81% test coverage, SQLite storage, modular architecture |
pip install brs-kbgit clone https://github.com/EPTLLC/BRS-KB.git
cd BRS-KB
pip install -e .Note: On first run, the system will automatically migrate payloads from in-memory storage to SQLite database (brs_kb/data/payloads.db). You can also run brs-kb migrate manually.
git clone https://github.com/EPTLLC/BRS-KB.git
cd BRS-KB
pip install -e ".[dev]"Requirements: Python 3.8+ • No external dependencies
# Setup PyPI configuration (one time only)
python3 scripts/publish.py setup
# Test publication process
python3 scripts/test_publish.py# Build and publish to PyPI
python3 scripts/publish.py
# Or manually:
python3 -m build
twine check dist/*
twine upload dist/*from brs_kb import get_vulnerability_details, list_contexts
# Get detailed XSS context information
details = get_vulnerability_details('html_content')
print(details['title']) # Cross-Site Scripting (XSS) in HTML Content
print(details['severity']) # critical
print(details['cvss_score']) # 8.8
print(details['cwe']) # ['CWE-79']
print(details['owasp']) # ['A03:2021']
# List all available contexts
contexts = list_contexts()
# ['css_context', 'default', 'dom_xss', 'html_attribute', ...]27 XSS Vulnerability Contexts (click to expand)
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
html_content |
XSS in HTML body/content | 407 | Critical | 8.8 |
html_attribute |
XSS in HTML attributes | 538 | Critical | 8.8 |
html_comment |
XSS in HTML comments | 77 | Medium | 5.4 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
javascript_context |
Direct JavaScript injection | 645 | Critical | 9.0 |
js_string |
JavaScript string injection | 628 | Critical | 8.8 |
js_object |
JavaScript object injection | 628 | High | 7.8 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
css_context |
CSS injection & style attrs | 684 | High | 7.1 |
svg_context |
SVG-based XSS vectors | 297 | High | 7.3 |
markdown_context |
Markdown rendering XSS | 110 | Medium | 6.1 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
json_value |
JSON context XSS | 81 | Medium | 6.5 |
xml_content |
XML/XHTML XSS vectors | 90 | High | 7.1 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
url_context |
URL/protocol-based XSS | 554 | High | 7.5 |
dom_xss |
DOM-based XSS (client-side) | 359 | High | 7.4 |
template_injection |
Client-side template injection | 116 | Critical | 8.6 |
postmessage_xss |
PostMessage API vulnerabilities | 134 | High | 7.4 |
wasm_context |
WebAssembly context XSS | 119 | Medium | 6.8 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
websocket_xss |
WebSocket real-time XSS | 431 | High | 7.5 |
service_worker_xss |
Service Worker injection | 557 | High | 7.8 |
webrtc_xss |
WebRTC P2P communication XSS | 565 | High | 7.6 |
indexeddb_xss |
IndexedDB storage XSS | 577 | Medium | 6.5 |
webgl_xss |
WebGL shader injection | 611 | Medium | 6.1 |
shadow_dom_xss |
Shadow DOM encapsulation bypass | 539 | High | 7.3 |
custom_elements_xss |
Custom Elements XSS | 590 | High | 7.1 |
http2_push_xss |
HTTP/2 Server Push XSS | 558 | Medium | 6.8 |
graphql_xss |
GraphQL API injection | 642 | High | 7.4 |
iframe_sandbox_xss |
iframe sandbox bypass | 591 | Medium | 6.3 |
| Context | Description | Lines | Severity | CVSS |
|---|---|---|---|---|
default |
Generic XSS information | 165 | High | 7.1 |
Each context includes security metadata:
{
# Core Information
"title": "Cross-Site Scripting (XSS) in HTML Content",
"description": "Detailed vulnerability explanation...",
"attack_vector": "Real-world attack techniques...",
"remediation": "Actionable security measures...",
# Security Metadata
"severity": "critical", # low | medium | high | critical
"cvss_score": 8.8, # CVSS 3.1 base score
"cvss_vector": "CVSS:3.1/...", # Full CVSS vector string
"reliability": "certain", # tentative | firm | certain
"cwe": ["CWE-79"], # CWE identifiers
"owasp": ["A03:2021"], # OWASP Top 10 mapping
"tags": ["xss", "html", "reflected"] # Classification tags
}Advanced payload analysis with automatic context detection and ML-ready features:
from brs_kb.reverse_map import find_contexts_for_payload, get_defenses_for_context, predict_contexts_ml_ready
# Automatic context detection with confidence scoring
info = find_contexts_for_payload("<script>alert(1)</script>")
# → {'contexts': ['html_content'],
# 'severity': 'critical',
# 'confidence': 1.0,
# 'analysis_method': 'pattern_matching',
# 'matched_patterns': 1}
# Modern XSS context detection
websocket_info = find_contexts_for_payload('WebSocket("wss://evil.com")')
# → {'contexts': ['websocket_xss'], 'severity': 'high', 'confidence': 1.0}
# ML-ready analysis with feature extraction
ml_analysis = predict_contexts_ml_ready('<script>alert(document.cookie)</script>')
# → {'contexts': ['html_content'], 'features': {'length': 39, 'has_script': True, ...}}
# Enhanced defense mapping with modern techniques
defenses = get_defenses_for_context('websocket_xss')
# → [{'defense': 'input_validation', 'priority': 1, 'required': True, 'tags': ['websocket']},
# {'defense': 'csp', 'priority': 1, 'required': True, 'tags': ['policy']}, ...]BRS-KB includes a comprehensive command-line interface for security research and testing:
# Install the package
pip install brs-kb
# Show all available commands
brs-kb --help
# Show system information
brs-kb info
# List all XSS contexts
brs-kb list-contexts
# Get detailed information about a context
brs-kb get-context websocket_xss
# Analyze a payload
brs-kb analyze-payload "<script>alert(1)</script>"
# Search payloads in database
brs-kb search-payloads websocket --limit 5
# Test payload effectiveness
brs-kb test-payload "<script>alert(1)</script>" html_content
# Generate comprehensive report
brs-kb generate-report
# Validate database integrity
brs-kb validate
# Export data
brs-kb export contexts --format json --output contexts.json
# Set language
brs-kb language ru
# Migrate to SQLite database
brs-kb migrate
# Start API server for Web UI
brs-kb serve
# Start API server on custom port with metrics
brs-kb serve --port 8080 --metricsAvailable Commands:
info- Show system information and statisticslist-contexts- List all available XSS contexts with severityget-context <name>- Get detailed vulnerability informationanalyze-payload <payload>- Analyze payload with reverse mappingsearch-payloads <query>- Search payload database with relevance scoringtest-payload <payload> <context>- Test payload effectiveness in contextgenerate-report- Generate comprehensive system analysisvalidate- Validate payload database integrityexport <type> --format <format>- Export data (payloads, contexts, reports)language [lang]- Set or list supported languages (EN, RU, ZH, ES)migrate [--force]- Migrate payloads to SQLite databaseserve [--port PORT] [--host HOST] [--metrics]- Start REST API server for Web UI
from brs_kb import get_vulnerability_details
def enrich_finding(context_type, url, payload):
kb_data = get_vulnerability_details(context_type)
return {
'url': url,
'payload': payload,
'title': kb_data['title'],
'severity': kb_data['severity'],
'cvss_score': kb_data['cvss_score'],
'cwe': kb_data['cwe'],
'description': kb_data['description'],
'remediation': kb_data['remediation']
}
# Use in scanner
finding = enrich_finding('dom_xss', 'https://target.com/app', 'location.hash')from brs_kb import get_vulnerability_details
def create_security_event(context, source_ip, target_url):
kb = get_vulnerability_details(context)
return {
'event_type': 'xss_detection',
'severity': kb['severity'],
'cvss_score': kb['cvss_score'],
'cvss_vector': kb['cvss_vector'],
'cwe': kb['cwe'],
'owasp': kb['owasp'],
'source_ip': source_ip,
'target': target_url,
'requires_action': kb['severity'] in ['critical', 'high']
}from brs_kb import get_vulnerability_details
def generate_report(context, url, payload):
kb = get_vulnerability_details(context)
return f"""
# {kb['title']}
**Severity**: {kb['severity'].upper()} (CVSS {kb['cvss_score']})
**CWE**: {', '.join(kb['cwe'])}
## Vulnerable URL
{url}
## Proof of Concept{payload}
## Description
{kb['description']}
## Remediation
{kb['remediation']}
"""
from brs_kb import list_contexts, get_vulnerability_details
# Create XSS learning materials
for context in list_contexts():
details = get_vulnerability_details(context)
print(f"Context: {context}")
print(f"Severity: {details.get('severity', 'N/A')}")
print(f"Attack vectors: {details['attack_vector'][:200]}...")
print("-" * 80)BRS-KB includes plugins for popular security testing tools:
- Real-time XSS payload analysis during proxying
- Automatic context detection for intercepted requests
- Integration with 27 XSS contexts
- Professional security team interface
Installation: Copy plugins/burp_suite/BRSKBExtension.java to Burp extensions
- Automated XSS scanning with BRS-KB intelligence
- Context-aware payload injection
- WAF bypass technique detection
- Professional security workflow support
Installation: Load plugins/owasp_zap/brs_kb_zap.py in ZAP scripts
- 200+ categorized XSS payloads
- Context-specific testing (27 XSS contexts)
- WAF bypass technique detection
Installation: Copy templates to Nuclei templates directory
BRS-KB integrates with enterprise SIEM systems for real-time XSS monitoring and alerting.
| Platform | Features | Installation |
|---|---|---|
| Splunk | Dashboards, alerting, trend analysis | siem_connectors/splunk/brs_kb_app.tar.gz |
| Elasticsearch | Kibana dashboards, ML anomaly detection | siem_connectors/elastic/ |
| Graylog | GELF integration, stream processing | siem_connectors/graylog/ |
# Splunk
cp siem_connectors/splunk/brs_kb_app.tar.gz $SPLUNK_HOME/etc/apps/
# Elasticsearch (Logstash)
cp siem_connectors/elastic/logstash.conf /etc/logstash/conf.d/
# Graylog
# Import content pack via Graylog UISee siem_connectors/README.md for detailed configuration.
BRS-KB includes comprehensive CI/CD configurations for automated testing and deployment:
- Multi-Python version testing (3.8-3.12)
- Code quality checks and security scanning
- Package building and PyPI deployment
- Performance testing and coverage reporting
- Parallel testing across Python versions
- Package building and deployment
- Documentation deployment (GitLab Pages)
- Performance and security testing
- Declarative pipeline with parallel execution
- Artifact management and deployment
- Notification integration and reporting
- Enterprise-grade pipeline management
Automated CI/CD pipeline setup and configuration.
Quick Setup:
python3 scripts/setup_cicd.pySee DEVELOPMENT_PLAN.md for detailed CI/CD documentation.
BRS-KB includes comprehensive documentation in multiple languages:
- English (EN) - Primary documentation (this file)
- Russian (RU) - docs/README.ru.md
- Chinese (ZH) - docs/README.zh.md
- Spanish (ES) - docs/README.es.md
brs-kb language ru # Switch to Russian
brs-kb language zh # Switch to Chinese
brs-kb language es # Switch to Spanish
brs-kb language en # Switch to English
brs-kb language --list # List all supported languagesThe Web UI supports full localization in all 4 languages:
- Localized interface elements
- Context-specific examples
- Security terminology adaptation
BRS-KB includes a built-in REST API server for Web UI integration and programmatic access:
# Start API server (default: http://0.0.0.0:8080)
brs-kb serve
# Custom port and host
brs-kb serve --port 9000 --host 127.0.0.1
# With Prometheus metrics endpoint
brs-kb serve --metrics --metrics-port 8000| Endpoint | Method | Description |
|---|---|---|
/api/info |
GET | System information |
/api/health |
GET | Health check |
/api/contexts |
GET | List all XSS contexts |
/api/contexts/<id> |
GET | Get context details |
/api/payloads |
GET | List payloads (with filters) |
/api/payloads/search?q=<query> |
GET | Search payloads |
/api/analyze |
GET/POST | Analyze payload |
/api/defenses?context=<ctx> |
GET | Get recommended defenses |
/api/stats |
GET | Platform statistics |
/api/languages |
GET | Supported languages |
/api/language |
POST | Set language |
from brs_kb import start_api_server, start_metrics_server
# Start API server programmatically
server = start_api_server(port=8080, host='0.0.0.0')
# Start metrics server for Prometheus
metrics = start_metrics_server(port=8000)
# Check if running
print(server.is_running()) # True
# Stop servers
server.stop()
metrics.stop()BRS-KB includes a modern React-based web interface for visual exploration and testing:
BRSKB Web UI - Modern React-based web interface with full API integration
Features:
- Visual exploration of 27 XSS contexts
- Interactive playground for payload analysis
- Real-time statistics dashboard
- Payloads browser with search and filtering
- API documentation viewer
- Multi-language support (EN, RU, ZH, ES)
- Responsive design for all devices
- Automatic fallback when API unavailable
Pages:
- Home - Overview and quick stats
- Contexts - Browse all XSS vulnerability contexts
- Payloads - Search and filter 194+ payloads
- Playground - Interactive payload analyzer
- Dashboard - Statistics and charts
- API Docs - REST API documentation
Installation:
# Terminal 1: Start API server
brs-kb serve --port 8080
# Terminal 2: Start Web UI
cd web_ui
npm install
npm startConfiguration:
Set REACT_APP_API_URL environment variable to change API endpoint:
REACT_APP_API_URL=http://localhost:8080/api npm startAccess: http://localhost:3000 after starting development server
See web_ui/README.md for detailed Web UI documentation.
See examples/ directory for integration examples:
| Example | Description |
|---|---|
basic_usage.py |
Basic API usage and functionality |
scanner_integration.py |
Integration into security scanners |
reverse_mapping.py |
Enhanced reverse mapping with ML-ready features |
payload_database.py |
200+ payload database with testing API |
cli_demo.py |
Command-line interface demonstration |
plugin_demo.py |
Security scanner plugin integration |
cicd_demo.py |
CI/CD pipeline demonstration |
multilanguage_demo.py |
Multi-language support demonstration |
integrated_demo.py |
Complete system integration showcase |
Run examples:
# Python examples
python3 examples/basic_usage.py
python3 examples/scanner_integration.py
python3 examples/cli_demo.py
python3 examples/plugin_demo.py
python3 examples/integrated_demo.py
# CLI commands
brs-kb info # System information
brs-kb list-contexts # All XSS contexts
brs-kb get-context websocket_xss # Context details
brs-kb analyze-payload "<script>alert(1)</script>" # Payload analysis
brs-kb search-payloads websocket --limit 5 # Search payloads
brs-kb test-payload "<script>alert(1)</script>" html_content # Test effectiveness
brs-kb generate-report # Comprehensive report
brs-kb validate # Database validation
brs-kb export contexts --format json # Export data
# Security scanner integration
nuclei -t plugins/nuclei/templates/brs-kb-xss.yaml -u https://target.com
# SIEM integration
python3 siem_connectors/splunk/brs_kb_splunk_connector.py --api-key YOUR_KEY --splunk-url https://splunk.company.com:8088
# CI/CD pipeline
python3 scripts/setup_cicd.py
# Multi-language support
brs-kb language ru
brs-kb language --listGet detailed information about a vulnerability context.
details = get_vulnerability_details('html_content')Get list of all available contexts.
contexts = list_contexts() # ['css_context', 'default', 'dom_xss', ...]Get knowledge base information (version, build, contexts count).
info = get_kb_info()
print(f"Version: {info['version']}, Total contexts: {info['total_contexts']}")Get version string.
version = get_kb_version() # "1.0.0"Import from brs_kb.reverse_map:
Advanced payload analysis with automatic context detection and confidence scoring.
ML-ready analysis with feature extraction for future machine learning integration.
Get recommended defenses for a context with enhanced metadata and implementation details.
Get comprehensive information about a defense mechanism including bypass difficulty and tags.
Analyze payload against pattern database returning matches with confidence scores.
Get reverse mapping system information including version, capabilities, and statistics.
Universal lookup function supporting payload, context, defense, and pattern queries.
Get all payloads effective in a specific context.
Get all payloads by severity level.
Search payloads with relevance scoring.
Test payload effectiveness in specific context.
Get payload database statistics and information.
Get CLI instance for programmatic use.
CLI Commands:
brs-kb info- System informationbrs-kb list-contexts- List all XSS contextsbrs-kb get-context <name>- Context detailsbrs-kb analyze-payload <payload>- Payload analysisbrs-kb search-payloads <query>- Search payloadsbrs-kb test-payload <payload> <context>- Test effectivenessbrs-kb generate-report- Comprehensive reportbrs-kb validate- Database validationbrs-kb export <type>- Export data
Contributions from the security community are welcome.
- Add new XSS contexts
- Update existing contexts with new bypasses
- Improve documentation
- Report issues or outdated information
- Share real-world examples
Quick start:
git clone https://github.com/EPTLLC/BRS-KB.git
cd BRS-KB
git checkout -b feature/new-context
# Make changes
pytest tests/ -v
git commit -m "Add: New context for WebSocket XSS"
git push origin feature/new-context
# Open Pull RequestSee CONTRIBUTING.md for detailed guidelines.
BRS-KB/
brs_kb/ # Main package
__init__.py # Core API with public exports
api_server.py # REST API server for Web UI
metrics_server.py # Prometheus metrics server
schema.json # JSON Schema validation
reverse_map.py # Reverse mapping wrapper (backward compatibility)
reverse_map/ # Reverse mapping package (modular)
__init__.py
patterns.py # Context detection patterns
defenses.py # Defense strategies
analysis.py # Payload analysis
utils.py # Utility functions
i18n.py # Internationalization system
cli.py # CLI wrapper (backward compatibility)
cli/ # CLI package (modular)
__init__.py
__main__.py # Module execution entry point
cli.py # Main CLI class
parser.py # Argument parser
commands/ # Individual command modules
base.py # Base command class
list_contexts.py
get_context.py
analyze_payload.py
search_payloads.py
test_payload.py
generate_report.py
info.py
validate.py
export.py
language.py
migrate.py
serve.py # API server command
payload_testing.py # Payload testing framework
payloads_db.py # Payload database wrapper (backward compatibility)
payloads_db/ # Payload database package (modular)
__init__.py
data.py # In-memory database
models.py # Data models
operations.py # CRUD operations
queries.py # Query functions
search.py # Search functionality
info.py # Database info
testing.py # Testing utilities
payloads_db_sqlite.py # SQLite database implementation
migrations.py # Database migrations
contexts/ # 27 vulnerability contexts
html_content.py
javascript_context.py
websocket_xss.py
...
examples/ # Integration examples
tests/ # Test suite (pytest, 334 tests, 81% coverage)
docs/ # Multi-language documentation
i18n/locales/ # Translation files
plugins/ # Security scanner plugins
siem_connectors/ # SIEM system integrations
web_ui/ # React-based web interface
src/
services/api.js # API client for backend
pages/ # Page components
components/ # UI components
LICENSE # MIT License
CONTRIBUTING.md # Contribution guide
CHANGELOG.md # Version history
README.md # This file
# Run all tests (334 tests)
pytest tests/ -v
# Run with coverage (81% coverage)
pytest tests/ -v --cov=brs_kb --cov-report=term-missing
# Run specific test modules
pytest tests/test_basic.py -v # Basic functionality
pytest tests/test_cli.py -v # CLI commands
pytest tests/test_sqlite.py -v # SQLite database
pytest tests/test_api_server.py -v # REST API server
pytest tests/test_metrics_server.py -v # Prometheus metricsTest Coverage: 81% (334 tests passing)
| Metric | Value |
|---|---|
| Total Lines | ~19,500+ |
| Context Modules | 27 |
| Payload Database | 194+ |
| Test Coverage | 81% (334 tests) |
| CLI Commands | 12 commands |
| REST API Endpoints | 13 |
| Reverse Mapping Patterns | 29 |
| Security Scanner Plugins | 3 platforms |
| SIEM Integrations | 3 systems |
| Multi-Language Support | 4 languages |
| External Dependencies | 0 |
| Python Version | 3.8+ |
| Feature | Status |
|---|---|
| REST API Server | Supported |
| Prometheus Metrics | Supported |
| Web UI (React 18) | Supported |
| SQLite Database | Supported |
| Multi-Language Support | EN, RU, ZH, ES |
| Docker Support | Supported |
| Kubernetes Support | Supported |
| CI/CD Pipelines | GitHub, GitLab, Jenkins |
| ML-Ready Features | Supported |
| WAF Bypass Detection | 15+ payloads |
| Modern XSS Contexts | WebSocket, WebRTC, GraphQL, etc. |
| Problem | Solution |
|---|---|
ModuleNotFoundError: No module named 'brs_kb' |
Run pip install -e . from project root |
| SQLite database not created | Run brs-kb migrate or check write permissions to brs_kb/data/ |
| API server port already in use | Use --port flag: brs-kb serve --port 9000 |
| Web UI cannot connect to API | Verify API server is running, check CORS and REACT_APP_API_URL |
| Tests failing on import | Ensure you're using Python 3.8+ |
# Force database recreation
brs-kb migrate --force
# Check database location
python3 -c "from brs_kb.payloads_db import get_database_info; print(get_database_info())"
# Verify database integrity
brs-kb validate# Check if port is available
lsof -i :8080
# Start with verbose logging
brs-kb serve --port 8080 2>&1 | tee server.log
# Test API health
curl http://localhost:8080/api/health# Clear npm cache and reinstall
cd web_ui
rm -rf node_modules package-lock.json
npm install
# Check API connection
curl http://localhost:8080/api/infoMIT License - Free to use in any project (commercial or non-commercial)
Copyright (c) 2025 EasyProTech LLC / Brabus
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
See LICENSE for full text.
| Project | BRS-KB (BRS XSS Knowledge Base) |
| Company | EasyProTech LLC |
| Website | www.easypro.tech |
| Developer | Brabus |
| Contact | https://t.me/easyprotech |
| Repository | https://github.com/EPTLLC/BRS-KB |
| License | MIT |
| Status | Production-Ready |
| Version | 3.0.0 |
- BRS-XSS - Advanced XSS Scanner (uses BRS-KB)
NO OFFICIAL SUPPORT PROVIDED
This is a community-driven project. While we welcome contributions:
- Use GitHub Issues for bug reports
- Use Pull Requests for contributions
- No SLA or guaranteed response time
This project is maintained by the community.
- Security researchers who contribute knowledge
- Open-source community for support
- Everyone who reports issues and improvements
Open Source XSS Knowledge Base
MIT License • Python 3.8+ • Zero Dependencies