Skip to content

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

26 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

ThreatModelerX

Production-Ready Automated Security Analysis & Threat Modeling Platform

ThreatModelerX is an enterprise-grade, open-source security automation platform that integrates SAST (Static Application Security Testing), threat modeling, and risk prioritization to automatically identify, map, and remediate application security risks across multiple programming languages.

Python Node FastAPI React


πŸš€ Quick Start (5 Minutes)

Prerequisites

  • Docker & Docker Compose (recommended)
  • Node.js 18+ (for local development)
  • Python 3.11+ (for local development)

Start the Application

Option 1: Using Docker Compose (Recommended)

docker-compose up -d

Option 2: Local Development

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend (new terminal)
npm install
npm run dev

Access the Application


✨ Key Features

πŸ” Security Scanning

  • Multi-Language SAST: Semgrep (Python, JavaScript, Java, Go, Ruby), Bandit (Python), Retire.js (JavaScript)
  • Enhanced Rulesets: 4 comprehensive Semgrep rulesets (auto, security-audit, owasp-top-ten, cwe-top-25)
  • Real-Time Updates: Dashboard refreshes every 5 seconds with live scan status
  • Vulnerability Detection: SQL Injection, XSS, Command Injection, Hardcoded Secrets, and 100+ more

πŸ›‘οΈ Threat Modeling

  • STRIDE Framework: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege
  • MITRE ATT&CK Mapping: Links threats to real-world attack techniques (T1059, T1190, T1552.001, etc.)
  • CWE Classification: Common Weakness Enumeration for each finding
  • Risk Scoring: Intelligent prioritization based on severity, exploitability, asset value, and exposure

πŸ“Š Reporting & Management

  • Interactive Dashboard: Real-time statistics and severity breakdown
  • Findings Explorer: Filter by severity, tool, or scan
  • Export Reports: HTML/PDF reports with comprehensive scan results
  • Manual Review: Track finding status, add comments, manage false positives
  • Attack Graph: Visual representation of threat relationships

πŸ”„ Production Features

  • Data Persistence: 30-day retention with SQLite database
  • Automatic Cleanup: Deletes uploads older than 7 days
  • Error Handling: Comprehensive try-catch blocks prevent crashes
  • UTF-8 Support: Handles international characters correctly
  • Concurrent Scans: Background task processing with asyncio

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   React UI      │────────▢│  FastAPI Backend │◀────────│  SQLite DB      β”‚
β”‚  (Frontend)     β”‚         β”‚  (Orchestrator)  β”‚         β”‚  (Scan Results) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                     β”‚
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚                β”‚                β”‚
              β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”
              β”‚  Semgrep  β”‚   β”‚  Bandit   β”‚   β”‚ Retire.js β”‚
              β”‚  Scanner  β”‚   β”‚  Scanner  β”‚   β”‚  Scanner  β”‚
              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                     β”‚
                              β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”
                              β”‚   STRIDE    β”‚
                              β”‚Threat Model β”‚
                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Technology Stack

Backend

  • FastAPI: Modern Python web framework with automatic API docs
  • Semgrep: Multi-language static analysis (Python, JS, Java, Go, Ruby)
  • Bandit: Python security linter
  • Retire.js: JavaScript dependency vulnerability scanner
  • SQLite: Lightweight database for scan results
  • NetworkX: Graph analysis for threat modeling

Frontend

  • React 18: Modern UI framework
  • TypeScript: Type-safe JavaScript
  • Vite: Fast build tool and dev server
  • TailwindCSS: Utility-first CSS framework
  • Lucide Icons: Beautiful icon library

πŸ“– Usage Guide

1. Upload Codebase

Via UI:

  1. Click "New Scan" in navigation
  2. Upload a zip file containing your codebase
  3. Select scan types (SAST, Threat Modeling, or both)
  4. Click "Start Analysis"

Via API:

# Upload codebase
curl -X POST http://localhost:8000/api/upload \
  -F "file=@your-codebase.zip"

