docs: rewrite README and user guide for v2.0.0, add MIT LICENSE

README.md:
- Rewrite features section with all v2.0 capabilities (approval
  workflows, version control, daily limits, Control Panel)
- Update quick start with Docker demo and 3 install methods
- Add post-installation setup guide (roles, rule mapping, limits)
- Update architecture section with current file layout
- Fix markdown lint warnings (headings, blank lines, code fences)

Whitelist_Manager_Documentation.md:
- Add approval workflows section (gates, submissions, notifications)
- Add Control Panel documentation (queue, usage, limits tabs)
- Add version control and revert documentation
- Add Splunk Admin Installation Guide section (index, roles, mapping)
- Update role table with v2.0 roles (wl_admin, wl_analyst_editor,
  wl_analyst_viewer)
- Add daily usage limits and bulk edit documentation
- Update FAQ with approval, locking, and concurrent edit questions

LICENSE:
- Add MIT License file

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: wildleo91

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Security Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,203 +1,214 @@
-# Splunk Whitelist Manager
+# Whitelist Manager for Splunk
 
-## Overview
+Manage detection-rule CSV whitelists through a web UI with inline editing, approval workflows, version control, and a full diff-based audit trail.
 
-The Splunk Whitelist Manager is a comprehensive, user-friendly Splunk application designed to streamline the management of detection rule whitelists across your security operations. This application enables security teams to efficiently review, approve, and manage whitelist entries for critical detection rules without requiring direct access to lookup files or advanced Splunk configuration knowledge.
-
-Built with an intuitive web interface, role-based access controls, and comprehensive audit logging, the Whitelist Manager reduces operational friction while maintaining security and compliance requirements. Teams can quickly respond to false positives, manage exceptions, and track all whitelist changes through a centralized dashboard.
+Built for SOC teams who need to manage detection rule exceptions without touching raw CSV files or Splunk configs.
 
 ## Features
 
-- **Multi-Rule Support**: Manage whitelists for 16+ detection rules including data exfiltration, brute force, privilege escalation, and more
-- **Web-Based Interface**: Intuitive dashboard for viewing, filtering, and managing whitelist entries
-- **Role-Based Access Control**: Assign permissions to managers, approvers, and viewers for controlled access
-- **Audit Trail**: Complete logging of all whitelist modifications with user attribution and timestamps
-- **Bulk Operations**: Add, remove, or modify multiple whitelist entries efficiently
-- **CSV Lookup Integration**: Seamless integration with Splunk lookup files for real-time whitelist application
-- **Search Integration**: View whitelist status directly in detection rule searches
-- **Flexible Rule Mapping**: Customizable configuration to add new detection rules
+### Core Editing
 
-## Prerequisites
+- Inline cell editing with change tracking (before/after diffs)
+- Add, remove, and bulk-edit rows with required comments
+- Add and remove columns
+- Row drag-and-drop reordering
+- CSV import/export
+- Search and filter rows
+- Dark and light theme support
 
-- Splunk Enterprise 7.3 or higher (8.x and 9.x recommended)
-- Admin access to Splunk instance for app installation
-- Available disk space for lookup files and audit logs
-- Network access to the Splunk web interface
+### Approval Workflows
 
-## Installation
+- Configurable thresholds trigger admin approval for bulk operations
+- Daily usage limits per analyst (row removals, edits, additions, reverts)
+- Admins approve/reject/cancel requests from the Control Panel
+- Self-approval prevention — submitter cannot approve their own request
 
-### Method 1: Via Splunk Web UI (Recommended)
+### Version Control
 
-1. Download the latest package from the Releases page
-2. Log in to Splunk as an admin
-3. Navigate to Manage Apps and select Install app from file
-4. Click Choose File and select the wl_manager-1.0.0.spl package
-5. Click Upload app and wait for installation to complete
-6. Restart Splunk when prompted
+- Every save creates a timestamped snapshot (last 6 versions retained)
+- Revert to any previous version with full audit trail
+- Optimistic locking — concurrent edits detected via file mtime
 
-### Method 2: Via Splunk CLI
+### Audit Trail
 
-bash
-/opt/splunk/bin/splunk install app wl_manager-1.0.0.spl -auth admin:password
-bash
+- Every change logged to a dedicated `wl_audit` Splunk index
+- Diff-based events: added, removed, edited, revert, auto-removed
+- Per-field before/after values for edits
+- Dashboard with summary stats, filters by analyst/rule/action/time
+- Expiring-soon panel for proactive review
 
-Replace 'admin:password' with your actual credentials.
+### Security
 
-### Method 3: Manual Installation
+- Role-based access control: `wl_admin`, `wl_analyst_editor`, `wl_analyst_viewer`
+- Server-side RBAC enforcement on every request
+- Path traversal protection, input sanitization, rate limiting
+- Control Panel restricted to admin roles
 
-1. Extract the app package: tar -xzf wl_manager-1.0.0.spl
-2. Copy to Splunk apps directory: cp -r wl_manager SPLUNK_HOME/etc/apps/
-3. Set proper permissions: chown -R splunk:splunk SPLUNK_HOME/etc/apps/wl_manager
-4. Restart Splunk: SPLUNK_HOME/bin/splunk restart
+### Row Expiration
 
