Semgrep Report Builder

A comprehensive Flask web application for generating professional PDF security reports from Semgrep findings.

⚠️ Important Disclaimers

This is an open source project developed by Chris Morris in combination with Cursor AI. This application is NOT an officially released product of Semgrep, Inc.

• Semgrep, Inc. and the author are in no way legally responsible for any misuse of this application or any damages caused by its use
• Users assume all risk and responsibility when using this software
• Use at your own risk

🚀 What This Application Does

The Semgrep Report Builder connects to your Semgrep AppSec Platform deployment and generates three types of professional PDF security reports:

📊 Executive Summary Report

• High-level security overview across all selected projects
• Findings categorized by severity (Critical, High, Medium, Low)
• Separate tables for SAST (Code Analysis) and SCA (Supply Chain Analysis) findings
• Top risk areas mapped to OWASP Top 10 categories
• Scan metrics including duration, files scanned, and last scan date
• Project hyperlinks to Semgrep platform

📋 Audit Detail Report

• Complete executive summary section
• Detailed language breakdown showing files scanned, parsed, and bytes processed
• Comprehensive vulnerability classes summary with:
  • Vulnerability classes extracted from Semgrep findings
  • CWE (Common Weakness Enumeration) classifications
  • OWASP (Open Web Application Security Project) classifications
  • Definitions of OWASP, CWE, and CVE standards

🔍 Detailed Vulnerability Report

• Complete executive summary section
• Detailed findings separated by product type (SAST, SCA, Secrets)
• For each finding includes:
  • SAST findings: Rule details, location, description, suggested fixes, remediation guidance
  • SCA findings: Vulnerability ID, affected dependencies, fix recommendations, reachability analysis
  • Common fields: Vulnerability classes, CWE mappings, OWASP classifications

✨ Key Features

Multi-Project Support

• Individual Reports: Generate separate reports for each project and report type combination
• Merged Reports: Combine multiple projects into single reports when "Merge reports by type" is enabled

Advanced Filtering

• Severity Filtering: Include/exclude findings by severity level (Critical, High, Medium, Low)
• Reachability Filtering: SCA findings filtered by reachability status (reachable, conditionally reachable, always reachable, no reachability analysis)
• True Positive Filtering: SAST findings filtered to include only Semgrep Assistant true positives

Professional Output

• Clean Design: Professional, minimal interface with clean styling
• Hyperlinked Project Names: Direct links to projects in Semgrep platform
• Dynamic Layouts: Tables adapt based on selected severity levels
• Comprehensive Data: Extracts vulnerability classes, CWE, and OWASP classifications from API

Secure Implementation

• Secure Credential Storage: API tokens stored using system keyring
• Input Validation: Comprehensive validation of all user inputs
• Path Traversal Protection: File operations use werkzeug.secure_filename and strict validation
• XSS Prevention: Safe DOM manipulation without innerHTML
• CDN Integrity: Bootstrap CSS includes integrity checks

🛠️ Prerequisites

System Requirements

• Python 3.8 or higher
• pip (Python package installer)
• Access to Semgrep AppSec Platform

Semgrep Requirements

• Valid Semgrep API token with appropriate permissions
• Deployment slug and deployment ID from your Semgrep organization
• Projects with completed scans in your Semgrep deployment

📦 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd reportBuilder

2. Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Run the Application

export FLASK_APP=app.py
export FLASK_ENV=development
export FLASK_DEBUG=1
flask run --port 5001

The application will be available at http://127.0.0.1:5001

🔧 Configuration

Initial Setup

1. Open the application in your web browser
2. Enter your Semgrep credentials:
   • API Token: Your Semgrep API token (stored securely in system keyring)
   • Deployment Slug: Your organization's deployment slug (e.g., your-org-name)
   • Deployment ID: Your deployment ID (numeric, e.g., 12345)
3. Save Configuration: Credentials are securely stored and will persist between sessions

Finding Your Semgrep Credentials

• API Token: Generate in Semgrep platform under Settings → API Tokens
• Deployment Slug: Found in your Semgrep organization URL
• Deployment ID: Available in your organization settings or API responses

📖 Usage Guide

Basic Workflow

1. Configure API credentials (one-time setup)
2. Select projects from the list (supports search by name or tags)
3. Choose report types:
   • Executive Summary
   • Audit Detail
   • Detailed Vulnerability Report
4. Set severity filters (Critical, High, Medium, Low)
5. Choose report mode:
   • Individual reports: Separate report for each project/type combination
   • Merged reports: Combined reports when "Merge reports by type" is checked
6. Generate reports: Download individual PDF or ZIP file with multiple reports

Report Generation Options

Single Project, Single Report Type

• Result: Individual PDF download

Single Project, Multiple Report Types

• Result: ZIP file containing separate PDFs for each report type

Multiple Projects, Individual Mode

• Result: ZIP file containing separate PDFs for each project/report type combination

Multiple Projects, Merged Mode

• Result: Combined reports showing all projects in single PDFs

🏗️ Project Structure

reportBuilder/
├── app.py                 # Main Flask application
├── semgrep_client.py      # Semgrep API client
├── project.py             # Project data model
├── report_generator.py    # PDF report generation
├── config.json            # Application configuration
├── requirements.txt       # Python dependencies
├── static/
│   ├── css/main.css      # Application styles
│   ├── js/main.js        # Frontend JavaScript
│   └── img/              # Static images
├── templates/
│   └── index.html        # Main HTML template
└── .venv/                # Virtual environment (created during setup)

🔍 Dependencies

Core Dependencies

• Flask 2.3.3: Web framework
• requests 2.31.0: HTTP client for Semgrep API
• reportlab 4.0.4: PDF generation
• matplotlib 3.7.2: Charts and visualizations
• keyring 24.2.0: Secure credential storage
• cryptography 41.0.4: Cryptographic functions
• python-dotenv 1.0.0: Environment variable management

Frontend Dependencies

• Bootstrap 5.3.0: UI framework (loaded from CDN)
• Custom CSS: Application-specific styling

🔒 Security Features

• Secure Credential Storage: API tokens stored in system keyring, never in plain text
• Input Validation: All user inputs validated and sanitized
• XSS Prevention: Safe DOM manipulation without innerHTML
• CDN Integrity: External resources include integrity checks
• Error Handling: Comprehensive exception handling with secure error messages

🐛 Troubleshooting

Common Issues

"Missing configuration" Error

• Ensure all three credentials (API token, deployment slug, deployment ID) are provided
• Verify credentials are correct by testing API access

"No projects found" Error

• Check that your deployment has projects with completed scans
• Verify deployment slug and ID are correct

"Failed to generate reports" Error

• Ensure selected projects have findings data
• Check that severity filters include at least one level with findings
• Verify sufficient disk space for PDF generation

Empty Reports

• Confirm projects have completed scans with findings
• Check severity filtering - ensure selected severities have actual findings
• Verify API permissions allow access to findings data

Debug Mode

Enable debug logging by setting:

export FLASK_DEBUG=1

🤝 Contributing

This is an open source project. Contributions are welcome via pull requests.

Development Setup

1. Follow installation instructions above
2. Make changes in a feature branch
3. Test thoroughly with various project configurations
4. Submit pull request with clear description

📄 License

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

🙏 Acknowledgments

• Semgrep: For providing the excellent security analysis platform and API
• Cursor AI: For development assistance and code generation
• ReportLab: For the powerful PDF generation library
• Bootstrap: For the responsive UI framework

---

Remember: This is an unofficial tool. Always verify report accuracy against your Semgrep platform data.