sentry-proxy

🛡️ SentryProxy

🇧🇷 Leia em Português

Web security analysis tool with MITM proxy, passive vulnerability detection, active scanners, autonomous security agent, AI-powered analysis, and a real-time dashboard.

SentryProxy intercepts, decrypts, and analyzes all HTTP/HTTPS traffic between the browser and the target site — combining automated vulnerability detection with an AI copilot and an autonomous browser-based security agent.

✨ Features

Feature	Description
🔓 HTTPS MITM Proxy	Full TLS interception with auto-generated CA certificates and LRU cert cache
🔍 5 Passive Analyzers	Data leak, headers, cookies, CORS, tech stack — real-time traffic analysis
⚡ 4 Active Scanners	XSS, Auth, IDOR, Info Disclosure — on-demand vulnerability testing
🤖 AI Real-time Copilot	LLM-powered traffic analysis with configurable prompts
📝 AI Report Analyst	5-phase deep analysis: correlations, attack chains, executive summary
🕵️ Autonomous Agent	Browser-driven security agent with 5 attack playbooks and safety guards
📱 Viewport Recon	Tests the site with 6 user-agents (Desktop, Mobile, iOS, WebView, etc.)
📜 Asset Scanner	JS/CSS crawl for secrets (API keys, tokens, connection strings)
🔎 Tech Fingerprinting	Detects 30+ technologies (frameworks, CMS, servers, CDNs, analytics)
📊 Real-time Dashboard	Web UI with WebSocket, filters, detail modals, toast notifications
💾 SQLite Persistence	Persistent storage for findings and traffic (survives restarts)
🖥️ CLI Mode	Headless scanning via --scan, --target, --headless flags
🔒 Rate Limiting	Built-in API rate limiting (100 req/min) with X-RateLimit headers
🐳 Docker Ready	Production Dockerfile included

📋 Table of Contents

• Quick Start
• Installation
• Configuration
• How to Use
• Architecture
• Modules
• Agent Mode
• AI Engine
• CLI Mode
• Dashboard
• HTTPS Setup
• API Reference
• Testing
• Documentation
• Contributing

🚀 Quick Start

# Clone
git clone https://github.com/diegosouzapw/sentry-proxy.git
cd sentry-proxy

# Install
npm install

# Configure
cp .env.example .env
# Edit .env → set TARGET_URL=https://your-target.com

# Run
npm start

The dashboard opens at http://localhost:3333 and the proxy listens on localhost:8888.

📦 Installation

Prerequisites: Node.js 20+ and npm.

npm install

Docker

docker build -t sentry-proxy .
docker run -p 3333:3333 -p 8888:8888 -e TARGET_URL=https://example.com sentry-proxy

⚙️ Configuration

Copy .env.example and adjust:

# Required
TARGET_URL=https://your-web-site.com

# Proxy
PROXY_PORT=8888
DASHBOARD_PORT=3333
MODE=passive              # passive (analyze only) | active (allows scanners)
LOG_LEVEL=info             # debug | info | warn | error

# Dashboard Auth
DASHBOARD_AUTH_USER=admin
DASHBOARD_AUTH_PASSWORD=your-strong-password

# AI (optional)
AI_ENABLED=true
AI_PROVIDER=openai-compatible
AI_BASE_URL=http://localhost:20128/v1
AI_API_KEY=your-api-key
AI_MODEL=gpt-4
AI_MODE=both               # realtime | report | both
AI_MAX_TOKENS=4096
AI_TEMPERATURE=0.3

# Storage
DATA_DIR=data              # SQLite database directory

🎯 How to Use

1. Passive Mode (default)

Simply browse the target with the proxy configured — SentryProxy analyzes all traffic automatically:

• Start SentryProxy: npm start
• Configure your browser proxy to http://localhost:8888
• Install the CA certificate (see HTTPS Setup)
• Navigate to the target site
• View real-time findings at http://localhost:3333

2. Active Scanning