# Start scan
curl -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/path/to/extracted/code",
    "scan_types": ["sast", "threat_modeling"]
  }'

2. View Results

Dashboard:

  • Total scans, findings, and threats
  • Severity breakdown (Critical, High, Medium, Low)
  • Recent scans list
  • Auto-refreshes every 5 seconds

Findings View:

  • All security findings from all scans
  • Filter by severity or scan
  • Detailed vulnerability information
  • Fix suggestions and CWE mappings

Threats View:

  • STRIDE threat categories
  • Attack vectors and mitigations
  • MITRE ATT&CK technique links
  • Risk level indicators

3. Export Reports

# Generate HTML report
curl http://localhost:8000/api/report/{scan_id}?format=html

# Generate PDF report
curl http://localhost:8000/api/report/{scan_id}?format=pdf

πŸ”§ API Reference

Core Endpoints

Method Endpoint Description
GET / API root
GET /health Health check
GET /docs Interactive API documentation
POST /api/upload Upload codebase zip file
POST /api/scan Start security scan
GET /api/scan/{scan_id} Get scan status and results
GET /api/scans List all scans
GET /api/findings Get all findings (or filter by scan_id)
GET /api/threats Get all threats (or filter by scan_id)
GET /api/stats Get dashboard statistics
GET /api/report/{scan_id} Generate report (HTML/PDF)
DELETE /api/scan/{scan_id} Delete specific scan
POST /api/scans/clear Clear all scans
POST /api/uploads/cleanup Clean old uploads (7+ days)

πŸ§ͺ Testing with Demo App

A vulnerable demo application is included for testing:

Contents:

  • app.py - Python Flask app with 8+ vulnerabilities
  • server.js - Node.js/Express app with 10+ vulnerabilities
  • package.json - Vulnerable dependencies (jQuery 1.8.1, Lodash 4.17.11)

Expected Results:

  • 15+ security findings
  • Multiple STRIDE threats
  • Critical, High, Medium severity issues
  • CWE mappings for each vulnerability

To Test:

  1. Upload demo_vulnerable_app.zip via UI
  2. Select "SAST + Threat Modeling"
  3. View results in Dashboard, Findings, and Threats sections

πŸ”’ Security & Production Features

Risk Scoring Logic

Formula:

Risk Score = Severity Weight Γ— Exploitability Γ— Asset Value Γ— Exposure Factor

Severity Weights:

  • Critical: 10.0
  • High: 6.0
  • Medium: 3.0
  • Low: 1.0

CWE-Based Exploitability:

  • CWE-89 (SQL Injection): 0.9
  • CWE-78 (Command Injection): 0.9
  • CWE-798 (Hardcoded Credentials): 0.95
  • CWE-502 (Insecure Deserialization): 0.85
  • And more...

Asset Value:

  • High-value files (auth, payment): 5.0
  • API/Endpoints: 4.0
  • Standard files: 3.0

Data Management

  • 30-Day Retention: Scan results stored for 30 days
  • Automatic Cleanup: Uploads older than 7 days deleted on startup
  • Manual Cleanup: /api/uploads/cleanup endpoint
  • Database Persistence: SQLite with error handling

Error Handling

  • Comprehensive Try-Catch: All critical operations protected
  • Graceful Degradation: Clear error messages when scanners unavailable
  • Logging: Detailed logs for debugging
  • Timeout Protection: 300-second timeout for scans

🐳 Docker Deployment

Using Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild after changes
docker-compose up -d --build

Manual Docker Build

# Build backend
docker build -t threatmodelx-backend ./backend

# Run backend container
docker run -d -p 8000:8000 threatmodelx-backend

πŸ” Scanner Installation

For local development, install the required scanners:

Semgrep

pip install semgrep
# or
brew install semgrep

Bandit

pip install bandit

Retire.js

npm install -g retire

Verify Installations

semgrep --version
bandit --version
retire --version

πŸ› οΈ Development

Project Structure

