OSFF Vulnerability Platform

Open-Source Firmware Foundation vulnerability reporting platform for EuCRA compliance.

Features

• ✅ Web-based vulnerability submission (OSV format)
• ✅ Project authentication and management
• ✅ Embargo support (time-based or until-fixed)
• ✅ Email subscription system with project filters
• ✅ CRA compliance timeline tracking
• ✅ RESTful API with automatic documentation
• ✅ Docker-based deployment
• 🚧 Git integration for OSV.dev (future)

Quick Start

Prerequisites

• Docker and Docker Compose
• Git
• Task (optional but recommended)

Installation

1. Clone the repository:

git clone <repository-url>
cd vulnerability-handling

2. Setup and start the platform:

task start

This will:

• Create data directories
• Create .env file from example
• Build and start Docker containers
• Run database migrations
• Check service health

3. Edit .env and configure:

   • SECRET_KEY: Generate with openssl rand -hex 32
   • SMTP settings for email notifications

4. The API will be available at:

   • API: http://localhost:8000
   • API Docs: http://localhost:8000/docs
   • Health Check: http://localhost:8000/health

Available Commands

View all available tasks:

task --list

Common commands:

• task start - Start the platform
• task stop - Stop the platform
• task logs - View backend logs
• task health - Check service health
• task onboard - Onboard a new project (interactive)
• task onboard:example - Quick onboard U-Boot example
• task shell - Open backend shell
• task clean - Remove all containers and data

Database Migrations

Migrations run automatically on startup. To manually run migrations:

task migrate

To create a new migration:

task migrate:create

Project Onboarding

To add a new firmware project to the platform:

Interactive mode:

task onboard

Quick example (U-Boot):

task onboard:example

This will:

1. Create the project in the database
2. Create an admin user account
3. Display login credentials

API Usage

Authentication

1. Login to get an access token:

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "uboot-admin", "password": "secure-password"}'

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer"
}

2. Use the token for authenticated requests:

curl -X GET http://localhost:8000/vulnerabilities/my/vulnerabilities \
  -H "Authorization: Bearer <your-token>"

Submit a Vulnerability

curl -X POST http://localhost:8000/vulnerabilities/ \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "osv_id": "OSFF-UBOOT-2024-0001",
    "severity": "critical",
    "embargo_until_fixed": true,
    "osv_json": {
      "id": "OSFF-UBOOT-2024-0001",
      "summary": "Buffer overflow in network stack",
      "details": "A buffer overflow...",
      "affected": [
        {
          "package": {"name": "u-boot"},
          "ranges": [{"type": "SEMVER", "events": [{"introduced": "2024.01"}, {"fixed": "2024.04"}]}]
        }
      ]
    }
  }'

List Public Vulnerabilities

curl http://localhost:8000/vulnerabilities/

Filter by project:

curl "http://localhost:8000/vulnerabilities/?project_id=<project-uuid>"

Subscribe to Notifications

curl -X POST http://localhost:8000/subscriptions/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "filters": [
      {
        "project_id": "<project-uuid>",
        "min_severity": "high"
      }
    ]
  }'

CRA Compliance Tracking

Get compliance status for your project's vulnerabilities:

curl http://localhost:8000/vulnerabilities/my/compliance \
  -H "Authorization: Bearer <your-token>"

Response shows:

• Mitigation deadline (72 hours)
• Patch deadline (14 days)
• Time remaining for each deadline
• Compliance status

Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│   Projects  │────▶│   FastAPI   │────▶│  PostgreSQL  │
│ (Web/API)   │     │   Backend   │     │   Database   │
└─────────────┘     └─────────────┘     └──────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    Email    │
                    │ Subscribers │
                    └─────────────┘

Database Models

• projects: Firmware projects
• project_users: Project authentication
• vulnerabilities: Vulnerability records (OSV format)
• subscriptions: Email subscriptions
• subscription_filters: Filter criteria
• notifications_log: Notification audit trail
• cra_compliance_events: CRA compliance events

OSV Format

The platform uses the Open Source Vulnerability (OSV) format.

Example OSV JSON:

{
  "id": "OSFF-PROJECT-2024-0001",
  "summary": "Brief description",
  "details": "Detailed description",
  "affected": [
    {
      "package": {"name": "project-name"},
      "ranges": [
        {
          "type": "SEMVER",
          "events": [
            {"introduced": "1.0.0"},
            {"fixed": "1.2.0"}
          ]
        }
      ]
    }
  ],
  "severity": [
    {
      "type": "CVSS_V3",
      "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
    }
  ],
  "references": [
    {"type": "WEB", "url": "https://example.com/advisory"}
  ]
}

Development

Project Structure

vulnerability-handling/
├── backend/
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── models/        # Database models
│   │   ├── schemas/       # Pydantic schemas
│   │   ├── services/      # Business logic
│   │   ├── utils/         # Utilities
│   │   ├── config.py      # Configuration
│   │   ├── database.py    # Database setup
│   │   └── main.py        # FastAPI app
│   ├── alembic/           # Database migrations
│   ├── requirements.txt
│   └── Dockerfile
├── docker-compose.yml
└── README.md

Running Tests

Run all tests:

task test

Run tests with coverage report:

task test:coverage

Run specific test suites:

task test:unit      # Auth and compliance tests
task test:api       # API endpoint tests

Run tests in CI mode (standalone):

task test:ci

Viewing Logs

task logs        # Backend logs
task logs:db     # Database logs

Configuration

Environment variables (.env file):

Variable	Description	Default
SECRET_KEY	JWT secret key	(required)
DEBUG	Enable debug mode	false
SMTP_HOST	SMTP server hostname	smtp.example.com
SMTP_PORT	SMTP server port	587
SMTP_USER	SMTP username	(required)
SMTP_PASSWORD	SMTP password	(required)
SMTP_FROM_EMAIL	From email address	noreply@osff.org
FRONTEND_URL	Frontend URL for links	http://localhost:3000

CRA Compliance

The platform tracks EU Cyber Resilience Act (CRA) compliance timelines:

• 24 hours: Critical vulnerabilities reported (automatic on submission)
• 72 hours: Mitigation/workaround must be provided
• 14 days: Patch or remediation timeline must be provided

Projects see real-time compliance status in their dashboard and receive email reminders.

Future Enhancements

• Git integration for OSV.dev sync
• Automated OSV.dev data source setup
• Frontend web application
• CVE ID integration
• Coordinated disclosure workflow
• Webhook notifications
• Public API with rate limiting
• Two-factor authentication

License

[Add license information]

Support

For issues and questions - open an issue on GitHub.

Contact

For more information, contact christian.walter@osfw.foundation.