🔥 ThreatForge

AI-powered cybersecurity tabletop exercise scenario generator that creates comprehensive, realistic scenarios for security training and incident response exercises.

✨ Features

🤖 Multi-AI Provider Support - Generate scenarios using OpenAI GPT or Anthropic Claude
🎯 Smart Scenario Generation - Create detailed, realistic cybersecurity scenarios
🔄 Reroll Capability - Regenerate specific sections of scenarios on-demand
💰 Cost Estimation - Compare costs across different AI providers before generation
🏢 Customizable Parameters - Company size, industry, threat actors, technologies
📊 Scenario History - Track and review previously generated scenarios
🎨 Modern UI - Responsive design with cyberpunk theme
⚡ Real-time Generation - Fast, async scenario creation
📱 Export Options - Download scenarios as text files
🔧 Production Ready - Docker support with nginx and gunicorn

🚀 Quick Start

Docker (Recommended)

# One-liner deployment
docker-compose -f docker-compose.prod.yml up -d

# Visit the application
open http://localhost

That's it! The application will be available at http://localhost with both frontend and backend running.

🛠️ Tech Stack

Backend

Framework: FastAPI with async support
Validation: Pydantic v2 for data validation
AI Integration: OpenAI API, Anthropic API
Server: Gunicorn with uvicorn workers
Testing: pytest, pytest-cov
Code Quality: Black, Ruff

Frontend

Framework: Vue 3 with Composition API
Build Tool: Vite for fast development
UI Components: PrimeVue 4
HTTP Client: Axios
Styling: CSS Variables with cyberpunk theme

Infrastructure

Containerization: Multi-stage Docker builds
Web Server: Nginx for static file serving and API proxy
Process Manager: Gunicorn for production WSGI serving

🔧 Development Setup

Prerequisites

Python 3.11+
Node.js 20+
Docker (optional, for containerized development)

Local Development

Clone the repository

git clone https://github.com/xFreed0m/threatforge.git
cd threatforge

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Frontend Setup
```
cd ../frontend
npm install
```

Environment Configuration

cp .env.example .env
# Edit .env and add your API keys

Run Development Servers

Backend (from backend/ directory):

source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend (from frontend/ directory):

npm run dev

Access the Application
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

Docker Development

# Development with hot-reloading
docker-compose -f docker-compose.dev.yml up

# Access at http://localhost:3000 (frontend) and http://localhost:8000 (backend)

🔒 Security

ThreatForge implements comprehensive security scanning to prevent secrets from being exposed:

Automated Security Scanning

TruffleHog: Scans for verified secrets in git history
GitLeaks: Comprehensive secret detection with custom patterns
Pre-commit hooks: Prevent secrets from being committed
Weekly scans: Automated security audits

Security Features

✅ Secret Detection: Automated scanning for API keys, tokens, and credentials
✅ False Positive Filtering: Excludes test data and examples
✅ Git History Scanning: Full repository history analysis
✅ Pre-commit Protection: Hooks prevent accidental secret commits
✅ SARIF Reports: Integration with GitHub Security tab

Running Security Scans Locally

# Quick setup (recommended)
./scripts/setup-security.sh

# Manual setup
pip install pre-commit
pre-commit install

# Run GitLeaks scan (no license required for personal repos)
gitleaks detect --config-path=.gitleaks.toml --verbose

# Run TruffleHog scan
trufflehog --only-verified --fail .

🧪 Testing

cd backend
pytest

Frontend Tests

cd frontend
npm run test

Code Quality

# Backend
cd backend
black .
ruff check .

# Frontend
cd frontend
npm run lint

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# API Keys (at least one required)
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# Application Settings
ENVIRONMENT=production
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///./threatforge.db

# Optional: Custom ports
FRONTEND_PORT=80
BACKEND_PORT=8000

API Key Setup

OpenAI: Get your API key from OpenAI Platform
Anthropic: Get your API key from Anthropic Console

At least one API key is required for scenario generation. For testing, the application will use a mock provider if no keys are configured.

📖 Usage

Fill out the scenario form with your requirements:
- Company name and industry
- Company size (small to enterprise)
- Threat actor type (ransomware, APT, insider, etc.)
- Exercise duration
- Technologies and participants
- AI provider preference
Generate scenarios with a single click
Use the reroll feature to regenerate specific sections
Compare costs across different AI providers
Review and export your generated scenario