ThreatModelerX/
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py              # FastAPI application
β”‚   β”‚   β”œβ”€β”€ models.py            # Data models
β”‚   β”‚   β”œβ”€β”€ scanner/             # Security scanners
β”‚   β”‚   β”‚   β”œβ”€β”€ semgrep_runner.py
β”‚   β”‚   β”‚   β”œβ”€β”€ bandit_runner.py
β”‚   β”‚   β”‚   └── retire_runner.py
β”‚   β”‚   β”œβ”€β”€ threatmodel/         # STRIDE threat modeling
β”‚   β”‚   β”‚   └── stride_mapper.py
β”‚   β”‚   β”œβ”€β”€ workers/             # Background tasks
β”‚   β”‚   β”‚   β”œβ”€β”€ risk_scorer.py
β”‚   β”‚   β”‚   β”œβ”€β”€ report_generator.py
β”‚   β”‚   β”‚   └── remediation_planner.py
β”‚   β”‚   └── uploads/             # Uploaded codebases
β”‚   └── requirements.txt
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ Dashboard.tsx        # Main dashboard
β”‚   β”‚   β”œβ”€β”€ ScanForm.tsx         # Scan creation
β”‚   β”‚   β”œβ”€β”€ FindingsView.tsx     # Security findings
β”‚   β”‚   └── ThreatView.tsx       # Threat modeling
β”‚   β”œβ”€β”€ App.tsx                  # Main app component
β”‚   └── main.tsx                 # Entry point
β”œβ”€β”€ demo_app/                    # Vulnerable demo app
β”œβ”€β”€ demo_vulnerable_app.zip      # Demo zip file
β”œβ”€β”€ docker-compose.yml           # Docker setup
β”œβ”€β”€ package.json                 # Frontend dependencies
└── README.md                    # This file

πŸ“Š Performance Benchmarks

Metric Value
Scan Time (small project) 10-30 seconds
Scan Time (medium project) 1-3 minutes
Dashboard Load Time < 500ms
API Response Time < 100ms
Database Query Time < 50ms
Upload Size Limit 100MB
Concurrent Scans 5+

🀝 Contributing

Contributions are welcome! Please follow these guidelines:

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

πŸ“„ License

This project is licensed under the MIT License.


πŸ™ Acknowledgments

  • Semgrep - Multi-language static analysis
  • Bandit - Python security linter
  • Retire.js - JavaScript vulnerability scanner
  • MITRE ATT&CK - Threat intelligence framework
  • CWE - Common Weakness Enumeration
  • STRIDE - Threat modeling methodology

πŸ“ž Support

For issues, questions, or contributions:


πŸ—ΊοΈ Roadmap

Completed βœ…

  • Multi-language SAST scanning
  • STRIDE threat modeling
  • Real-time dashboard
  • Data persistence (30 days)
  • Automatic cleanup (7 days)
  • Export reports (HTML/PDF)
  • Manual review workflow
  • Risk scoring with CWE-based exploitability
  • MITRE ATT&CK mapping
  • Attack graph generation

Planned 🚧

  • WebSocket for true real-time updates
  • More scanners (Trivy, OWASP ZAP, SpotBugs)
  • Machine learning risk scoring
  • Integration with JIRA/GitHub Issues
  • Kubernetes deployment
  • Multi-tenancy support
  • Advanced analytics dashboard

Made with ❀️ for the security community

Version: 1.0.0 (Production Ready)
Last Updated: December 2025


πŸš€ Quick Start (5 Minutes)

Prerequisites

  • Docker & Docker Compose (recommended)
  • Node.js 18+ (for local development)
  • Python 3.11+ (for local development)

Start the Application

Option 1: Using Docker Compose (Recommended)

docker-compose up -d

Option 2: Local Development

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend (new terminal)
npm install
npm run dev

Access the Application


✨ Key Features

