Security Report Builder Agent

Generate professional, executive-ready security reports from plugin security scanner results. Produces HTML, PDF, and DOCX formats with context-aware analysis to reduce false positives.

Capabilities

Report Generation:

• Generate interactive HTML reports with modern dark theme
• Create professional PDF reports for printing and archival
• Export editable DOCX reports for collaboration
• Support multiple report templates (Executive, Technical, Compliance)

Intelligent Analysis:

• Context-aware severity adjustment (reduce 85-90% false positive rate)
• Taint analysis to identify real user input risks
• Framework mapping (MITRE ATT&CK, ATLAS, OWASP, CWE)
• Risk scoring with contextual intelligence

Customization:

• Configurable branding (logo, colors, company name)
• Template selection for different audiences
• Severity filtering (exclude INFO/LOW findings)
• False positive exclusion rules

Usage

When the user requests a security report:

1. Ask for input location:

   • "What is the path to the scan results?" (JSON files or directory)

2. Ask for output preferences:

   • "Which format do you need?" (HTML, PDF, DOCX, or all)
   • "Which template should I use?" (Executive, Technical, Compliance)

3. Confirm customization:

   • "Should I apply false positive filtering?" (recommended: yes)
   • "What minimum severity level?" (CRITICAL, HIGH, MEDIUM, LOW, INFO)

4. Generate reports:

   • Parse scan result JSON files
   • Apply context-aware analysis
   • Map to security frameworks
   • Generate requested format(s)
   • Save to output directory

5. Provide summary:

   • Report location and file size
   • Key statistics (total findings, adjusted findings, top issues)
   • Recommendations for next steps

Commands

Use the main report generation script:

python3 security-report-builder/scripts/generate_report.py \
  --input <scan_results_path> \
  --output <output_path> \
  --formats html,pdf,docx \
  --template executive \
  --min-severity MEDIUM \
  --exclude-false-positives

Configuration Files

• config/report_config.json: Report structure and sections
• config/severity_rules.json: Context-aware severity adjustment rules
• config/branding.json: Company logo, colors, footer text
• references/framework_mappings.json: MITRE ATT&CK/ATLAS/OWASP/CWE data

Report Structure

Executive Summary Report

• High-level risk assessment
• Top 10 critical findings
• Business impact analysis
• Recommended actions
• 1-2 pages

Technical Deep Dive Report

• Detailed findings with code examples
• Framework mappings (MITRE ATT&CK/ATLAS)
• Remediation steps per finding
• Severity distribution charts
• 10-50 pages

Compliance Audit Report

• Regulatory framework alignment
• Control mappings (NIST, ISO 27001, SOC 2)
• Gap analysis
• Evidence collection
• 5-15 pages

Context-Aware Analysis

The agent automatically adjusts severity based on context:

innerHTML Usage:

• innerHTML = '' → INFO (safe clearing operation)
• innerHTML = static string → LOW (best practice recommendation)
• innerHTML = template without user input → MEDIUM (verify escaping)
• innerHTML = user input → CRITICAL (real XSS risk)

eval() Usage:

• eval() in controlled environment → MEDIUM (code smell)
• eval(userInput) → CRITICAL (code execution risk)

File Operations:

• File read/write with static paths → LOW
• File operations with user-controlled paths → CRITICAL (path traversal)

Integration

Input Format: JSON files from plugin-security-checker with structure:

{
  "metadata": {"plugin_name": "...", "scan_date": "..."},
  "findings": [
    {
      "severity": "CRITICAL",
      "category": "XSS",
      "description": "...",
      "cvss_score": 9.1,
      "att&ck_techniques": ["T1059.006"],
      "code_snippet": "..."
    }
  ],
  "summary": {"total_findings": 10, "risk_score": 300}
}

Output Formats:

• report.html: Interactive dashboard with search/filter
• report.pdf: Professional document with branding
• report.docx: Editable Microsoft Word document
• report_summary.json: Machine-readable statistics

False Positive Reduction

Based on analysis showing 85-90% false positive rate in raw scanner output, apply intelligent filtering:

1. Pattern Recognition: Identify safe patterns (clearing innerHTML, static HTML)
2. Context Analysis: Check for user input in data flow
3. Plugin Type Detection: Web UI plugins expect DOM manipulation
4. Taint Tracking: Follow data from source to sink
5. Severity Adjustment: Downgrade false positives to INFO/LOW

Result: Target <20% false positive rate, matching industry standards (npm audit, Snyk, GitHub Security).

Examples

Generate executive summary:

python3 scripts/generate_report.py \
  --input ../plugin-security-checker/archive_scan_results/ \
  --output reports/executive_summary.pdf \
  --format pdf \
  --template executive \
  --min-severity HIGH

Generate all formats with full details:

python3 scripts/generate_report.py \
  --input scan_results.json \
  --output reports/ \
  --formats html,pdf,docx \
  --template technical \
  --exclude-false-positives

Generate compliance report:

python3 scripts/generate_report.py \
  --input results/ \
  --output compliance_report.docx \
  --format docx \
  --template compliance \
  --config custom_branding.json

Best Practices

1. Always apply false positive filtering for cleaner reports
2. Use Executive template for management/C-suite audiences
3. Use Technical template for security engineers
4. Use Compliance template for auditors and regulators
5. Include company branding for customer-facing reports
6. Generate all three formats for maximum flexibility
7. Archive reports with scan dates for historical tracking