diff --git a/CLAUDE.md b/CLAUDE.md index fcd00dc..986fa65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,11 +61,21 @@ python3 -c "import yaml; yaml.safe_load(open('configs/example-site.yaml'))" - `_get_screenshot_dir()`: Creates screenshots subdirectory - `_generate_filename()`: Generates filename for screenshot (IP_PORT.png) -3. **configs/** - YAML configuration files +3. **src/report_generator.py** - HTML report generator + - `HTMLReportGenerator` class: Generates comprehensive HTML reports from JSON scan data + - `generate_report()`: Main method to generate HTML report with summary dashboard and service details + - `_load_json_report()`: Loads and parses JSON scan report + - `_calculate_summary_stats()`: Calculates scan statistics for dashboard (IPs, ports, services, screenshots) + - `_identify_drift_alerts()`: Identifies unexpected/missing ports and services + - `_identify_security_warnings()`: Identifies security issues (expiring certs, weak TLS, self-signed certs) + - `_format_date()`: Helper to format ISO date strings + - `_format_duration()`: Helper to format scan duration + +4. **configs/** - YAML configuration files - Define scan title, sites, IPs, and expected network behavior - Each IP includes expected ping response and TCP/UDP ports -4. **output/** - JSON scan reports and screenshots +5. **output/** - JSON scan reports and screenshots - Timestamped JSON files: `scan_report_YYYYMMDD_HHMMSS.json` - Screenshot directory: `scan_report_YYYYMMDD_HHMMSS_screenshots/` - Contains actual vs. expected comparison for each IP @@ -266,6 +276,41 @@ JSON structure defined in src/scanner.py:365+. To modify: 3. Update README.md output format documentation 4. Update example output in both README.md and CLAUDE.md +### Generating HTML Reports + +**Basic usage:** +```bash +# Generate HTML report from most recent JSON scan +python3 src/report_generator.py output/scan_report_20251113_175235.json +``` + +**Custom output location:** +```bash +# Specify output filename +python3 src/report_generator.py output/scan.json reports/my_report.html +``` + +**Programmatic usage:** +```python +from src.report_generator import HTMLReportGenerator + +generator = HTMLReportGenerator('output/scan_report.json') +html_path = generator.generate_report('custom_output.html') +print(f"Report generated: {html_path}") +``` + +**Customizing the HTML template:** +- Edit `templates/report_template.html` to modify layout, colors, or content +- Template uses Jinja2 syntax with variables like `{{ title }}`, `{% for site in sites %}` +- CSS is embedded in the template for portability (single file output) +- Test design changes with `templates/report_mockup.html` first + +**Output:** +- Standalone HTML file (no external dependencies) +- Can be opened directly in any browser +- Dark theme optimized for readability +- Screenshot links are relative paths (keep output directory structure intact) + ### Customizing Screenshot Capture **Change viewport size** (src/screenshot_capture.py:35): @@ -339,53 +384,69 @@ Optimization strategies: - Adjust screenshot timeout (currently 15 seconds in src/screenshot_capture.py:34) - Disable screenshot capture for faster scans (set screenshot_capture to None) +## HTML Report Generation (✅ Implemented) + +SneakyScanner now includes comprehensive HTML report generation from JSON scan data. + +**Usage:** +```bash +# Generate HTML report from JSON scan output +python3 src/report_generator.py output/scan_report_20251113_175235.json + +# Specify custom output path +python3 src/report_generator.py output/scan.json custom_report.html +``` + +**Implemented Features:** +- ✅ Dark theme with slate/grey color scheme for easy reading +- ✅ Summary dashboard with scan statistics, drift alerts, and security warnings +- ✅ Site-by-site breakdown with IP grouping +- ✅ Service details with expandable cards (click to expand) +- ✅ Visual badges for expected vs. unexpected services (green/red/yellow) +- ✅ SSL/TLS certificate details with expandable sections +- ✅ TLS version support display with cipher suites +- ✅ Certificate expiration warnings (highlighted for <30 days) +- ✅ Weak TLS version detection (TLS 1.0/1.1) +- ✅ Self-signed certificate identification +- ✅ Screenshot links (referenced, not embedded) +- ✅ Missing expected services clearly marked +- ✅ UDP port handling: + - Expected UDP ports shown with green "Expected" badge + - Unexpected UDP ports shown with red "Unexpected" badge + - Missing expected UDP ports shown with yellow "Missing" badge + - Note displayed that service detection not available for UDP +- ✅ Responsive layout for different screen sizes +- ✅ No JavaScript dependencies - pure HTML/CSS with minimal vanilla JS +- ✅ Optimized hover effects for table rows (lighter background + blue left border) + +**Template Architecture:** +- `templates/report_template.html` - Jinja2 template for dynamic report generation +- `templates/report_mockup.html` - Static mockup for design testing +- Custom CSS with dark slate theme (#0f172a background, #60a5fa accents) +- Expandable service details and SSL/TLS sections +- Color-coded status badges (expected=green, unexpected=red, missing=yellow) + +**HTMLReportGenerator Class** (`src/report_generator.py`): +- Loads JSON scan reports +- Calculates summary statistics (IPs, ports, services, screenshots) +- Identifies drift alerts (unexpected/missing ports and services) +- Identifies security warnings (expiring certs, weak TLS, self-signed certs, high ports) +- Renders Jinja2 template with context data +- Outputs standalone HTML file (no server required) + +**Future Enhancements for HTML Reports:** +- Sortable/filterable tables with JavaScript +- Timeline view of scan history +- Scan comparison (diff between two reports) +- Export to PDF capability +- Interactive charts/graphs for trends +- Embedded screenshot thumbnails (currently links only) + ## Planned Features (Future Development) The following features are planned for future implementation: -### 1. HTML Report Generation -Build comprehensive HTML reports from JSON scan data with interactive visualizations. - -**Report Features:** -- Service details and SSL/TLS information tables -- Visual comparison of expected vs. actual results (red/green highlighting) -- Certificate expiration warnings with countdown timers -- TLS version compliance reports (highlight weak configurations) -- Embedded webpage screenshots -- Sortable/filterable tables -- Timeline view of scan history -- Export to PDF capability - -**Implementation Considerations:** -- Template engine: Jinja2 or similar -- CSS framework: Bootstrap or Tailwind for responsive design -- Charts/graphs: Chart.js or Plotly for visualizations -- Store templates in `templates/` directory -- Generate static HTML that can be opened without server - -**Architecture:** -```python -class HTMLReportGenerator: - def __init__(self, json_report_path, template_dir='templates'): - pass - - def generate_report(self, output_path): - # Parse JSON - # Render template with data - # Include screenshots - # Write HTML file - pass - - def _compare_expected_actual(self, expected, actual): - # Generate diff/comparison data - pass - - def _generate_cert_warnings(self, services): - # Identify expiring certs, weak TLS, etc. - pass -``` - -### 2. Comparison Reports (Scan Diffs) +### 1. Comparison Reports (Scan Diffs) Generate reports showing changes between scans over time. **Features:** @@ -409,18 +470,21 @@ Generate reports showing changes between scans over time. - python-libnmap==0.7.3 (nmap XML parsing) - sslyze==6.0.0 (SSL/TLS analysis) - playwright==1.40.0 (webpage screenshot capture) -- Built-in: socket, ssl, subprocess, xml.etree.ElementTree, logging +- Jinja2==3.1.2 (HTML report template engine) +- Built-in: socket, ssl, subprocess, xml.etree.ElementTree, logging, json, pathlib, datetime - System: chromium, chromium-driver (installed via Dockerfile) -### For HTML Reports, Will Need: -- Jinja2 (template engine) -- Optional: weasyprint or pdfkit for PDF export +### For Future Enhancements, May Need: +- weasyprint or pdfkit for PDF export +- Chart.js or Plotly for interactive visualizations ### Key Files to Modify for New Features: 1. **src/scanner.py** - Core scanning logic (add new phases/methods) 2. **src/screenshot_capture.py** - ✅ Implemented: Webpage screenshot capture module -3. **src/report_generator.py** - New file for HTML report generation (planned) -4. **templates/** - New directory for HTML templates (planned) +3. **src/report_generator.py** - ✅ Implemented: HTML report generation with Jinja2 templates +4. **templates/** - ✅ Implemented: Jinja2 templates for HTML reports + - `report_template.html` - Main report template with dark theme + - `report_mockup.html` - Static mockup for design testing 5. **requirements.txt** - Add new dependencies 6. **Dockerfile** - Install additional system dependencies (browsers, etc.) @@ -475,6 +539,39 @@ Generate reports showing changes between scans over time. - **Check**: System certificates up to date in container - **Solution**: This should not happen; file an issue if it does +### HTML Report Generation Issues + +**Problem**: "Template not found" error +- **Check**: Verify `templates/report_template.html` exists +- **Check**: Running script from correct directory (project root) +- **Solution**: Ensure template directory structure is intact: `templates/report_template.html` + +**Problem**: Report generated but looks broken/unstyled +- **Check**: Browser opens HTML file correctly (not viewing source) +- **Check**: CSS is embedded in template (should be in ` + +
+| Port | +Protocol | +Service | +Product | +Status | +
|---|---|---|---|---|
| 22 | +TCP | +ssh | +OpenSSH | +Expected | +
|
+
+
+
+
+
+ Product
+ OpenSSH
+
+
+ Version
+ 8.2p1 Ubuntu 4ubuntu0.5
+
+
+ OS Type
+ Linux
+
+
+ Extra Info
+ protocol 2.0
+
+ |
+ ||||
| 80 | +TCP | +http | +nginx | +Expected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+ Product
+ nginx
+
+
+ Version
+ 1.18.0 (Ubuntu)
+
+
+ Protocol
+ HTTP
+
+ |
+ ||||
| 443 | +TCP | +https | +nginx | +Expected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+
+
+ Product
+ nginx
+
+
+ Version
+ 1.18.0
+
+
+ Protocol
+ HTTPS
+
+
+
+
+
+ 🔒 SSL/TLS Details+ Click to expand ▼ +
+
+
+ Certificate Information+
+
+
+
+ Subject
+ CN=prod.example.com
+
+
+ Issuer
+ CN=Let's Encrypt Authority X3
+
+
+ Valid From
+ 2025-01-01 00:00:00 UTC
+
+
+ Valid Until
+ 2025-04-01 23:59:59 UTC
+
+
+ Days Until Expiry
+ 138 days
+
+
+ Serial Number
+ 03:AB:CD:EF:12:34:56:78
+
+
+ Subject Alternative Names (SANs)
+ prod.example.com, www.prod.example.com, api.example.com
+
+
+
+
+
+ TLS Version Support+ +
+
+
+
+ TLS 1.0
+ Not Supported
+
+
+
+
+
+ TLS 1.1
+ Not Supported
+
+
+
+
+
+ TLS 1.2
+ Supported
+
+
+
+
+ TLS 1.3
+ Supported
+
+
|
+ ||||
| 3000 | +TCP | +http | +Node.js Express | +Unexpected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+ Product
+ Node.js Express
+
+
+ Version
+ 4.18.2
+
+
+ Protocol
+ HTTP
+
+
+ ⚠️ Status
+ Not in expected ports list
+
+ |
+ ||||
| 8080 | +TCP | +http-proxy | +Tomcat | +Unexpected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+ Product
+ Apache Tomcat
+
+
+ Version
+ 9.0.65
+
+
+ Protocol
+ HTTP
+
+
+ ⚠️ Status
+ Not in expected ports list
+
+ |
+ ||||
| Port | +Protocol | +Service | +Product | +Status | +
|---|---|---|---|---|
| 22 | +TCP | +ssh | +OpenSSH | +Expected | +
|
+
+
+
+
+
+ Product
+ OpenSSH
+
+
+ Version
+ 8.9p1 Ubuntu 3ubuntu0.1
+
+
+ OS Type
+ Linux
+
+ |
+ ||||
| 443 | +TCP | +https | +Apache | +Expected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+
+
+ Product
+ Apache httpd
+
+
+ Version
+ 2.4.52
+
+
+ Protocol
+ HTTPS
+
+
+
+
+
+ 🔒 SSL/TLS Details Certificate Expiring Soon+ Click to expand ▼ +
+
+ Certificate Information+
+
+
+
+ Subject
+ CN=backup.example.com
+
+
+ Issuer
+ CN=DigiCert TLS RSA SHA256 2020 CA1
+
+
+ Valid From
+ 2024-10-15 00:00:00 UTC
+
+
+ Valid Until
+ 2025-11-29 23:59:59 UTC
+
+
+ Days Until Expiry
+ 15 days ⚠️
+
+
+ Serial Number
+ 09:FE:DC:BA:98:76:54:32
+
+
+ Subject Alternative Names (SANs)
+ backup.example.com
+
+
+
+
+ TLS Version Support+ +
+
+
+
+ TLS 1.0
+ Supported (Weak) ⚠️
+
+
+
+
+
+ TLS 1.2
+ Supported
+
+
+
+
+ TLS 1.3
+ Not Supported
+
+ |
+ ||||
| 53 | +UDP | +domain | +ISC BIND | +Expected | +
|
+
+
+
+
+
+ Product
+ ISC BIND
+
+
+ Version
+ 9.16.1-Ubuntu
+
+
+ Service Type
+ DNS Server
+
+ |
+ ||||
| Port | +Protocol | +Service | +Product | +Status | +
|---|---|---|---|---|
| 22 | +TCP | +ssh | +OpenSSH | +Expected | +
|
+
+
+
+
+
+ Product
+ OpenSSH
+
+
+ Version
+ 8.2p1
+
+ |
+ ||||
| 443 | +TCP | +❌ Expected but not found | +Missing | +|
| Port | +Protocol | +Service | +Product | +Status | +
|---|---|---|---|---|
| 22 | +TCP | +ssh | +OpenSSH | +Expected | +
|
+
+
+
+
+
+ Product
+ OpenSSH
+
+
+ Version
+ 8.4p1 Debian 5+deb11u1
+
+ |
+ ||||
| 8006 | +TCP | +https | +Proxmox VE | +Expected | +
|
+
+
+
+
+
+ 🖼️ View Screenshot
+
+
+
+
+ Product
+ Proxmox Virtual Environment
+
+
+ Version
+ 7.4-1
+
+
+ Protocol
+ HTTPS
+
+
+ Service Type
+ Virtualization Management
+
+
+
+
+
+ 🔒 SSL/TLS Details Self-Signed Certificate+ Click to expand ▼ +
+
+ Certificate Information+
+
+
+
+ Subject
+ CN=proxmox.local
+
+
+ Issuer
+ CN=proxmox.local (Self-Signed)
+
+
+ Valid From
+ 2024-01-10 12:00:00 UTC
+
+
+ Valid Until
+ 2034-01-08 12:00:00 UTC
+
+
+ Days Until Expiry
+ 3342 days
+
+
+ Serial Number
+ 01:23:45:67:89:AB:CD:EF
+
+
+
+ TLS Version Support+ +
+
+
+
+ TLS 1.0
+ Not Supported
+
+
+
+
+
+ TLS 1.1
+ Not Supported
+
+
+
+
+
+ TLS 1.2
+ Supported
+
+
+
+
+ TLS 1.3
+ Supported
+
+
|
+ ||||
| Port | +Protocol | +Service | +Product | +Status | +
|---|---|---|---|---|
| 22 | +TCP | +ssh | +OpenSSH | +Expected | +
|
+
+
+
+
+
+ Product
+ OpenSSH
+
+
+ Version
+ 8.9p1 Ubuntu 3ubuntu0.6
+
+ |
+ ||||
| 5432 | +TCP | +postgresql | +PostgreSQL | +Expected | +
|
+
+
+
+
+
+ Product
+ PostgreSQL DB
+
+
+ Version
+ 14.7
+
+
+ Extra Info
+ Debian 14.7-1.pgdg110+1
+
+
+ OS Type
+ Linux
+
+ |
+ ||||
| 6379 | +TCP | +redis | +Redis | +Expected | +
|
+
+
+
+
+
+ Product
+ Redis key-value store
+
+
+ Version
+ 7.0.8
+
+
+ Extra Info
+ 64-bit
+
+ |
+ ||||