Set MODE=active in .env, then trigger scanners from the dashboard or API:

# Via API
curl -X POST http://localhost:3333/api/scan/xss
curl -X POST http://localhost:3333/api/scan/auth
curl -X POST http://localhost:3333/api/scan/idor
curl -X POST http://localhost:3333/api/scan/info-disclosure

3. Agent Mode

The autonomous agent uses a real browser (Playwright) to explore and test the target:

# Start agent from dashboard or API
curl -X POST http://localhost:3333/api/agent/start \
  -H "Content-Type: application/json" \
  -d '{"playbook": "reconnaissance"}'

Available playbooks: reconnaissance, auth-testing, input-injection, sensitive-data, access-control.

4. CLI / Headless Mode

# Run specific scanners and exit
npx tsx src/index.ts --target https://example.com --scan xss,idor --output report.json

# Headless mode (no dashboard)
npx tsx src/index.ts --headless --scan info-disclosure

🏗️ Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Browser    │────▶│  MITM Proxy  │────▶│   Target Site   │
│              │◀────│  (port 8888) │◀────│                 │
└─────────────┘     └──────┬───────┘     └─────────────────┘
                           │
                    ┌──────▼───────┐
                    │  Analyzers   │  ← passive, real-time
                    │  (5 modules) │
                    └──────┬───────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐     ┌──────▼──────┐   ┌──────▼──────┐
    │ Finding │     │  Dashboard  │   │  AI Copilot │
    │  Store  │     │ (port 3333) │   │  (LLM API)  │
    └────┬────┘     └──────┬──────┘   └─────────────┘
         │                 │
    ┌────▼────┐     ┌──────▼──────┐
    │ SQLite  │     │  WebSocket  │
    │   DB    │     │  (live UI)  │
    └─────────┘     └─────────────┘

Source Modules

Module	Files	Purpose
proxy/	server, cert-manager, container	MITM proxy, TLS certificates, DI
analyzers/	cors, headers, data-leak, tech-stack, cookies	Passive traffic analysis
scanners/	xss, auth, idor, info-disclosure	Active vulnerability scanning
agent/	controller, browser-driver, playbooks, safety-guard, navigation-graph, page-analyzer, action-planner	Autonomous browser agent
ai/	llm-provider, realtime-copilot, report-analyst, prompt-library, ai-config	AI-powered analysis
recon/	auto-recon, viewport-recon, asset-recon	Automated reconnaissance
dashboard/	server, websocket, routes/core, routes/ai, routes/agent	Web UI and API
storage/	finding-store, request-store, database	In-memory and SQLite storage
middleware/	rate-limit	API rate limiting
utils/	cli, logger, lru-cache, headers	Shared utilities

🕵️ Autonomous Agent

The agent is a browser-driven security testing system powered by Playwright and LLM decision-making.

Playbooks

Playbook	Risk	Steps	Purpose
reconnaissance	Low	50	Map pages, forms, APIs, admin areas
auth-testing	Medium	30	Test login, enumeration, rate limiting
input-injection	High	40	XSS and SQLi on all input fields
sensitive-data	Low	25	Hunt for exposed PII, keys, tokens
access-control	Medium	25	IDOR and privilege escalation testing

Safety Guard

• All destructive actions require human approval
• Risk level classification per action
• Automatic abort on safety violations
• Maximum step budget per playbook

Agent API

# Control
POST /api/agent/start    # Start with playbook
POST /api/agent/stop     # Stop execution
POST /api/agent/pause    # Pause execution
POST /api/agent/resume   # Resume execution
POST /api/agent/approve  # Approve pending action

# Status
GET  /api/agent/status   # Current state
GET  /api/agent/map      # Navigation graph (Mermaid)
GET  /api/agent/playbooks # Available playbooks

🤖 AI Engine

Real-time Copilot

Analyzes intercepted traffic in real-time using configurable LLM prompts:

