Documentation - Alert KB Review Hub

📖 Full Catalog

Project Overview

A self-hosted alert review tool for MSPs to review 343 MDR alerts with team collaboration and automatic Airtable sync.

Work Phases

🎯 Phase 1: Foundation & Core Features

Status: ✅ Complete

Built a functional alert review tool with localStorage sync and Airtable integration. 343 alerts with before/after diffs, team feedback, filtering, and review tracking.

🐛 Phase 2: Emoji Encoding Fixes

Status: ✅ Complete

Fixed garbled emoji characters by converting from UTF-8 to HTML entities. Ensures reliable rendering across all browsers and file encoding scenarios.

🎨 Phase 3: UX Improvements

Status: ✅ Complete

Enhanced visual hierarchy with vibrant colors, clear "Changes:" labels, improved button styling with hover effects, and better visual connection between filters and alert badges.

📋 Phase 4: Documentation

Status: ✅ Complete

Created comprehensive documentation (SUMMARY, ALERT_IMPROVEMENTS, CHANGES) and maintenance protocols for future development.

Current Features

View 343 alert diffs with before/after changes
Local review persistence (browser localStorage)
Airtable auto-sync (5-second polling)
Team feedback display with timestamps
Search & filter by ID, title, cluster, change type
Mark reviews as Approved / Needs Review / Flagged
Add notes to each review
Dark mode support
Responsive design

Technical Stack

Hosting: Netlify (auto-deploys from GitHub)
Frontend: Single HTML file with embedded JavaScript/CSS
Storage: Browser localStorage + Airtable cloud sync
Framework: Vanilla JavaScript (no build step)

Alert Improvements by Group

Documentation of improvements made to the 343 MDR alerts organized by cluster/group.

Improvement Summary

Group	Alerts	Focus	Status
Worst-first gaps	12	Source-specific remediation improvements	✅
Generic boilerplate	42	Core alert remediation rewrite	✅
Cross-vendor duplicates	15	Differentiate duplicate-title families	✅
Identity & Access	~87	Cluster-wide review & standardization	✅
Windows/Sysmon	~128	Event log cluster review	✅
Network/Perimeter	~74	MITRE ATT&CK reference backfill	✅
Email & SaaS	~47	Collaboration cluster review	✅
EDR & Misc	~26	Long-tail endpoint detection cleanup	✅
Data hygiene	~106	Source field standardization	✅
MITRE validation	All 343	Validate all IDs against live STIX	✅

Quality Improvements

Remediation: From generic → specific, actionable guidance
References: From incomplete → comprehensive MITRE mapping
Sources: From blank/inconsistent → standardized attribution
Consistency: From ad-hoc → cluster-wide standards
Clarity: From confusing duplicates → well-differentiated alerts

By the Numbers

343 alerts reviewed and improved
42 alerts with generic remediation completely rewritten
87 alerts in Identity cluster standardized
128 alerts in Windows cluster reviewed and aligned
74 alerts with MITRE references backfilled
106 alerts with source field standardized
15 alert families disambiguated
343 alerts MITRE validated against live STIX data

Technical Changelog

Complete record of all changes made to the alert review tool, including design decisions and rationale.

Recent Changes

Emoji Encoding Fixes

Fixed garbled emoji characters by converting from literal UTF-8 to HTML entities. Ensures reliable rendering across browsers and file encoding issues.

Entities used: ✓ (✓) ⚠ (⚠) ✕ (✕) 👤 (👤) · (·) ▶ (▶)

Change-Type Badge Colors

Upgraded from muted pastels to vibrant semantic colors using CSS variables. Better visibility and dark mode support.

Colors: Remediation (green) | References (cyan) | Source (yellow) | Triggers (red)

Filter & Label Improvements

Added "CHANGES:" labels and improved button styling with borders, rounded corners, and hover effects. Creates clear visual connection between filters and alert badges.

Documentation System

Created three complementary documentation files (SUMMARY, ALERT_IMPROVEMENTS, CHANGES) and self-hosted documentation viewer. Enables future AI assistants to understand design constraints and avoid breaking changes.

Design Principles for Future Changes

Always use HTML entities for emoji — Never use literal characters (survives encoding issues)
Keep all colors in CSS variables — For consistent theming and dark mode support
Use semantic colors — success/warning/critical for meaning, not just decoration
Match styling between related elements — Filters ↔ badges should look like the same control family
Test in both light and dark modes — Before deployment
Check browser console for errors — F12 DevTools before pushing

Maintenance Commitment

Important: Always update CHANGES.md when making changes to this project. This documentation serves as a reference for future developers and AI assistants to understand the reasoning behind each decision.