sneakygeek/SneakyScan
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add HTML report generation with dark theme

Browse Source 
Implements comprehensive HTML report generation from JSON scan data with Jinja2 templates. Reports feature a dark slate theme with summary dashboard, drift alerts, security warnings, and expandable service details.

Features:
- Dark theme HTML reports with slate/grey color scheme
- Summary dashboard: scan statistics, drift alerts, security warnings
- Site-by-site breakdown with IP grouping and status badges
- Expandable service details and SSL/TLS certificate information
- Visual badges: green (expected), red (unexpected), yellow (missing)
- UDP port handling: shows expected, unexpected, and missing UDP ports
- Screenshot links with relative paths for portability
- Optimized hover effects for table rows
- Standalone HTML output (no external dependencies)

Technical changes:
- Added src/report_generator.py: HTMLReportGenerator class with summary calculations
- Added templates/report_template.html: Jinja2 template for dynamic reports
- Added templates/report_mockup.html: Static mockup for design testing
- Updated requirements.txt: Added Jinja2==3.1.2
- Updated README.md: Added HTML report generation section with usage and features
- Updated CLAUDE.md: Added implementation details, usage guide, and troubleshooting

Usage:
  python3 src/report_generator.py output/scan_report.json

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phillip Tarrant
2025-11-14 01:43:59 +00:00
parent 61cc24f8d2
commit d390c4b491
6 changed files with 2933 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
CLAUDE.md
View File

@@ -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 `<style>` tags)
- **Solution**: Try different browser (Chrome, Firefox, Edge)
**Problem**: UDP ports not showing in report
- **Check**: JSON report contains UDP port data in `actual.udp_ports`
- **Solution**: Regenerate report with updated template (template was fixed to show UDP ports)
- **Note**: Expected behavior - UDP ports show with note that service detection unavailable
**Problem**: Screenshot links broken in HTML report
- **Check**: Screenshot directory exists in same parent directory as HTML file
- **Check**: Screenshot paths in JSON are relative (not absolute)
- **Solution**: Keep HTML report and screenshot directory together (don't move HTML file alone)
- **Example**: If HTML is at `output/scan_report.html`, screenshots should be at `output/scan_report_screenshots/`
**Problem**: "Invalid JSON" error when generating report
- **Check**: JSON report file is valid: `python3 -m json.tool output/scan_report.json`
- **Check**: JSON file not truncated or corrupted
- **Solution**: Re-run scan to generate fresh JSON report
**Problem**: Expandable sections not working (click doesn't expand)
- **Check**: JavaScript is enabled in browser
- **Check**: Browser console for JavaScript errors (F12 → Console)
- **Solution**: This indicates template corruption; re-generate from `templates/report_template.html`
### Nmap/Masscan Issues
**Problem**: No ports discovered