BBpanel

Self-hosted bug bounty management and continuous asset monitoring platform.

Integrates reconnaissance automation with program change tracking across HackerOne, Bugcrowd, Intigriti, and YesWeHack.

---

Quickstart (Production)

Prerequisites

• Docker & Docker Compose
• Git

Setup

git clone <repo-url> bbpanel
cd bbpanel

# 1. Create environment file from sample
cp .env.sample .env
# Edit .env — set your domain, passwords, and API tokens

# 2. Create BugHound environment (minimal, credentials stored in Django DB)
cat > BugHound/config/.env << 'EOF'
LOG_LEVEL=DEBUG
WATCH_BUGCROWD=True
EOF

# 3. Start all services
docker compose up -d --build

# 4. Create admin user
docker compose exec backend python django_app/manage.py createsuperuser

# 5. Log in at https://<your-domain>/

The app runs at http://localhost (or your configured domain). Default setup uses port 80.

Post-Setup Configuration

All application settings are managed through the web UI — no .env edits needed after initial setup:

Setting	Where	Purpose
BugHound credentials	/bughound/ → Settings modal	H1/Intigriti API tokens, watch flags, fetch interval
Discord webhooks	/bughound/ → Settings modal	BugHound program change notifications
Discord webhooks	/cp/settings/ → Settings modal	Scan result notifications (nuclei findings, new live subs)
GitHub/Chaos tokens	/cp/settings/ → Settings modal	Passive subdomain enumeration sources
Max concurrent jobs	/cp/settings/ → Settings modal	Scan job concurrency limit

---

Architecture

┌─────────────────────────────────────────────────┐
│  nginx :80/443                                   │
│  Reverse proxy, static files, SSL termination     │
└──────────────┬──────────────────────────────────┘
               │
┌──────────────▼──────────────────────────────────┐
│  backend       Django + Gunicorn (port 8000)     │
│                Web UI, auth, job orchestration    │
│                BugHound: program change monitor   │
└───┬───────────┬──────────────┬──────────────────┘
    │           │              │
┌───▼───┐ ┌─────▼─────┐ ┌─────▼──────┐
│PostgreSQL│ │  Redis    │ │  MongoDB   │
│  :5432  │ │  :6379    │ │  :27017    │
│ Users,  │ │ Celery    │ │ Assets,    │
│ Jobs,   │ │ broker +  │ │ Programs,  │
│ Reports │ │ results   │ │ BugHound   │
└─────────┘ └─────┬─────┘ └────────────┘
                  │
┌─────────────────▼──────────────────────────────┐
│  bbpanel-celery   Worker + Beat scheduler       │
│                   Runs bbpanel_watch scripts     │
│                   BugHound periodic fetch tasks  │
└─────────────────────────────────────────────────┘

Docker Services

Service	Port	Purpose
db	5432	PostgreSQL 17 — Django primary DB
backend	8000	Django + Gunicorn
nginx-reverse_proxy	80, 443	Reverse proxy, static assets
watch-mongo	27017	MongoDB — asset data, BugHound program data
bbpanel-tasks-redis	6379	Celery broker + result backend
bbpanel-celery	—	Celery worker + beat (3 queues: celery concurrency=2, bughound concurrency=1, watch_fresh concurrency=1)

Django Apps

App	URL	Purpose
dashboard	/	Dashboard home, BXSS inbox, webhook logs, program management
controlpanel	/cp/	Scan job lifecycle, job scheduling, global settings
bughound	/bughound/	BugHound — platform cards, program listing, fetch control, change tracking
authentication	/auth/	Login/logout
bxss	bx.<domain>	Blind XSS capture payload + victim report receiver
webhook	*.hook.<domain>	Blind HTTP request capture (OOB interaction)
filemanager	/filemanager/	Encrypted file upload/download/view
admin	/admin/	Django admin

Recon Engine (bbpanel_watch/)

The scanner runs as Celery tasks or cron jobs. Pipeline order:

1. Subdomain Enumeration — CRT.sh, Subfinder, Chaos, Wayback, GAU, GitHub, AbuseIPDB
2. DNS Resolution — Resolve subdomains (A/AAAA/CNAME) via dnsx
3. HTTP Probing — HTTP/HTTPS service detection via httpx, change detection
4. Nuclei Scanning — Vulnerability scanning on discovered HTTP services

Results stored in MongoDB (bbpanel-watch database), displayed in the dashboard.

Watch Fresh (django_app/apps/controlpanel/tasks/watch_fresh.py)

Continuous freshness scanning for program subdomains. Configured per-program at /cp/watch-fresh/:

• Live jobs: DNS-resolve all known subdomains via dnsx -a, detect new live hosts
• HTTP jobs: Probe live hosts via httpx_go -json -tech-detect, detect changes in status code, title, technologies, response hash, IPs
• Scheduled via Celery Beat (every 15 min tick), runs on dedicated watch_fresh queue with concurrency=1
• Discord notifications sent on new/changed assets

BugHound (BugHound/)

Monitors program changes across 4 bug bounty platforms. Detected changes include:

• New programs launched
• State changes (open → paused, etc.)
• Type changes (VDP ↔ RDP)
• New assets added to scope
• Asset changes (eligibility, severity, etc.)

Notifies via Discord and/or Telegram. All changes also stored in the dashboard at /bughound/changes/.

