BurnBox Architecture & API Reference

Developer and analyst guide to the BurnBox secure web research workspace, SSRF perimeter controls, and REST APIs.

1. The 6-Stage Web Research Lifecycle

BurnBox standardizes web investigations into an auditable six-stage pipeline:

01. SEARCH

Discover and input target URLs, configure crawl depth (1–3), and set domain scoping constraints.

02. INVESTIGATE

Run pre-flight DNS SSRF validation and dispatch crawl tasks to decoupled Scrapy Cloud workers.

03. COLLECT

Harvest page body content, HTTP response codes, response headers, and outbound link graphs.

04. ANALYZE

Inspect evidence, export clean JSON datasets, or run exploratory analytics via Deepnote notebooks.

05. DOCUMENT

Attach structured notes, risk tags, and timeline markers to research findings in project workspaces.

06. SHARE

Collaborate securely across roles with tenant-scoped permissions and immutable audit logs.

2. SSRF Shield & Perimeter Verification

Before any crawl job is dispatched, the BurnBox control plane executes a multi-layer SSRF filter:

Pre-Flight DNS Resolution: Resolves target hostnames using Cloudflare Worker-compatible async DNS with secure DNS-over-HTTPS fallback.

Private CIDR Blocking: Blocks RFC1918 subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopbacks (127.0.0.0/8, ::1), and carrier-grade NAT (100.64.0.0/10).

Cloud Metadata Defense: Rejects addresses matching cloud instance metadata endpoints (169.254.169.254) on AWS, GCP, Azure, and DigitalOcean.

Recursive Redirect Inspection: Outbound HTTP redirects are screened against the SSRF policy at each hop before following.

3. REST API Endpoints

POST/api/investigations

Dispatch SSRF-shielded Scrapy Cloud web investigation.

GET/api/investigations

List web investigations for the authenticated tenant.

GET/api/investigations/:id

Retrieve investigation progress, metadata, and harvested evidence.

POST/api/projects

Create a new research project workspace.

GET/api/projects

List active research projects for current tenant organization.

GET/api/audit-logs

Query immutable tenant compliance and security audit events.

GET/api/analytics

Fetch operational telemetry, crawl metrics, and dataset exports.

POST/api/analytics

Trigger optional Deepnote remote analytics notebook execution.

POST/api/webhooks/pageclip

Ingest contact and security feedback inquiries securely.