🏗️ Project Structure

threatforge/
├── backend/                 # FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── core/           # Configuration
│   │   ├── models/         # Database models
│   │   ├── schemas/        # Pydantic models
│   │   └── services/       # Business logic & AI services
│   ├── tests/              # Test files
│   └── requirements.txt    # Python dependencies
├── frontend/               # Vue.js frontend
│   ├── src/
│   │   ├── components/     # Vue components
│   │   ├── assets/         # Static assets
│   │   └── views/          # Page components
│   ├── package.json        # Node dependencies
│   └── vite.config.js      # Vite configuration
├── docker/                 # Docker configuration
│   ├── Dockerfile.frontend
│   ├── Dockerfile.backend
│   └── nginx.conf
├── docs/                   # Documentation
├── docker-compose.dev.yml  # Development setup
├── docker-compose.prod.yml # Production setup
└── README.md

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow the existing code style (Black for Python, ESLint for JavaScript)
Add tests for new features
Update documentation as needed
Ensure all tests pass before submitting

🗺️ Roadmap

Upcoming Features

🔐 Multi-user Support - User authentication and scenario sharing
📊 Analytics Dashboard - Usage statistics and scenario metrics
🔄 Scenario Templates - Pre-built templates for common scenarios
📱 Mobile App - Native mobile application
🌐 Multi-language Support - Internationalization
🔗 API Integrations - Connect with security tools and platforms
📈 Advanced Analytics - Scenario effectiveness tracking
🎯 Custom AI Models - Fine-tuned models for specific industries

Version 2.0 Goals

Collaborative Editing - Real-time scenario collaboration
Advanced AI Features - Custom model training
Enterprise Features - SSO, RBAC, audit logs
API Marketplace - Third-party integrations

📄 License

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

🙏 Acknowledgments

Built with FastAPI and Vue.js
UI components from PrimeVue
AI capabilities powered by OpenAI and Anthropic
Icons from Heroicons

Threat Modeling File Upload Feature

This feature provides AI-powered threat modeling analysis for cybersecurity systems. Users can upload diagram files or provide text descriptions of systems to generate comprehensive threat models using various frameworks.

Supported File Types

DRAWIO (.drawio) - Diagram files for system architecture
PNG (.png) - Image files
JPG (.jpg) - Image files
SVG (.svg) - Vector graphics
XML (.xml) - XML-based diagrams

File Size Limit

Maximum file size: 10MB

AI-Powered Threat Modeling

The system uses advanced AI models (OpenAI GPT and Anthropic Claude) to generate comprehensive threat models based on:

System descriptions - Text-based descriptions of systems, architectures, or components
Uploaded diagrams - Visual representations of system architecture
Multiple frameworks - STRIDE, LINDDUN, PASTA, and Attack Trees analysis

Generated Threat Models Include

System Overview - Brief description of the analyzed system
Asset Identification - Key assets, data, and components
Threat Actors - Potential attackers and their motivations
Threat Analysis - Detailed threats using the selected framework
Risk Assessment - Threat ratings (High/Medium/Low) based on likelihood and impact
Mitigation Strategies - Recommended controls and countermeasures
Security Recommendations - Overall security posture improvements

API Endpoints

POST /api/threat-model/upload — Upload a diagram file (multipart/form-data, field: file)
GET /api/threat-model/files — List uploaded files
DELETE /api/threat-model/files/{file_id} — Delete a file by its ID
POST /api/threat-model/generate — Generate AI-powered threat model (synchronous)
POST /api/threat-model/generate-async — Generate AI-powered threat model (asynchronous)
GET /api/threat-model/jobs/{job_id} — Get async job status and progress
DELETE /api/threat-model/jobs/{job_id} — Cancel an async job
GET /api/threat-model/jobs — List recent jobs
POST /api/threat-model/estimate-cost — Estimate costs across all AI providers
GET /api/threat-model/providers — Get available AI providers

Example Async Threat Model Generation Request

curl -X POST "http://localhost:8000/api/threat-model/generate-async" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A web application with user authentication and database storage",
    "framework": "STRIDE",
    "file_id": "optional-uploaded-file-id",
    "llm_provider": "openai"
  }'

Example Job Status Check

curl -X GET "http://localhost:8000/api/threat-model/jobs/{job_id}"

Example Threat Model Generation Request

