🛡️ 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:

1. Start SentryProxy: npm start
2. Configure your browser proxy to http://localhost:8888
3. Install the CA certificate (see HTTPS Setup)
4. Navigate to the target site
5. 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:

1. Finding Correlation — groups related vulnerabilities
2. Attack Chain Analysis — identifies exploitation paths
3. Risk Assessment — business impact evaluation
4. Executive Summary — non-technical overview
5. 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:

1. Start SentryProxy once (generates certs/rootCA.pem)
2. Import the CA into your browser/system
3. 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

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

📄 License

MIT © 2025-2026