πŸ” Security Scanning

  • Multi-Language SAST: Semgrep (Python, JavaScript, Java, Go, Ruby), Bandit (Python), Retire.js (JavaScript)
  • Recursive Scanning: Automatically scans all files in uploaded codebases
  • Real-Time Updates: Dashboard refreshes every 5 seconds with live scan status
  • Vulnerability Detection: SQL Injection, XSS, Command Injection, Hardcoded Secrets, and 100+ more

πŸ›‘οΈ Threat Modeling

  • STRIDE Framework: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege
  • MITRE ATT&CK Mapping: Links threats to real-world attack techniques
  • CWE Classification: Common Weakness Enumeration for each finding
  • Risk Scoring: Intelligent prioritization based on severity and exploitability

πŸ“Š Reporting & Management

  • Interactive Dashboard: Real-time statistics and severity breakdown
  • Findings Explorer: Filter by severity, tool, or scan
  • Export Reports: HTML/PDF reports with comprehensive scan results
  • Manual Review: Track finding status, add comments, manage false positives
  • Email Notifications: Automated alerts for critical findings

πŸ”„ Production Features

  • Data Persistence: 30-day retention with SQLite database
  • Automatic Cleanup: Deletes uploads older than 7 days
  • Error Handling: Comprehensive try-catch blocks prevent crashes
  • Fallback Mechanisms: Mock data when scanners unavailable
  • UTF-8 Support: Handles international characters correctly

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   React UI      │────────▢│  FastAPI Backend │◀────────│  SQLite DB      β”‚
β”‚  (Frontend)     β”‚         β”‚  (Orchestrator)  β”‚         β”‚  (Scan Results) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                     β”‚
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚                β”‚                β”‚
              β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”
              β”‚  Semgrep  β”‚   β”‚  Bandit   β”‚   β”‚ Retire.js β”‚
              β”‚  Scanner  β”‚   β”‚  Scanner  β”‚   β”‚  Scanner  β”‚
              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                     β”‚
                              β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”
                              β”‚   STRIDE    β”‚
                              β”‚Threat Model β”‚
                              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Technology Stack

Backend

  • FastAPI: Modern Python web framework with automatic API docs
  • Semgrep: Multi-language static analysis (Python, JS, Java, Go, Ruby)
  • Bandit: Python security linter
  • Retire.js: JavaScript dependency vulnerability scanner
  • SQLite: Lightweight database for scan results
  • NetworkX: Graph analysis for threat modeling

Frontend

  • React 18: Modern UI framework
  • TypeScript: Type-safe JavaScript
  • Vite: Fast build tool and dev server
  • TailwindCSS: Utility-first CSS framework
  • Lucide Icons: Beautiful icon library

πŸ“– Usage Guide

1. Upload Codebase

Via UI:

  1. Click "New Scan" in navigation
  2. Upload a zip file containing your codebase
  3. Select scan types (SAST, Threat Modeling, or both)
  4. Click "Start Scan"

Via API:

# Upload codebase
curl -X POST http://localhost:8000/api/upload \
  -F "file=@your-codebase.zip"

# Start scan
curl -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "repo_path": "/path/to/extracted/code",
    "scan_types": ["sast", "threat_modeling"]
  }'

2. View Results

Dashboard:

  • Total scans, findings, and threats
  • Severity breakdown (Critical, High, Medium, Low)
  • Recent scans list
  • Auto-refreshes every 5 seconds

Findings View:

  • All security findings from all scans
  • Filter by severity or scan
  • Detailed vulnerability information
  • Fix suggestions and CWE mappings

Threats View:

  • STRIDE threat categories
  • Attack vectors and mitigations
  • MITRE ATT&CK technique links
  • Risk level indicators

3. Export Reports

# Generate HTML report
curl http://localhost:8000/api/report/{scan_id}?format=html

# Generate PDF report
curl http://localhost:8000/api/report/{scan_id}?format=pdf

# Email report
curl http://localhost:8000/api/report/{scan_id}?format=html&email=user@example.com

πŸ”§ API Reference

Core Endpoints

