Read-only evidence capture for any web-based control system.
Whistleblower logs into your building automation system (BAS), SCADA, or other web-based operational dashboard, captures screenshots and visible page data, and saves timestamped evidence locally.
Perfect for: Documenting what operators actually see, catching UI inconsistencies, and creating audit trails.
100% Read-only. No control actions, no vendor lock-in, no cloud required.
Whistleblower was built around a simple idea: before teams automate, analyze, or optimize building data, they should verify that the operator-facing view is accurate.
In real systems, graphics drift, labels get out of sync, trends freeze, and integrations can make those issues harder to detect. When that happens, teams can end up making decisions from a view of the system that looks credible but does not fully match reality.
Whistleblower creates a practical validation step at the presentation layer so teams can confirm what operators actually see before relying on that data for analytics, AI, reporting, or operational decisions.
Read more: Why presentation-layer validation matters →
Whistleblower is designed to be that first integrity check: capture the presentation layer first, then build analytics and decision-making on a stronger foundation.
Download the desktop application - No Python or coding required!
- 📥 Download Whistleblower for Windows (47 MB)
- Extract the ZIP file
- FIRST TIME ONLY: Go into the
Whistleblowerfolder and runinstall-browsers.bat(installs Playwright browsers) - After browsers install, launch
Whistleblower.exe - Click "More info" → "Run anyway" if Windows warns you (this is normal for unsigned apps)
- 📥 Download Whistleblower for macOS (50 MB)
- Open the DMG file and drag to Applications
- Right-click the app → "Open" → "Open" again (first time only)
What you'll be able to do:
- ✅ Record login flows to your system (Bootstrap)
- ✅ Capture screenshots and data automatically
- ✅ Schedule regular captures (every 15 minutes, hourly, etc.)
- ✅ Analyze captures with AI (requires API key - see below)
The main program in this repo is the Tkinter desktop app:
python3 tkinter_ui_refactored.pyIf you prefer the helper launcher, use:
./RUN-APP.shTo get AI-powered analysis of your captures (detects anomalies, reads values, identifies issues), you'll need an API key from OpenAI or another provider.
Getting an API Key (5 minutes):
-
OpenAI (Recommended for beginners):
- Visit: https://platform.openai.com/api-keys
- Sign up for an account (requires payment method)
- Click "Create new secret key"
- Copy the key (starts with
sk-...) - Paste it into Whistleblower's "Analysis API Key" field
- Cost: ~$0.01-0.05 per screenshot analyzed (very affordable)
-
Alternative: xAI/Grok:
- Visit: https://console.x.ai/
- Follow similar steps to get your API key
Without an API key: You can still capture screenshots and data - you just won't get automated analysis reports.
📖 New to APIs? See our API Key Guide for step-by-step instructions with screenshots.
Configure your API keys and settings in the Setup tab
Captures Evidence:
- Automatically logs into your BAS/SCADA web interface
- Navigates to your dashboards and graphics
- Takes full-page screenshots
- Extracts visible data and element states
- Saves everything locally with timestamps
AI Analysis (with API key):
- Reads sensor values from screenshots
- Detects anomalies and unusual states
- Identifies potential issues
- Creates easy-to-read reports
Example AI analysis report showing loading status and potential issues
🎭 AI Analysis Personalities (Advanced):
Get specialized analysis from different professional perspectives! Enable one or more "personalities" to analyze your captures:
- BoilerBob (Mechanical Authority) - Examines mechanical equipment, pumps, boilers, chillers, and system status
- ConservationCasey (Energy Specialist) - Identifies energy waste, inefficiencies, and cost-saving opportunities
- DirectorDave (ROI Strategist) - Develops ROI models, calculates payback periods, and prioritizes improvements
- GraphicalGary (UI Standards) - Reviews interface consistency, usability, and graphical standards compliance
Enable specialist AI personalities for targeted analysis of your building systems
You can also ask custom questions like "What's the supply air temperature trend?" or "Are any pumps running in alarm?"
What it does NOT do:
- ❌ No setpoint changes or control actions (100% read-only)
- ❌ No vendor-specific protocols or APIs
- ❌ No cloud storage (everything stays local)
- ❌ No automatic alerts (yet)
Whistleblower works with any web-based control system. We provide ready-to-use templates for:
| Vendor | System | Status |
|---|---|---|
| Tridium | Niagara | ✅ Tested |
| Generic | React/SPA Systems | ✅ Tested |
| Any Custom | Web-based systems | ✅ Use Bootstrap Recorder |
📖 Full vendor list: Supported Systems Guide
Want to run from source or customize? You'll need Python 3.12+.
Click to expand developer setup
git clone https://github.com/makeitworkok/Whistleblower.git
cd Whistleblower
python3 -m pip install -r requirements.txt
python3 -m playwright install chromium# Use the main desktop app
python3 tkinter_ui_refactored.py
# Or run from command line
python3 whistleblower.py --config sites/example.json- CLI Guide - Command-line usage, analysis setup, advanced options
- Configuration Guide - Creating site configs, templates, credentials
- React/SPA Systems - Working with modern web frameworks
- Testing Guide - Validating configurations and running tests
- Build Guide - Creating Windows/macOS executables
After each run, you'll find timestamped folders with all the evidence:
data/
└── my-building/
└── 20260220-143000/ # Timestamp: Feb 20, 2026 at 2:30 PM
├── main_dashboard/
│ ├── screenshot.png # Full screenshot
│ ├── dom.json # Text and data from page
│ ├── meta.json # Run details
│ └── analysis.md # AI analysis (if you have API key)
└── hvac_graphics/
└── ...
Everything stays on your computer. Nothing is uploaded unless you explicitly run analysis.
Read-Only Access: Configure your BAS account with read-only permissions only. Never give Whistleblower control or override rights.
Stop Recording Correctly: Always use the app's Stop Capture button to end a recording. Do not close the browser window directly, as this can produce incomplete or corrupted output. See User Manual for details.
Unsigned Applications: The desktop apps are not code-signed (this is an open-source educational project). Your OS will warn you the first time - this is normal and safe.
API Costs: If using AI analysis, OpenAI charges ~$0.01-0.05 per screenshot. Monitor your usage at platform.openai.com.
- User Manual - Step-by-step what to do after launching the app
- Desktop App User Guide - Using the Windows/macOS applications
- Configuration Guide - Setting up your first system
- Supported Systems - Vendor templates and examples
- CLI Guide - Command-line usage and automation
- React/SPA Systems - Modern web frameworks (React, Vue, Angular)
- Testing & Validation - Test configs before deployment
- Build from Source - Create your own executables
Questions or issues? Open an issue on GitHub
Want to contribute? Pull requests are welcome! See CODE_OF_CONDUCT.md
Whistleblower is released under the MIT License.
You are free to use, modify, and distribute this software for any purpose, including commercial use, without restriction. See LICENSE for the full license text.
Contributions welcome.