curl -X POST "http://localhost:8000/api/threat-model/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A web application with user authentication and database storage",
    "framework": "STRIDE",
    "file_id": "optional-uploaded-file-id",
    "llm_provider": "openai"
  }'

Example Cost Estimation Request

curl -X POST "http://localhost:8000/api/threat-model/estimate-cost" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A cloud-based microservices application",
    "framework": "STRIDE",
    "llm_provider": "openai"
  }'

Frontend Usage

Use the "Threat Model Upload" button at the top of the app to switch to the threat modeling interface
Upload supported diagram files for additional context (optional)
Provide a detailed system description in the text area
Select a threat modeling framework (STRIDE, LINDDUN, PASTA, Attack Trees)
Choose an AI provider (OpenAI or Anthropic)
Generate comprehensive threat models with cost estimation
Export results in multiple formats (Text, Markdown, JSON, PDF)

Features

Drag & Drop Upload - Easy file upload with visual feedback
Multi-file Support - Upload and manage multiple diagram files
Bulk Operations - Select and delete multiple files at once
Progress Tracking - Real-time upload progress indicators
Cost Comparison - Compare costs across different AI providers
Export Options - Download threat models in various formats
Form Validation - Real-time validation and error handling
Async Processing - Background job processing for complex analyses
Progress Monitoring - Real-time job status and progress tracking
Result Caching - Automatic caching to avoid regenerating similar models
Job Management - View, cancel, and manage async generation jobs
Dual Generation Modes - Choose between synchronous and asynchronous processing
Visual Threat Modeling - Interactive diagram-based threat modeling
Component Library - Pre-built components for common system elements
Threat Mapping - Visual threat assignment to system components
Advanced Export - Professional PDF reports and executive summaries
Compliance Reports - Framework-specific compliance analysis
Custom Templates - Configurable export templates and formats

Made with ❤️ by the ThreatForge team

📚 Documentation

User Guides

Quick Start Guide - Get up and running in 5 minutes
Threat Modeling User Guide - Comprehensive guide to threat modeling
Best Practices - Best practices for effective threat modeling
Sample Threat Models - Examples and templates

Features Overview

🤖 AI-Powered Threat Modeling

Multiple Frameworks: STRIDE, LINDDUN, PASTA, Attack Trees
AI Providers: OpenAI GPT and Anthropic Claude integration
Async Processing: Background job processing with progress tracking
Intelligent Caching: Automatic result caching for similar requests

🎨 Visual Threat Modeling

Interactive Diagrams: Drag-and-drop system component creation
Component Library: Pre-built components for common system elements
Threat Mapping: Visual threat assignment to system components
Real-time Collaboration: Multi-user threat modeling sessions
Diagram Export: Export diagrams in multiple formats

📊 Advanced Export Options

PDF Reports: Professional PDF reports with executive summaries
Executive Summaries: High-level summaries for stakeholders
Technical Reports: Detailed technical analysis for security teams
Compliance Reports: Compliance-focused reports with controls mapping
Custom Templates: Configurable export templates and formats

🔄 Workflow Integration

File Upload: Support for DRAWIO, PNG, JPG, SVG, XML diagrams
Job Monitoring: Real-time tracking of async threat model generation
Cost Comparison: Compare costs across different AI providers
Export Integration: Export to various formats and platforms

API Documentation

Threat Modeling API: POST /api/threat-model/generate, POST /api/threat-model/generate-async
File Management: POST /api/threat-model/upload, GET /api/threat-model/files, DELETE /api/threat-model/files/clear
Job Management: GET /api/threat-model/jobs/{job_id}, DELETE /api/threat-model/jobs/{job_id}
Cost Estimation: POST /api/threat-model/estimate-cost
Provider Information: GET /api/threat-model/providers

Interactive Features

Built-in Tutorial: Click the "Tutorial" button in the threat modeling interface
Visual Modeling: Switch between text-based and visual threat modeling
Real-time Job Monitoring: Track async threat model generation progress
Cost Comparison: Compare costs across different AI providers
Advanced Export: Generate professional reports in multiple formats

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.claude		.claude
.github		.github
backend		backend
docker		docker
docs		docs
frontend		frontend
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
package-lock.json		package-lock.json
package.json		package.json

License

xFreed0m/threatforge

Folders and files

Latest commit

History

Repository files navigation