Method Endpoint Description
GET / API root
GET /health Health check
GET /docs Interactive API documentation
POST /api/upload Upload codebase zip file
POST /api/scan Start security scan
GET /api/scan/{scan_id} Get scan status and results
GET /api/scans List all scans
GET /api/findings Get all findings (or filter by scan_id)
GET /api/threats Get all threats (or filter by scan_id)
GET /api/stats Get dashboard statistics
GET /api/report/{scan_id} Generate report (HTML/PDF)
DELETE /api/scan/{scan_id} Delete specific scan
POST /api/scans/clear Clear all scans
POST /api/uploads/cleanup Clean old uploads (7+ days)

Example: Complete Scan Workflow

# 1. Upload codebase
UPLOAD_RESPONSE=$(curl -X POST http://localhost:8000/api/upload \
  -F "file=@demo_vulnerable_app.zip")
REPO_PATH=$(echo $UPLOAD_RESPONSE | jq -r '.path')

# 2. Start scan
SCAN_RESPONSE=$(curl -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d "{\"repo_path\": \"$REPO_PATH\", \"scan_types\": [\"sast\", \"threat_modeling\"]}")
SCAN_ID=$(echo $SCAN_RESPONSE | jq -r '.scan_id')

# 3. Check status
curl http://localhost:8000/api/scan/$SCAN_ID

# 4. Get findings
curl http://localhost:8000/api/findings?scan_id=$SCAN_ID

# 5. Get threats
curl http://localhost:8000/api/threats?scan_id=$SCAN_ID

# 6. Generate report
curl http://localhost:8000/api/report/$SCAN_ID?format=html > report.html

πŸ§ͺ Testing with Demo App

A vulnerable demo application is included for testing:

Contents:

  • app.py - Python Flask app with 8+ vulnerabilities
  • server.js - Node.js/Express app with 10+ vulnerabilities
  • package.json - Vulnerable dependencies (jQuery 1.8.1, Lodash 4.17.11)

Expected Results:

  • 15+ security findings
  • Multiple STRIDE threats
  • Critical, High, Medium severity issues
  • CWE mappings for each vulnerability

To Test:

  1. Upload demo_vulnerable_app.zip via UI
  2. Select "SAST + Threat Modeling"
  3. View results in Dashboard, Findings, and Threats sections

πŸ”’ Security & Production Features

Data Management

  • 30-Day Retention: Scan results stored for 30 days
  • Automatic Cleanup: Uploads older than 7 days deleted on startup
  • Manual Cleanup: /api/uploads/cleanup endpoint
  • Database Persistence: SQLite with error handling

Error Handling

  • Comprehensive Try-Catch: All critical operations protected
  • Graceful Degradation: Fallback to mock data if scanners fail
  • Logging: Detailed logs for debugging
  • Timeout Protection: 300-second timeout for scans

Performance

  • Real-Time Updates: Dashboard polls every 5 seconds
  • Optimized Queries: Efficient database operations
  • Gzip Compression: Reduced API response sizes
  • Caching: LRU cache for expensive operations

Scalability

  • Concurrent Scans: Background task processing
  • Resource Limits: Timeout and size limits
  • Clean Architecture: Modular scanner design
  • Docker Ready: Easy horizontal scaling

πŸ› οΈ Development

Project Structure

ThreatModelerX/
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py              # FastAPI application
β”‚   β”‚   β”œβ”€β”€ models.py            # Data models
β”‚   β”‚   β”œβ”€β”€ scanner/             # Security scanners
β”‚   β”‚   β”‚   β”œβ”€β”€ semgrep_runner.py
β”‚   β”‚   β”‚   β”œβ”€β”€ bandit_runner.py
β”‚   β”‚   β”‚   └── retire_runner.py
β”‚   β”‚   β”œβ”€β”€ threatmodel/         # STRIDE threat modeling
β”‚   β”‚   β”œβ”€β”€ workers/             # Background tasks
β”‚   β”‚   β”œβ”€β”€ templates/           # Report templates
β”‚   β”‚   └── uploads/             # Uploaded codebases
β”‚   └── requirements.txt
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ components/
β”‚   β”‚   β”œβ”€β”€ Dashboard.tsx        # Main dashboard
β”‚   β”‚   β”œβ”€β”€ ScanForm.tsx         # Scan creation
β”‚   β”‚   β”œβ”€β”€ FindingsView.tsx     # Security findings
β”‚   β”‚   └── ThreatView.tsx       # Threat modeling
β”‚   β”œβ”€β”€ App.tsx                  # Main app component
β”‚   └── main.tsx                 # Entry point
β”œβ”€β”€ demo_app/                    # Vulnerable demo app
β”œβ”€β”€ demo_vulnerable_app.zip      # Demo zip file
β”œβ”€β”€ docker-compose.yml           # Docker setup
β”œβ”€β”€ package.json                 # Frontend dependencies
└── README.md                    # This file

