Full-featured REST API for OWASP BLT running on Cloudflare Workers

Features • Quick Start • API Endpoints • Development • Deployment

BLT-API is a high-performance, edge-deployed REST API that interfaces with all aspects of the OWASP BLT (Bug Logging Tool) project. Built using Python on Cloudflare Workers, it provides efficient, globally-distributed access to BLT's bug bounty platform.

• 🚀 Edge-deployed - Runs on Cloudflare's global network for low latency
• 🐍 Python-powered - Built with Python for Cloudflare Workers
• �️ D1 Database - Uses Cloudflare D1 (SQLite) for data persistence
• �🔒 Secure - CORS enabled, authentication support
• 📊 Full API Coverage - Access to issues, users, domains, organizations, projects, hunts, and more
• 📖 Well-documented - Comprehensive API documentation
• ⚡ Fast - Optimized for quick cold starts and efficient execution

• Python 3.12+
• Node.js 18+
• uv (Python package manager)
• Wrangler (Cloudflare Workers CLI)

# Clone the repository
git clone https://github.com/OWASP-BLT/BLT-API.git
cd BLT-API

# Install dependencies
uv sync

# Install workers-py
uv tool install workers-py

# Setup local database
wrangler d1 migrations apply blt-api --local
wrangler d1 execute blt-api --local --file=test_data.sql

# Start the development server
wrangler dev --port 8787

# The API will be available at http://localhost:8787

For detailed setup instructions, see CONTRIBUTING.md.

# Install test dependencies
uv sync --extra dev

# Run tests
uv run pytest

Query Parameters for /issues:

• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)
• status - Filter by status (open, closed)
• domain - Filter by domain URL

Domain endpoints use Cloudflare D1 database. See docs/DATABASE.md for details.

Query Parameters for /leaderboard/monthly:

• month - Month number (1-12)
• year - Year (e.g., 2024)

All API responses follow a consistent JSON format:

{
  "success": true,
  "data": { ... },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "count": 10,
    "total": 100
  }
}

{
  "error": true,
  "message": "Error description",
  "status": 400
}

This project uses Cloudflare D1 (SQLite) for data persistence. Some endpoints query the D1 database directly, while others proxy to the BLT backend API.

• /domains - Domain data stored in D1
• /domains/{id}/tags - Domain tags from D1

# Apply migrations locally
wrangler d1 migrations apply blt-api --local

# Load test data
wrangler d1 execute blt-api --local --file=test_data.sql

# Create new migration
wrangler d1 migrations create blt-api <description>

# Apply to production
wrangler d1 migrations apply blt-api --remote

For complete database guide including queries, schema, and patterns, see docs/DATABASE.md.

BLT-API/
├── src/
│   ├── __init__.py         # Package initialization
│   ├── main.py             # Worker entry point
│   ├── router.py           # URL routing
│   ├── utils.py            # Utility functions
│   ├── client.py           # BLT backend HTTP client
│   ├── libs/               # Library modules
│   │   └── db.py           # Database helpers
│   └── handlers/           # Request handlers
│       ├── __init__.py
│       ├── issues.py
│       ├── users.py
│       ├── domains.py      # D1-integrated
│       ├── organizations.py
│       ├── projects.py
│       ├── hunts.py
│       ├── stats.py
│       ├── leaderboard.py
│       ├── contributors.py
│       ├── repos.py
│       └── health.py
├── migrations/             # D1 database migrations
│   └── 0001_init.sql
├── docs/                   # Documentation
│   └── DATABASE.md         # D1 database guide
├── tests/                  # Test files
├── test_data.sql           # Sample data for development
├── wrangler.toml           # Cloudflare Workers config
├── pyproject.toml          # Python project config
├── CONTRIBUTING.md         # Contribution guide
└── README.md

1. Create a new handler in src/handlers/
2. Import and export it in src/handlers/__init__.py
3. Register the route in src/main.py

Configure these in wrangler.toml:

# Login to Cloudflare
wrangler login

# Apply database migrations to production
wrangler d1 migrations apply blt-api --remote

# Deploy to production
wrangler deploy

# Deploy to development
wrangler deploy --env development

# Deploy to production
wrangler deploy --env production

Some endpoints require authentication. Pass the auth token in the request header:

curl -H "Authorization: Token YOUR_API_TOKEN" https://your-worker.workers.dev/issues

The API follows Cloudflare Workers' execution limits:

• CPU time: 50ms (free), 30s (paid)
• Memory: 128MB
• Request size: 100MB

We welcome contributions! Please see CONTRIBUTING.md for detailed setup instructions and development guidelines.

Quick start:

1. Fork the repository
2. Setup local environment (see CONTRIBUTING.md)
3. Create a feature branch
4. Make your changes
5. Test locally with wrangler dev
6. Submit a pull request

For database changes, see docs/DATABASE.md.

• OWASP BLT - Main BLT project
• BLT Website - Live BLT platform

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

• 💬 OWASP Slack - Join #project-blt
• 🐛 GitHub Issues - Report bugs
• 📖 BLT Documentation

Made with ❤️ by the OWASP BLT Community