v0.6.1b - API Call Efficiency

What's Changed

Performance Optimizations

• Eliminate duplicate IPS API call: Raw IPS events are now stashed during log collection and reused for IPS analysis, avoiding a redundant HTTP round-trip per report cycle
• Run integrations once: Cloudflare WAF/DNS integrations now run once and share results between HTML and text report generation (previously ran independently for each format)
• Merge asyncio event loops: Combined two separate asyncio.run() calls into a single event loop, reducing overhead and enabling shared integration state
• Cache working IPS endpoint: Successfully discovered IPS endpoints are cached across calls, avoiding up to 7 probe requests on subsequent runs

Files Changed

File	Change
api_collector.py	Stash raw IPS events before parsing
collector.py	Propagate raw IPS events from API collector
__main__.py	Reuse stashed IPS events, single asyncio.run() with shared integrations
generator.py	Accept pre-computed integration results (backward compatible)
client.py	IPS endpoint caching with automatic invalidation

Docker

docker pull ghcr.io/trek-e/unifi-security-report:v0.6.1b

Full Changelog: v0.5.5b...v0.6.1b

v0.6.0b - Bug Fix Release

Bug Fix Release

🐛 Docker Healthcheck Fix

• Fixed: Container no longer reports unhealthy while waiting for scheduled jobs
• Health status now set to HEALTHY immediately after session starts

🔧 MongoDB IPS Report Improvements

• Threat display now shows: Blocked: 45.33.32.156 → 192.168.1.10 instead of generic labels
• Source IPs now visible in blocked threats section
• Better grouping by attacker IP address

🧪 Test Fixes

• Fixed timezone-aware datetime assertions in test_models.py
• Updated rule counts for HEALTH_RULES additions
• Fixed deprecation warning for datetime.utcnow()

📦 Full Changelog

• Docker healthcheck passes during scheduled wait periods
• MongoDB IPS alerts show meaningful IP-based information
• All 938 tests passing

v0.5.5b - MongoDB IPS Collection

What's New

MongoDB-based IPS Threat Collection via SSH

The UniFi Network API does not expose IPS/threat events through REST endpoints. This release adds a workaround that SSHs into UDM Pro devices and queries MongoDB directly for blocked threat alerts.

New Features

• SSH Key Authentication: Support for key-based SSH authentication (required for UDM Pro)
• MongoDB IPS Collector: Queries ace.alert collection for THREAT_BLOCKED_V3 documents
• Automatic Fallback: When API returns empty IPS results, automatically falls back to MongoDB collection

New Configuration Options

Variable	Description	Default
UNIFI_SSH_KEY_PATH	Path to SSH private key file	None
UNIFI_SSH_KEY_PASSPHRASE	Passphrase for encrypted key	None
UNIFI_SSH_USERNAME	SSH username	root

Setup

# Generate key pair (if needed)
ssh-keygen -t ed25519 -f ~/.ssh/unifi_key

# Copy public key to UDM Pro
cat ~/.ssh/unifi_key.pub | ssh root@192.168.1.1 "cat >> ~/.ssh/authorized_keys"

# Configure scanner
export UNIFI_SSH_KEY_PATH=~/.ssh/unifi_key

Limitations

MongoDB alerts contain limited data compared to what the UniFi UI shows:

• Available: Source IP, destination IP, severity, timestamp
• NOT available: Signature ID, signature name, threat category, protocol/port

Signature names displayed in UniFi's UI are enriched from encrypted rule databases and are not stored in MongoDB.

---

Full Changelog: v0.4.0a1...v0.5.5b

v0.3.4-alpha: Integration Infrastructure

What's New

Phase 10 introduces the integration infrastructure framework that enables optional external integrations (Cloudflare, Cybersecure) to be added in future releases.

Features

• Integration Protocol - Standard interface for all external integrations with is_configured(), validate_config(), and fetch() methods
• Failure Isolation - One integration failing does not affect others; uses asyncio.gather(return_exceptions=True) for complete isolation
• Circuit Breakers - External API failures trigger circuit breakers that fail fast and recover automatically (opens after 3 failures, resets after 60 seconds)
• Silent Skip - Integrations that are not configured are silently skipped (no errors in logs)
• Parallel Execution - Integrations run in parallel with each other for faster report generation