Adding New Scanners

  1. Create scanner class in backend/app/scanner/
  2. Implement run(repo_path) method
  3. Return list of Finding objects
  4. Register in main.py

Example:

class MyScanner:
    def run(self, repo_path: str) -> List[Finding]:
        # Scan logic here
        return findings

Environment Variables

# Backend
DATABASE_URL=sqlite:///scan_results.db
UPLOAD_DIR=./uploads
MAX_UPLOAD_SIZE=100MB
SCAN_TIMEOUT=300

# Frontend
VITE_API_URL=http://localhost:8000

🐳 Docker Deployment

Using Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild after changes
docker-compose up -d --build

Manual Docker Build

# Build backend
docker build -t threatmodelx-backend ./backend

# Build frontend
docker build -t threatmodelx-frontend .

# Run containers
docker run -d -p 8000:8000 threatmodelx-backend
docker run -d -p 5173:5173 threatmodelx-frontend

πŸ” Troubleshooting

Backend Issues

Database locked:

# Stop backend, delete database, restart
rm backend/app/scan_results.db

Scanners not found:

# Install scanners
pip install semgrep bandit
npm install -g retire

Port already in use:

# Change port in uvicorn command
uvicorn app.main:app --port 8001

Frontend Issues

Build errors:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

API connection failed:

  • Check backend is running on port 8000
  • Verify CORS settings in backend/app/main.py
  • Check browser console for errors

πŸ“Š Performance Benchmarks

Metric Value
Scan Time (small project) 10-30 seconds
Scan Time (medium project) 1-3 minutes
Dashboard Load Time < 500ms
API Response Time < 100ms
Database Query Time < 50ms
Upload Size Limit 100MB
Concurrent Scans 5+

🀝 Contributing

Contributions are welcome! Please follow these guidelines:

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

πŸ“„ License

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


πŸ™ Acknowledgments

  • Semgrep - Multi-language static analysis
  • Bandit - Python security linter
  • Retire.js - JavaScript vulnerability scanner
  • MITRE ATT&CK - Threat intelligence framework
  • CWE - Common Weakness Enumeration
  • STRIDE - Threat modeling methodology

πŸ“ž Support

For issues, questions, or contributions:


πŸ—ΊοΈ Roadmap

Completed βœ…

  • Multi-language SAST scanning
  • STRIDE threat modeling
  • Real-time dashboard
  • Data persistence (30 days)
  • Automatic cleanup (7 days)
  • Export reports (HTML/PDF)
  • Manual review workflow

Planned 🚧

  • WebSocket for true real-time updates
  • More scanners (Trivy, OWASP ZAP, SpotBugs)
  • Machine learning risk scoring
  • Integration with JIRA/GitHub Issues
  • Kubernetes deployment
  • Multi-tenancy support
  • Advanced analytics dashboard

Made with ❀️ for the security community

Version: 1.0.0 (Production Ready)
Last Updated: November 2025

About

ThreatModelerX is a local-first Application Security automation platform that performs threat modeling, secure code scanning, and vulnerability visualization. It integrates Semgrep, Bandit, and Retire.js with an automated STRIDE engine to help developers identify and remediate risks across Python, Node.js, and Java.

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages