security-report-builder

What this skill does

# Security Report Builder

**Version:** 1.2.0
**Category:** Security, Reporting, Documentation
**Author:** Security Team

## Overview

Professional security report generator that transforms raw plugin security scanner results into executive-ready reports. Produces HTML, PDF, and DOCX formats with intelligent false positive filtering and context-aware risk assessment.

## Key Features

### 🎯 Context-Aware Analysis
- Reduces false positive rate from 85-90% to <20%
- Intelligent severity adjustment based on code context
- Taint analysis to identify real user input risks
- Plugin type detection (web UI vs CLI plugins)

### 📊 Multiple Output Formats
- **HTML**: Interactive dashboard with modern dark theme
- **PDF**: Professional print-ready reports with branding
- **DOCX**: Editable Microsoft Word documents for collaboration

### 🔍 Framework Integration
- MITRE ATT&CK technique mapping
- MITRE ATLAS (ML security) coverage
- OWASP Top 10 alignment
- CWE weakness classification

### 📈 Risk Assessment
- Context-adjusted risk scoring
- Per-plugin and overall risk levels
- Actionable prioritization
- Executive summary generation

## Installation

```bash
# Install dependencies
pip install -r security-report-builder/requirements.txt

# Core dependencies:
# - jinja2>=3.1.0 (HTML templating)
# - weasyprint>=60.0 (PDF generation)
# - python-docx>=1.1.0 (DOCX generation)
# - pandas>=2.0.0 (data analysis)
# - numpy>=1.24.0 (statistics)
```

## Usage

### Basic Usage

```bash
# Generate all formats (HTML, PDF, DOCX)
python3 security-report-builder/scripts/generate_report.py \
  --input plugin-security-checker/archive_scan_results/ \
  --output reports/ \
  --formats html,pdf,docx

# Generate HTML report only
python3 security-report-builder/scripts/generate_report.py \
  --input scan_results.json \
  --output report.html \
  --format html

# Generate PDF with minimum severity HIGH
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output report.pdf \
  --format pdf \
  --min-severity HIGH
```

### Advanced Usage

```bash
# Executive summary template (1-2 pages)
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output executive_report.pdf \
  --format pdf \
  --template executive \
  --min-severity HIGH

# Technical deep dive (full details)
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output technical_report.html \
  --format html \
  --template technical

# Compliance audit report
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output compliance_report.docx \
  --format docx \
  --template compliance

# Custom branding
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output reports/ \
  --formats html,pdf,docx \
  --branding custom_branding.json

# Disable false positive filtering
python3 security-report-builder/scripts/generate_report.py \
  --input results/ \
  --output raw_report.html \
  --format html \
  --no-filter
```

## Configuration

### Report Templates

Edit `config/report_config.json` to customize report structure:

- **Executive**: High-level for C-suite (1-2 pages)
- **Technical**: Detailed for engineers (10-50 pages)
- **Compliance**: Regulatory alignment (5-15 pages)

### Severity Rules

Edit `config/severity_rules.json` to adjust context-aware filtering:

```json
{
  "innerHTML": {
    "patterns": [
      {
        "pattern": "innerHTML\\s*=\\s*['\"]\\s*['\"]",
        "adjusted_severity": "INFO",
        "reason": "Clearing content - safe operation"
      }
    ]
  }
}
```

### Branding

Edit `config/branding.json` for custom appearance:

```json
{
  "company_name": "Your Organization",
  "logo_path": "/path/to/logo.png",
  "primary_color": "#6366f1",
  "secondary_color": "#8b5cf6",
  "footer_text": "Confidential - Internal Use Only"
}
```

## Input Format

The plugin expects JSON files from `plugin-security-checker` with this structure:

```json
{
  "metadata": {
    "plugin_name": "example-plugin",
    "scan_date": "2025-10-29T10:30:00",
    "scanner_version": "3.0.0"
  },
  "findings": [
    {
      "severity": "CRITICAL",
      "category": "XSS",
      "description": "Potential cross-site scripting vulnerability",
      "code_snippet": "element.innerHTML = userInput;",
      "cvss_score": 9.1,
      "att&ck_techniques": ["T1059.006"],
      "owasp_categories": ["A03:2021-Injection"],
      "cwe_ids": ["CWE-79"]
    }
  ],
  "summary": {
    "total_findings": 10,
    "risk_score": 300,
    "risk_level": "CRITICAL"
  }
}
```

## Output Examples

### HTML Report Features
- Interactive dashboard with search/filter
- Dark theme with gradient accents
- Collapsible sections
- Severity distribution charts
- Responsive design (mobile-friendly)
- Print-optimized CSS

### PDF Report Features
- Professional layout (A4/Letter)
- Page numbers and headers/footers
- Table of contents
- Company branding (logo, colors)
- Print-ready quality
- Vector graphics support

### DOCX Report Features
- Microsoft Word format (.docx)
- Editable sections
- Styled headings and tables
- Track changes compatible
- Comments support
- Professional typography

## Report Sections

### 1. Executive Summary
- Overall risk level and score
- Key statistics
- Business impact assessment
- Top 10 critical findings
- Recommended actions

### 2. Key Statistics
- Total plugins analyzed
- Findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
- Findings by category
- Scan date range

### 3. Top Risky Plugins
- Plugin name and risk score
- Number of findings (total and by severity)
- Risk level classification
- False positive count

### 4. Critical Findings
- Detailed description
- Code snippets
- Plugin context
- Framework mappings (ATT&CK, OWASP, CWE)
- Remediation recommendations

### 5. Framework Analysis
- MITRE ATT&CK coverage (techniques and tactics)
- MITRE ATLAS coverage (ML security)
- OWASP Top 10 alignment
- CWE weakness distribution

### 6. False Positive Analysis
- Original vs. adjusted findings
- Context-aware filtering results
- Severity adjustments
- False positive rate

## Context-Aware Features

### innerHTML Detection
- `innerHTML = ''` → INFO (safe clearing)
- `innerHTML = static HTML` → LOW (best practice: use textContent)
- `innerHTML = template` → MEDIUM (verify escaping)
- `innerHTML = userInput` → CRITICAL (real XSS risk)

### eval() Detection
- `eval('static string')` → MEDIUM (code smell)
- `eval(userInput)` → CRITICAL (code execution risk)

### File Operations
- `readFile('/static/path')` → LOW (safe)
- `readFile(userPath)` → CRITICAL (path traversal risk)

### Plugin Type Context
- Web UI plugins: Expected to use DOM manipulation (reduced penalties)
- CLI plugins: DOM usage is suspicious (increased severity)

## Integration with Plugin Security Checker

```bash
# Step 1: Scan plugins
python3 plugin-security-checker/scripts/scan_plugin.py \
  my-plugin/ \
  --output scan_results.json

# Step 2: Generate report
python3 security-report-builder/scripts/generate_report.py \
  --input scan_results.json \
  --output report.html \
  --format html
```

## Performance

- **Parsing**: ~1,000 plugins/second
- **Analysis**: ~500 findings/second
- **Report Generation**:
  - HTML: <5 seconds for 1,000 plugins
  - PDF: <15 seconds for 1,000 plugins
  - DOCX: <10 seconds for 1,000 plugins

## Troubleshooting

### WeasyPrint Installation Issues

```bash
# macOS
brew install python3 cairo pango gdk-pixbuf libffi
pip install weasyprint

# Ubuntu/Debian
sudo apt-get install python3-dev python3-pip python3-cffi python3-brotli \
  libpango-1.0-0 libpangoft2-1.0-0 libcairo2
pip install weasyprint

# Windows
pip install weasyprint
# May require additional system dependencies
```

### Missing Framework Mappings

If framework mappings are not found:

```bash
# Copy from plugin-security-checker
cp plugin-security-checker/references/threat_mappings.json \
   security-report-builder/references/framework_mapping