-## Configuration
+- Set expiration dates with presets (7d, 30d, 6mo, 1yr) or custom date/time
+- Expired rows auto-removed on CSV load and via hourly scheduled cleanup
+- Expiring-soon alerts in the Audit Trail dashboard
 
-### 1. Map Detection Rules
+## Quick Start
 
-Edit the rule_csv_map.csv file to define which detection rules use which lookup files:
+### Docker Demo (Try Before Installing)
 
-- Location: lookups/rule_csv_map.csv
-- Format: rule_name,csv_lookup_file,description
-- Example: DR20_whitelist,DR20_whitelist.csv,DNS Tunneling Detection
+```bash
+# Clone and start
+git clone https://github.com/RelativisticJet/wl_manager.git
+cd wl_manager
+docker compose up -d
 
-### 2. Assign User Roles and Capabilities
+# Wait ~90 seconds for Splunk to start, then open:
+# http://localhost:8000  (admin / Chang3d!)
+```
 
-The app includes custom roles for access control:
+Navigate to **Apps > Whitelist Manager** to start using the app.
 
-- wl_manager_admin: Full access to manage all whitelists and settings
-- wl_manager_approver: Can approve whitelist changes
-- wl_manager_user: Can view and submit whitelist change requests
+### Install on Existing Splunk
 
