Initial commit

2025-11-29 18:20:54 +08:00
commit 5cbffe7347
4 changed files with 258 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "security-report-builder",
+  "description": "Professional security report generator with HTML, PDF, and DOCX output. Reduces false positives through context-aware analysis.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Diego Consolini",
+    "email": "diego@diegocon.nl"
+  },
+  "agents": [
+    "./agents/"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# security-report-builder
+
+Professional security report generator with HTML, PDF, and DOCX output. Reduces false positives through context-aware analysis.
--- a/agents/security-report-builder.md
+++ b/agents/security-report-builder.md
@@ -0,0 +1,198 @@
+---
+description: Generate professional security reports from scan results in HTML, PDF, and DOCX formats with intelligent false positive filtering
+capabilities: ["report-generation", "html-reports", "pdf-reports", "docx-reports", "false-positive-filtering", "context-aware-analysis", "risk-assessment", "mitre-attack-mapping", "compliance-reporting"]
+---
+
+# 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:
+
+```bash
+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:
+```json
+{
+  "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:**
+```bash
+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:**
+```bash
+python3 scripts/generate_report.py \
+  --input scan_results.json \
+  --output reports/ \
+  --formats html,pdf,docx \
+  --template technical \
+  --exclude-false-positives
+```
+
+**Generate compliance report:**
+```bash
+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
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,45 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:diegocconsolini/ClaudeSkillCollection:security-report-builder",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "5c9c12061656cd0e7616cc0924edd19cbe2f18b6",
+    "treeHash": "8b982183b7015f35b896d4ac091714a322212e34d8fafc51d00d3ff472a77e80",
+    "generatedAt": "2025-11-28T10:16:26.847406Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "security-report-builder",
+    "description": "Professional security report generator with HTML, PDF, and DOCX output. Reduces false positives through context-aware analysis.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "960976a3f5ab00b273b9066be78ae7dd761a2a3ef3c0f1e65a0a7ac2697927ba"
+      },
+      {
+        "path": "agents/security-report-builder.md",
+        "sha256": "77298eed142b442162533d64ab66657e68e9465b9c44627b7282b09f754418c3"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "0721e318ffd31a8342a9a314eb695f1cccd03ad76112beb73ed0dd82b4d38fe5"
+      }
+    ],
+    "dirSha256": "8b982183b7015f35b896d4ac091714a322212e34d8fafc51d00d3ff472a77e80"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}