Technical Details

• Uses typing.Protocol for duck typing with static type checking
• pybreaker>=1.4 added for circuit breaker support
• 30-second timeout per integration to prevent blocking
• In-memory circuit breaker state (resets on service restart)

Requirements Completed

• ✅ INTG-01: Optional integrations gracefully skip if not configured
• ✅ INTG-02: Integration failure isolation
• ✅ INTG-03: Circuit breakers for external API calls

Tests

30 new tests covering Protocol contract, registry filtering, runner isolation, and circuit breaker behavior.

---

Full Changelog: v0.3.3a1...v0.3.4a1

v0.3.3-alpha: Device Health Monitoring

Device Health Monitoring

Proactive alerts about device health before failures occur.

Features

• Temperature monitoring — Warnings at 80°C, critical alerts at 90°C with remediation guidance
• PoE event detection — Disconnect and overload events with affected port identification
• Uptime tracking — Flags devices needing restart at 90+ days (warning) and 180+ days (critical)
• CPU/Memory alerts — Proactive alerts before performance degrades (CPU >80%, Memory >85%)

Report Integration

• New "Device Health Summary" section in reports
• Executive summary showing total/healthy/warning/critical device counts
• Critical issues displayed prominently with red styling
• Device status table with all monitored metrics
• Category-specific remediation guidance for all findings

API Additions

• get_devices() method on UnifiClient for stat/device endpoint
• HEALTH_RULES for PoE disconnect (MEDIUM severity) and overload (SEVERE severity)

Technical Details

• DeviceStats model parses UniFi stat/device API responses
• DeviceHealthAnalyzer with configurable thresholds via HealthThresholds dataclass
• Health analysis is optional — failures don't block report generation
• 107 new tests covering models, analyzer, rules, and integration

Requirements Complete

• HLTH-01: Temperature monitoring via stat/device polling ✓
• HLTH-02: PoE disconnect detection ✓
• HLTH-03: PoE overload/budget exceeded detection ✓
• HLTH-04: Uptime tracking and reporting ✓
• HLTH-05: CPU/memory utilization alerts ✓

Full Changelog: v0.3.2a1...v0.3.3a1

v0.3.2-alpha: Enhanced Security Analysis

Enhanced Security Analysis

Phase 8 adds IDS/IPS threat analysis with plain-English explanations and actionable remediation guidance.

Features

• Suricata signature parsing — 24 ET category mappings
• Plain English threat descriptions — "ET SCAN" → "Reconnaissance"
• Blocked vs detected separation — IPS vs IDS mode distinction
• Top threat source IP summaries — 10+ event threshold, external/internal separation
• Category-specific remediation guidance — Severity-adjusted detail levels
• Detection mode warning — Alerts when all events are detected-only

New Report Sections

• Threats Detected — With "Recommended Actions" remediation box
• Threats Blocked — No action needed (already stopped by IPS)
• Top Threat Sources — External and internal IP breakdown

Requirements Completed

• SECR-01: Suricata signature parsing
• SECR-02: Plain English explanations
• SECR-03: Blocked vs detected distinction
• SECR-04: Top source IP summaries
• SECR-05: Category-specific remediation

Docker

docker pull ghcr.io/trek-e/unifi-security-report:latest

v0.3.1-alpha: Extended Wireless Analysis

Extended Wireless Analysis

This release adds comprehensive wireless event analysis to help users understand client behavior and AP radio changes.

Features

• Client Roaming Detection (WIFI-01): Track client movement between APs with source/destination AP names
• Band Switching Detection (WIFI-02): Monitor 2.4GHz ↔ 5GHz transitions with human-readable band names
• Channel Change Detection (WIFI-03): Report AP channel changes with from/to channel numbers
• DFS Radar Detection (WIFI-04): Flag radar events as warnings with remediation guidance
• RSSI Quality Translation (WIFI-05): Convert signal strength to Excellent/Good/Fair/Poor/Very Poor
• Flapping Detection (WIFI-06): Warn when clients roam excessively (5+ times per analysis window)

Example Output

[Wireless] Client roamed from Office-AP to Lobby-AP
Signal: Good (-58 dBm)

[Wireless] Client switched from 2.4GHz to 5GHz on Conference-AP

[Wireless] AP Lobby-AP changed channel from 36 to 44

[Wireless] Client flapping detected (7 roams)

Technical Details

• New WIRELESS category in analysis rules
• 4 wireless rules in src/unifi_scanner/analysis/rules/wireless.py
• Helper functions: rssi_to_quality(), format_radio_band()
• Extended template context with wireless-specific fields
• 47 new tests for wireless analysis

Requirements Completed

• WIFI-01 through WIFI-06 (6/6)

---

Full changelog: v0.3-alpha...v0.3.1-alpha

v0.4-alpha Cybersecure Integration

Cybersecure Integration

Users with Cybersecure subscription now see enhanced threat intelligence in reports.

What's New

• ET PRO Signature Detection: IPS findings from Proofpoint ET PRO signatures (SID 2800000-2899999) are automatically identified as Cybersecure-powered
• Visual Badge: Purple "CYBERSECURE" badge appears next to threat categories detected by enhanced signatures
• Attribution Tracking: Reports track how many threats were detected by premium threat intelligence

Technical Details

• is_cybersecure computed field on IPSEvent model
• ThreatSummary includes is_cybersecure flag and cybersecure_count
• Badge renders in both "Threats Detected" and "Threats Blocked" sections

Requirements Shipped

• CYBS-01: Service detects if Cybersecure subscription is active
• CYBS-02: Service marks findings with enhanced signature coverage
• CYBS-03: Service shows Cybersecure badge on threat findings

Full Changelog

All v0.4-alpha milestones complete:

• v0.2-alpha: Production-ready containerized service (Phases 1-5)
• v0.3-alpha: State persistence (Phase 6)
• v0.3.1-alpha: Extended wireless analysis (Phase 7)
• v0.3.2-alpha: Enhanced security analysis (Phase 8)
• v0.3.3-alpha: Device health monitoring (Phase 9)
• v0.3.4-alpha: Integration infrastructure (Phase 10)
• v0.3.5-alpha: Cloudflare integration (Phase 11)
• v0.3.15-alpha: WebSocket support (Phase 13)
• v0.4-alpha: Cybersecure integration (Phase 12)

---

13 phases | 48 plans | ~11,800 lines of Python

v0.3-alpha: No Duplicate Reports

What's New

State persistence to prevent duplicate event reporting across scheduled runs.

Features

• StateManager with atomic writes (crash-safe persistence)
• Timestamp filtering in API and SSH log collectors
• Checkpoint-after-delivery pattern ensures no duplicates
• 5-minute clock skew tolerance for time drift between scanner and controller
• Configurable initial lookback via UNIFI_INITIAL_LOOKBACK_HOURS (default: 24)
• Empty report handling with confirmation message

Configuration

New environment variable:

• UNIFI_INITIAL_LOOKBACK_HOURS - Hours of history to process on first run (default: 24, max: 720)

How It Works

1. Service reads last successful run timestamp from .last_run.json
2. Only events newer than that timestamp are processed
3. State is updated only after successful delivery
4. First run (no state file) processes last 24 hours by default

Fixes

• Issue #1: Don't Send Previous Logs - events are now filtered by last successful run timestamp

---

Full Changelog: v0.2-alpha...v0.3-alpha

v0.2-Alpha

v0.2-Alpha Release

Bug fixes and improvements for UniFi OS device support.

Container Image

docker pull ghcr.io/trek-e/unifi-security-report:v0.2-alpha

What's New

CSRF Token Support

• Fixed 403 Forbidden errors on UniFi OS devices (UDM Pro, UDM SE, UCG Ultra)
• Automatically captures and includes CSRF token in API requests

Manual Report Trigger

• New --run-once flag to generate a report immediately and exit
• Useful for testing configuration and on-demand reports

docker run --rm ... ghcr.io/trek-e/unifi-security-report:latest --run-once

Configuration Improvements

• Fixed empty string handling for optional port fields
• Updated docker-compose.yml with working UDM configuration
• Uses network_mode: host for reliable UDM connectivity

Upgrade Notes

If upgrading from v0.1-alpha:

1. Pull new image: docker pull ghcr.io/trek-e/unifi-security-report:latest
2. Download updated docker-compose.yml
3. Restart: docker-compose up -d

Full Changelog

v0.1-alpha...v0.2-alpha