-Assign roles in Settings menu or through your identity provider.
+Download the latest `.spl` from the [Releases](https://github.com/RelativisticJet/wl_manager/releases) page.
 
-### 3. Verify Index Configuration
+**Option A — Splunk Web UI:**
 
-Ensure that your Splunk instance has an index for audit logs:
+1. Go to **Apps > Manage Apps > Install app from file**
+2. Upload `wl_manager-2.0.0.spl`
+3. Restart Splunk when prompted
 
-1. Go to Settings and select Indexes
-2. Verify audit index exists (default Splunk index)
-3. The Whitelist Manager logs changes to the audit index automatically
+**Option B — CLI:**
 
-## Usage
+```bash
+$SPLUNK_HOME/bin/splunk install app wl_manager-2.0.0.spl
+$SPLUNK_HOME/bin/splunk restart
+```
 
-### Accessing the Application
+**Option C — Manual:**
 
-1. Log in to your Splunk instance
-2. In the app picker, select Whitelist Manager
-3. You will see the main dashboard with available detection rules
+```bash
+tar -xzf wl_manager-2.0.0.spl -C $SPLUNK_HOME/etc/apps/
+chown -R splunk:splunk $SPLUNK_HOME/etc/apps/wl_manager
+$SPLUNK_HOME/bin/splunk restart
+```
 
-### Managing Whitelists
+## Post-Installation Setup
 
-View Whitelist Entries:
-- Select a detection rule from the dropdown
-- Current whitelist entries display in a table
-- Use filters to search for specific entries
+### 1. Create User Roles
 
-Add Whitelist Entry:
-- Click Add Entry button
-- Fill in required fields (varies by rule type)
-- Click Save to add the entry
+The app ships with three roles in `authorize.conf`. Assign them to your users via **Settings > Access Controls > Roles**:
 
-Remove Whitelist Entry:
-- Click the delete icon next to an entry
-- Confirm deletion when prompted
-- Change is logged and applied immediately
+| Role | Can View | Can Edit | Control Panel | Inherits |
+|------|----------|----------|---------------|----------|
+| `wl_admin` | Yes | Yes | Yes | `power` |
+| `wl_analyst_editor` | Yes | Yes | No | `power` |
+| `wl_analyst_viewer` | Yes | No | No | `user` |
 
-### Checking Audit Trail
+Legacy roles `wl_editor` and `wl_viewer` are supported for backward compatibility.
 
-Navigate to the Audit Trail tab to:
-- View all whitelist changes with timestamps
-- See which user made each change
-- Review the action taken (add, remove, modify)
-- Track entry details that were modified
-- Export audit logs for compliance reporting
+### 2. Map Your Detection Rules
 
-## Architecture
+Edit `lookups/rule_csv_map.csv` to map your detection rules to CSV lookup files:
 
-The Whitelist Manager consists of several key components:
+```csv
+rule_name,csv_file,app_context
+DR20_malicious_command,DR20_whitelist.csv,wl_manager
+DR55_brute_force_login,DR55_brute_force_users.csv,wl_manager
+```
 
-### CSV Lookup Files
-- Rule-specific CSV files in the lookups/ directory
-- Format: CSV with whitelist entries
-- Updated in real-time by the backend handler
+- `rule_name` — display name in the Detection Rule dropdown
+- `csv_file` — the CSV lookup file in the app's `lookups/` directory
+- `app_context` — the Splunk app containing the CSV (usually `wl_manager`)
 
-### Web Interface
-- React-based front-end for intuitive user experience
-- Located in appserver/static/
-- Dashboard, control panel, and audit trail views
+The app ships with 18 sample detection rules. Replace or extend these with your own.
 
-### Backend Handler
-- Python script (bin/wl_handler.py) processes whitelist changes
-- Updates CSV lookup files
-- Logs all operations to audit index
-- Enforces role-based permissions
+### 3. Verify the Audit Index
 
-### Configuration Files
-- app.conf: App metadata and version info
-- restmap.conf: REST API endpoint definitions
-- authorize.conf: Role-based access control rules
-- props.conf: Lookup file properties
-- rule_csv_map.csv: Detection rule to lookup file mappings
+The app creates a `wl_audit` index automatically via `indexes.conf`. Verify it exists:
 
-## Development
+```spl
+| eventcount index=wl_audit
+```
 
-### Building the App
+### 4. Configure Daily Limits (Optional)
 
-To build a deployable package from source:
+Admins can configure per-analyst daily limits from the **Control Panel > Limits & Permissions** tab:
 
-bash
-./scripts/package.sh
-bash
+- Row additions, removals, edits (default: 10/day each)
+- Column additions and removals (default: 2/day each)
+- Reverts (default: 3/day)
+- Approval thresholds for bulk operations (default: 3+ rows)
 
-Output: dist/wl_manager-VERSION.spl
+## Architecture
 
-### Testing
+```text
+wl_manager/
+  bin/wl_handler.py              # REST handler (all server logic)
+  appserver/static/
+    whitelist_manager.js          # Main dashboard controller
+    whitelist_manager.css         # Styles (dark/light theme)
+    control_panel.js              # Admin Control Panel
+    notifications.js              # Approval notification system
+  default/
+    app.conf                      # App metadata
+    restmap.conf                  # REST endpoint config
+    authorize.conf                # RBAC role definitions
+    indexes.conf                  # wl_audit index
+    savedsearches.conf            # Expiration alert
+    data/ui/views/
+      whitelist_manager.xml       # Main dashboard
+      audit.xml                   # Audit trail dashboard
+      control_panel.xml           # Admin panel
+  lookups/
+    rule_csv_map.csv              # Detection rule -> CSV mapping
+```
+
+### How It Works
+
+1. **Frontend** (JavaScript + jQuery) builds the entire UI dynamically inside Splunk SimpleXML panels
+2. **Backend** (`wl_handler.py`) is a `PersistentServerConnectionApplication` handling GET/POST at `/custom/wl_manager`
+3. **Diff engine** uses similarity-based matching to correctly detect edits even when rows are simultaneously removed
+4. **Audit events** are written directly to the `wl_audit` index via Splunk's REST API
+5. **Version snapshots** are stored in `lookups/_versions/` with a JSON manifest
 
-Validate the app package:
+## Development
 
-bash
-./scripts/validate.sh
-bash
+### Prerequisites
 
-Run integration tests:
+- Docker and Docker Compose
+- Git Bash (Windows) or any Unix shell
+- Python 3.9+ (for validation)
 
-bash
-pytest tests/ -v
-bash
+### Development Workflow
 
-### Modifying Detection Rules
+```bash
+# Start dev environment
+make docker-up
+make docker-wait
 
-To add a new detection rule to the Whitelist Manager:
+# After code changes
+make validate         # Run AppInspect-style checks
+make test             # Run integration tests
 
-1. Create a new CSV lookup file in lookups/ directory
-2. Define column structure matching your rule requirements
-3. Add entry to lookups/rule_csv_map.csv
-4. Update bin/wl_handler.py if new field types needed
-5. Rebuild and test the app package
+# Build release package
+make package          # Outputs dist/wl_manager-VERSION.spl
+```
 
-## Troubleshooting
+### Adding a New Detection Rule
 
-### App Not Appearing in App Picker
-- Check app is installed in Manage Apps
-- Verify app.conf is properly formatted
-- Restart Splunk and clear browser cache
+1. Create a CSV file in `lookups/` with your column headers
+2. Add a row to `lookups/rule_csv_map.csv`
+3. The new rule appears in the dashboard dropdown immediately (no code changes needed)
 
-### Whitelist Changes Not Applying
-- Verify the backend handler has proper permissions
-- Check Splunk logs for Python errors in bin/wl_handler.py
-- Ensure lookup file path in rule_csv_map.csv is correct
-- Verify detection rule references the correct lookup file
+## Requirements
 
-### Permission Denied Errors
-- Ensure user has appropriate wl_manager role assigned
-- Check authorize.conf for correct role definitions
-- Verify REST API endpoint permissions in restmap.conf
+- Splunk Enterprise 8.x or 9.x (tested on 9.3.1)
+- Python 3 (bundled with Splunk 8+)
+- ~10 MB disk space for the app + audit data
 
-### Contact Support
+## License
 
-For additional issues, check the documentation or open an issue on GitHub repository.
+MIT License. See [LICENSE](LICENSE) for details.
 
-## License and Support
+## Contributing
 
-This application is provided as-is for use within your organization.
-For support, questions, or contributions, please contact your team lead.
+Issues and pull requests welcome at [github.com/RelativisticJet/wl_manager](https://github.com/RelativisticJet/wl_manager).