---

Project Structure

bbpanel/
├── docker-compose.yaml          # Service orchestration
├── Dockerfile.django            # Backend image
├── Dockerfile.celery            # Worker + beat image
├── django_entrypoint.sh         # Backend startup script
├── worker_entrypoint.sh         # Worker startup script
├── nginx/nginx.conf             # Reverse proxy config
├── .env.sample                  # Environment template
│
├── django_app/                  # Django web application
│   ├── core/                    # Settings, URLs, WSGI, ASGI, host routing
│   ├── worker/                  # Celery app init
│   └── apps/
│       ├── dashboard/           # Main UI views + templates
│       ├── controlpanel/        # Scan jobs, Celery tasks, settings, Watch Fresh
│       │   ├── tasks/watch_fresh.py   # Watch Fresh run + tick tasks
│       │   ├── views/watch_fresh.py   # Watch Fresh config/detail views
│       │   └── models/watch_fresh_*.py # WatchFreshConfig, WatchFreshLog
│       ├── bughound/            # BugHound Django integration
│       ├── authentication/      # User login/logout
│       ├── bxss/                # Blind XSS capture
│       ├── webhook/             # OOB HTTP request capture
│       ├── filemanager/         # File management
│       ├── dynamic/             # Dummy image server
│       └── utils/               # Shared utilities, Discord notifications
│
├── bbpanel_watch/               # Reconnaissance engine
│   ├── enum/                    # Subdomain enumeration scripts
│   ├── ns/                      # DNS resolution scripts
│   ├── http/                    # HTTP probing + change detection
│   ├── nuclei/                  # Vulnerability scanning
│   ├── database/                # MongoDB models/selectors/services
│   ├── tools/                   # Python wrappers for Go/C binaries
│   ├── utils/                   # Shell utils, scope check, Discord
│   ├── api/                     # FastAPI REST endpoints
│   └── bin/                     # Pre-built binaries (dnsx, subfinder, nuclei, ...)
│
└── BugHound/                    # Bug bounty program monitor
    ├── config/                  # Environment config, API base class
    ├── fetch_programs/api/      # Platform API clients (H1, BC, II, YWH)
    ├── database/                # MongoEngine models + upsert/diff services
    └── utils/                   # Telegram, Discord, DeepDiff, timestamps

---

Environment Variables

The .env file at project root contains infrastructure-level configuration.

Variable	Purpose
POSTGRES_DB/USER/PASSWORD	PostgreSQL credentials for Django
DJANGO_SECRET_KEY	Django secret key
DEBUG	Set to FALSE in production
DOMAIN	Your domain (e.g., bbpanel.example.com)
DJANGO_ALLOWED_HOSTS	Comma-separated allowed hosts
DJANGO_CSRF_TRUSTED_ORIGINS	Comma-separated trusted origins
CRYPTO_KEY	Fernet key for file encryption
DB_NAME/HOST/USER/PASSWORD	MongoDB credentials
WATCH_DIR	Path to bbpanel_watch inside container
CELERY_BROKER_URL	Redis URL for Celery broker
CELERY_RESULT_BACKEND	Redis URL for Celery results

Application-level settings (BugHound tokens, webhook URLs, scan config, including the ProjectDiscovery Chaos API token) are managed exclusively through the web UI (/cp/ → Platform Settings) and stored in PostgreSQL via the GlobalSetting model. No .env edits needed.

---

Common Operations

Trigger a BugHound fetch

POST /bughound/fetch/

Or click "Fetch Programs Now" in the BugHound dashboard. Fetches program data from all enabled platforms.

Schedule a scan

Navigate to /cp/ → select a program → "New Scan". Configure:

• Subdomain enumeration sources
• DNS resolution options
• HTTP probing settings
• Nuclei scanning templates

View program changes

Navigate to /bughound/changes/ or click "Recent Changes" on the dashboard. Shows all detected program changes across platforms.

Stop a running job

Go to /bughound/logs/ → click the stop button on a running fetch. The job status changes to "stopped" and the background thread/task is signaled to stop.

Check webhook hits

Go to /dashboard/logs/ to view captured OOB HTTP requests from *.hook.<domain>.

---

Development Notes

• No .env dependency for app settings: All application config uses GlobalSetting (PostgreSQL). The .env file is only for infrastructure-level variables.
• Don't remove DB containers with -v: Use docker compose down (without -v) to preserve data.
• Shared MongoDB: watch-mongo is used by both bbpanel_watch (asset data) and BugHound (program data), database bbpanel-watch.
• Two Discord webhook systems: scan_discord_webhook_url for scan findings, bughound_discord_webhook_url for program change notifications.
• Job concurrency: Controlled via max_active_jobs in global settings. BugHound fetches and scan jobs share this limit.
• Scan order: subdomain > lives > http (reverse-alphabetical priority).
• Watch Fresh queue: Dedicated watch_fresh queue with concurrency=1. Runs independently of on-demand scan jobs.
• httpx vs httpx_go: The container has a Python httpx stub (161B) that shadows the Go httpx_go binary (51MB). Always use httpx_go.
• Celery code reload: pool_restart is not enabled. After editing task code, copy with docker cp and kill+restart the relevant worker PID.
• See PROJECT-OVERVIEW.md for detailed architectural documentation.