• HTTP Traffic Analysis — detects security issues in request/response pairs
• JavaScript Analysis — finds client-side vulnerabilities
• Auth Flow Analysis — evaluates authentication security
• API Response Analysis — checks for data exposure
• Tech Stack Analysis — contextual vulnerability mapping

Report Analyst

5-phase deep analysis of all accumulated findings:

• Finding Correlation — groups related vulnerabilities
• Attack Chain Analysis — identifies exploitation paths
• Risk Assessment — business impact evaluation
• Executive Summary — non-technical overview
• Remediation Plan — prioritized fix recommendations

AI API

GET  /api/ai/status         # AI status and token usage
POST /api/ai/analyze-report # Generate deep analysis
GET  /api/ai/reports        # List generated reports

🖥️ CLI Mode

Usage:
  npx tsx src/index.ts [options]

Options:
  -t, --target <url>       Target URL (overrides TARGET_URL)
  -m, --mode <mode>        passive | active
  -s, --scan <scanners>    Run scanners and exit (comma-separated)
  -o, --output <file>      Output file for results (JSON)
  --headless               No interactive dashboard
  -h, --help               Help

Examples:
  npx tsx src/index.ts --target https://example.com
  npx tsx src/index.ts --scan xss,idor --output report.json
  npx tsx src/index.ts --headless --scan info-disclosure

📊 Dashboard

The web dashboard provides:

• Real-time findings via WebSocket with severity badges
• Traffic monitor with request/response details
• Statistics with security score (A–F grade)
• Scanner controls for active scanning
• Agent controls with status and navigation graph
• AI insights with copilot status and report generation
• Export full JSON security report
• Toast notifications for new findings
• Responsive design (desktop, tablet, mobile)
• Rate limiting with X-RateLimit-* headers

🔐 HTTPS Interception

SentryProxy generates a local CA certificate at startup. To intercept HTTPS:

• Start SentryProxy once (generates certs/rootCA.pem)
• Import the CA into your browser/system
• All HTTPS traffic will be transparently decrypted

See HTTPS Setup Guide for detailed instructions.

📡 API Reference

Endpoint	Method	Description
/api/stats	GET	Dashboard statistics and security score
/api/findings	GET	Paginated findings (?page=1&limit=50&severity=HIGH)
/api/traffic	GET	Paginated traffic (?page=1&limit=50)
/api/export	GET	Full JSON security report
/api/scan/:type	POST	Trigger scanner (xss, auth, idor, info-disclosure)
/api/reset	POST	Clear all findings and traffic
/api/ai/status	GET	AI copilot status and token usage
/api/ai/analyze-report	POST	Generate AI deep analysis
/api/ai/reports	GET	List AI-generated reports
/api/agent/start	POST	Start agent with playbook
/api/agent/stop	POST	Stop agent
/api/agent/status	GET	Agent state
/api/agent/map	GET	Navigation graph (Mermaid)
/api/agent/playbooks	GET	Available playbooks

All API endpoints include rate limiting headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

🧪 Testing

# Unit tests (114 tests)
npm test

# With coverage
npm run test:coverage

# E2E tests (12 Playwright tests)
npm run test:e2e

# Lint
npm run lint

Test coverage:

Area	Files	Tests
Analyzers	5	56
Scanners	4	21
Storage	2	22
Utils	1	9
E2E	1	12
Total	13	126

📚 Documentation

Document	Description
User Guide (EN)	Complete step-by-step guide for beginners
User Guide (PT-BR)	Guia completo passo a passo
Architecture	System architecture and design
API Reference	Full API documentation
Analyzers	Passive analyzer details
Scanners	Active scanner details
Detection Patterns	Vulnerability detection rules
HTTPS Setup	CA certificate installation
CHANGELOG	Version history
SECURITY	Security policy

🤝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature/my-feature
• Make your changes with tests
• Run npm test && npm run lint
• Submit a Pull Request

📄 License

MIT © 2025-2026

🛡️ SentryProxy v1.0.0
Security Analysis & Vulnerability Detection Tool