BoundedScan

A self-hosted, open-source web attack surface management platform for small security teams.

Español · Security policy · Contributing · Roadmap

Release status: v0.1.0 portfolio release. BoundedScan is functional and reproducible, but it has not undergone an independent security audit and is not presented as an enterprise-ready security product.

BoundedScan brings authorized scopes, persistent asset inventory, bounded non-destructive campaigns, deduplicated findings, CVE intelligence and evidence-based reporting into one operational console. It is designed to demonstrate defensive security engineering while keeping authorization and safety controls visible throughout the workflow.

Only scan systems you own or have explicit permission to test.

Product tour

Campaign execution	Finding investigation

Evidence-based reporting	Authorized validation controls

The screenshots are generated from the deterministic local lab and can be reproduced with the opt-in Playwright capture test:

cd apps/dashboard
$env:BOUNDEDSCAN_CAPTURE_SCREENSHOTS = "1"
pnpm run test:e2e

What is implemented

• Approved scopes and exact-origin enforcement before and between campaign stages.
• PostgreSQL persistence with Alembic migrations; isolated SQLite support for tests and local development.
• Local users with admin, operator and reviewer roles, Argon2id password hashing, opaque revocable sessions and CSRF protection.
• Celery/RabbitMQ execution, Redis coordination, cancellation, scheduling, rate limits and request budgets.
• A bounded pipeline covering discovery, probing, same-origin crawl, approved Nuclei templates, normalization, intelligence and reporting.
• Generic reflected-HTML canaries, passive CSRF form review and optional two-identity object-authorization comparison without identifier enumeration.
• Pinned Subfinder, Httpx, Katana and Nuclei adapters, with transparent non-destructive Python fallbacks when a tool is unavailable.
• Finding deduplication, occurrence history, workflow states, comments and two-clean-scan resolution.
• AES-GCM credential profiles restricted to one approved host, including explicit revocation.
• Optional NVD/CVSS, FIRST EPSS and CISA KEV enrichment and evidence-only local Ollama explanations.
• HTML, PDF and JSON reports plus CSV finding export.
• Audit events, correlation IDs, Prometheus metrics, liveness and readiness endpoints.

Reproducible demo

Requirements: Docker Desktop or Docker Engine with Docker Compose v2.

docker compose --env-file .env.example -f docker-compose.yml -f compose.demo.yml up --build

Open http://localhost:5173 and sign in with:

Email:    demo@boundedscan.local
Password: boundedscan-demo-2026!

Select Prepare demo, open the guided campaign and run it. The lab uses only the isolated demo-web fixture and OWASP Juice Shop containers; intelligence is served from offline fixtures. The deterministic fixture includes documented XSS, CSRF and IDOR scenarios, while automated detection remains restricted to non-state-changing checks. See the vulnerable local lab guide.

Service	Local URL
Dashboard	http://localhost:5173
API / OpenAPI	http://localhost:8000/docs
Deterministic fixture	http://localhost:8089
OWASP Juice Shop	http://localhost:3000
RabbitMQ management	http://localhost:15672

Stop the demo without deleting its volumes:

docker compose --env-file .env.example -f docker-compose.yml -f compose.demo.yml down

Architecture

flowchart LR
    UI["React dashboard"] --> API["FastAPI /api/v1"]
    API --> PG["PostgreSQL"]
    API --> MQ["RabbitMQ"]
    API --> REDIS["Redis"]
    MQ --> WORKER["Celery scanner worker"]
    REDIS --> WORKER
    WORKER --> TOOLS["Subfinder / Httpx / Katana / Nuclei"]
    WORKER --> PG
    SCHED["Scheduler"] --> MQ
    API --> REPORTS["HTML / PDF / JSON / CSV"]
    API -. "redacted evidence" .-> OLLAMA["Local Ollama"]

Loading

PostgreSQL is the source of truth. RabbitMQ transports tasks, while Redis provides coordination, progress, cancellation and rate control. The worker is attached to a separate internal scan network. Demo targets are reachable only through that network.

Normal installation

For a complete local installation, including Ollama:

.\scripts\bootstrap.ps1

It creates .env with unique secrets, starts the optional ai profile, and pulls llama3.2:3b into a persistent Docker volume. Model weights are never committed to Git. The local operations runbook covers alternative models and non-AI operation.

For a manual installation, copy the example and replace every example credential:

Copy-Item .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(48))"

Set unique PostgreSQL and RabbitMQ passwords, a strong bootstrap password and the generated BOUNDEDSCAN_MASTER_KEY. For HTTPS deployments set BOUNDEDSCAN_COOKIE_SECURE=true and configure the exact dashboard origin in BOUNDEDSCAN_ALLOWED_ORIGINS.

The API refuses to start in authenticated non-demo mode while example secrets remain.

docker compose --env-file .env up --build -d
docker compose ps

This is a single-organization installation. There is no public registration, multi-tenancy or managed cloud service.

Development and verification

cd apps/api
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-dev.txt
python -m ruff check app tests
python -m pytest --cov=app --cov-report=term-missing

cd apps/dashboard
pnpm install --frozen-lockfile
pnpm run build
pnpm exec playwright install chromium
pnpm run test:e2e

python scripts/check_utf8.py
docker compose --env-file .env.example config --quiet
docker compose --env-file .env.example --profile ai config --quiet
docker compose --env-file .env.example -f docker-compose.yml -f compose.demo.yml config --quiet

See the local operations runbook, generic web checks and initial threat model for more detail.

Safety boundaries and limitations

BoundedScan does not implement exploitation, reverse shells, credential attacks, authentication bypass, persistence, evasion, lateral movement, exfiltration or destructive payloads. Web requests are restricted to GET, HEAD and OPTIONS; the aggressive lab profile is always blocked in production.

The platform can still generate traffic and false positives. A detected technology or exposed route is evidence to review, not automatic proof of a vulnerability. Operators remain responsible for authorization, scope accuracy, rate limits and manual validation.

Kubernetes manifests are reference deployments for the API, worker and scheduler. They assume externally managed PostgreSQL, RabbitMQ and Redis services and require deployment-specific images and secrets.

License

Copyright 2026 Juan José Navarro Villegas. Licensed under the Apache License 2.0.