AmpelClip

English | Deutsch

Local-first clipboard privacy guard — traffic-light workflow to detect and anonymize sensitive text before you paste it.

AmpelClip is a local-first Windows clipboard privacy monitor. It watches clipboard text, detects sensitive patterns such as IBANs, email addresses, German phone numbers and credit-card-like numbers, and helps anonymize copied content before it is pasted elsewhere.

---

Quick Navigation

Section (EN)	Abschnitt (DE)	Description / Beschreibung
Start Here	Einstieg	Immediate workflow guide / Sofort-Startleitfaden
Target Personas	Zielgruppen	User profiles & intent / Profile & Einsatzzwecke
Why AmpelClip	Warum AmpelClip	Core value proposition / Kernnutzen
Comparative Matrix	Vergleichsmatrix	AmpelClip vs. alternatives / AmpelClip im Vergleich
System Architecture	Systemarchitektur	Topology & component model / Topologie & Komponentenmodell
Traffic-Light Lifecycle	Ampel-Lebenszyklus	Sequence diagram / Sequenzdiagramm
Installation	Installation	Python requirements & setup / Setup-Anleitung
Web Companion	Web-Companion	Local PWA companion & Node tests / Lokale PWA & Node-Tests
How It Works	Ablauf	Step-by-step workflow / Schritt-für-Schritt-Ablauf
Configuration	Konfiguration	Config files & parameters / Konfigurationsparameter
Build Executable	EXE bauen	PyInstaller compilation / PyInstaller-Kompilierung
Windows Store Readiness	Windows-Store-Readiness	Preflight & packaging status / Vorbereitungsstatus
Governance & Invariants	Governance & Invarianten	10 verified invariants / 10 verifizierte Invarianten
Sibling Ecosystem	Geschwister-Ökosystem	file-bricks desktop suite / Desktop-Werkzeugfamilie
Security Policy	Sicherheitsrichtlinie	Vulnerability disclosure & SLA / Meldewege & SLA
Search Context & SEO	Suchkontext & SEO	Discovery queries / Relevante Suchphrasen
License & Legal	Lizenz & Rechtliches	MIT license & § 521 BGB notice / MIT & § 521 BGB
Changelog	Änderungsprotokoll	Version history / Versionshistorie

---

Start Here

Need	Use
Run the desktop tool	python Ampel6.py or START.bat
Configure detection	Enable built-in regex patterns and import sensitive/whitelist terms
Review before replacing	Use yellow preview mode
Auto-anonymize clipboard text	Use green mode after checking the rules
Understand limits	Read the manual-review warning below

---

Target Personas & High-Intent Use Cases

+---------------------------------------------------------------------------------------------------+
| [PERSONA-01] Privacy-Conscious Professional / AI Prompt Operator                                  |
| Need: Intercept copied database rows, code snippets, and customer emails before pasting into     |
|       ChatGPT, Claude, or public LLM chats.                                                       |
| Solution: Background clipboard watcher instantly flags PII and anonymizes matches to [ANONYM].    |
+---------------------------------------------------------------------------------------------------+
| [PERSONA-02] Compliance & Data Protection Officer (GDPR / DSGVO)                                  |
| Need: Prevent accidental clipboard leaks of IBANs, phone numbers, or credit card digits.          |
| Solution: Zero cloud egress, 100% on-device regex matching, local audit history, no telemetry.   |
+---------------------------------------------------------------------------------------------------+
| [PERSONA-03] Technical Support Engineer & IT Administrator                                        |
| Need: Sanitize user diagnostics and ticket dumps before posting to public bug trackers.           |
| Solution: Side-by-side original vs. redacted preview in Yellow mode with single-click copy.      |
+---------------------------------------------------------------------------------------------------+
| [PERSONA-04] Everyday Windows Power User                                                          |
| Need: Lightweight, unobtrusive clipboard watchdog without heavyweight enterprise DLP software.   |
| Solution: Unprivileged RunAsInvoker execution, colored system tray status, zero background lag.   |
+---------------------------------------------------------------------------------------------------+

---

Why AmpelClip

• Traffic-light workflow: red for monitor-only, yellow for preview, green for automatic replacement.
• Clipboard-focused privacy support: useful before pasting text into documents, tickets, chat tools, LLM prompts or web forms.
• Built-in pattern detection: IBAN, email, German phone numbers, credit-card-like numbers, postal codes and dates.
• Custom lists: import sensitive terms and whitelist terms from TXT or Excel files.
• Local-first desktop app: clipboard handling stays on the local Windows machine.
• Tray integration and history: colored tray icon plus the last 15 clipboard entries.

Warning

AmpelClip is not an enterprise DLP platform and does not guarantee complete redaction. It is a helper for privacy workflows, not a substitute for manual review.

---

Comparative Matrix: AmpelClip vs. Alternatives

Comparison Dimension	AmpelClip (file-bricks)	Enterprise DLP (Symantec/Forcepoint)	Password Managers (Bitwarden/1Password)	Browser Extensions (uBlock/Privacy Badger)	Ad-hoc Manual Regex / Notepad
Zero Cloud Egress ([INV-LOCAL-01])	✅ 100% Local-First	❌ Cloud telemetry & logs	⚠️ Cloud vault sync	⚠️ Web runtime only	✅ Local manual
Privilege Model ([INV-PERM-02])	✅ RunAsInvoker (User)	❌ Kernel filter drivers	✅ User mode	✅ Sandbox	✅ User mode
Real-Time Clipboard Hook ([INV-CLIP-03])	✅ OS dataChanged Hook	✅ Enterprise hook	⚠️ Clipboard clear timer	❌ Web context only	❌ Manual paste
Traffic-Light States ([INV-MODE-04])	✅ Red / Yellow / Green	❌ Binary block / allow	❌ Static credentials	❌ URL blocking	❌ None
Regex & Whitelisting ([INV-RULE-05])	✅ Single-Pass Merger	⚠️ Complex admin policy	❌ Stored records only	❌ Network filters	⚠️ Manual find-replace
System Tray Status ([INV-TRAY-06])	✅ Dynamic Color Icon	⚠️ Hidden agent	✅ Static tray	❌ Browser only	❌ None
PWA Profile Exchange ([INV-PWA-07])	✅ Offline JSON Companion	❌ Cloud tenant only	❌ Proprietary schema	❌ Browser extension	❌ None
Store Packaging Prep ([INV-MSIX-08])	✅ MSIX Preflight Ready	❌ Custom MSI installer	✅ MSIX / WinGet	❌ Web Store only	❌ None
Open Source & Legal ([INV-LEGAL-09])	✅ MIT (§ 521 BGB)	❌ Expensive SaaS	⚠️ Freemium / Dual	✅ Open source	✅ None
48h Security SLA ([INV-SLA-10])	✅ Guaranteed 48h SLA	⚠️ Enterprise tier	✅ Tiered SLA	⚠️ Volunteer basis	❌ None

---

System Architecture

flowchart TD
    subgraph OS["Windows OS Subsystem"]
        ClipAPI["Windows Clipboard API (dataChanged Signal)"]
        TrayAPI["Windows System Tray Notification Area"]
    end

    subgraph Core["AmpelClip Desktop Core (PySide6)"]
        Listener["Clipboard Listener & Re-Entry Guard"]
        ModeEngine["Traffic-Light State Engine (Red / Yellow / Green)"]
        RegexEngine["Built-in Regex Matcher (IBAN, Mail, Phone, CC, PLZ, Date)"]
        ListEngine["Custom Wordlists (Sensitive & Whitelist Spans)"]
        Substitutor["Single-Pass Merger & [ANONYM] Substitutor"]
        History["Volatile Memory History (Max 15 Entries)"]
        ConfigMgr["Config Manager (%LOCALAPPDATA% / Local JSON)"]
    end

    subgraph Companion["Web Companion (Local PWA)"]
        PWAEngine["PWA Anonymization & Profile Editor"]
        PWAStorage["Local Storage (ampelclip-profile-v1.json)"]
    end

    ClipAPI -->|"dataChanged"| Listener
    Listener --> ModeEngine
    ModeEngine -->|"Analyze Spans"| RegexEngine
    ModeEngine -->|"Analyze Whitelists"| ListEngine
    RegexEngine --> Substitutor
    ListEngine --> Substitutor
    Substitutor -->|"Preview Only"| History
    Substitutor -->|"Auto-Replace (Green Mode)"| ClipAPI
    ModeEngine -->|"Update Color Status"| TrayAPI
    ConfigMgr -.->|"Load / Save Settings"| ModeEngine
    PWAStorage <-->|"Export / Import JSON Profile"| ConfigMgr

Loading

---

Traffic-Light Lifecycle

sequenceDiagram
    autonumber
    actor User as Windows User
    participant App as Source Application
    participant Clip as System Clipboard
    participant AC as AmpelClip Engine
    participant Tray as System Tray
    participant Dest as Destination Application

    User ->> App: Copy text (Ctrl+C)
    App ->> Clip: Store raw clipboard text
    Clip -->> AC: dataChanged event notification
    AC ->> AC: Re-entry guard check (ignore self-written text)
    AC ->> AC: Evaluate regex patterns and custom whitelists

    alt Red Mode (Monitor Only)
        AC ->> Tray: Set tray icon Red
        AC ->> AC: Append to volatile history (no text modification)
    else Yellow Mode (Preview Alert)
        AC ->> Tray: Set tray icon Yellow
        AC ->> AC: Display side-by-side original vs anonymized preview
        AC ->> AC: Await manual user confirmation
    else Green Mode (Automatic Anonymization)
        AC ->> Tray: Set tray icon Green
        AC ->> AC: Substitute sensitive spans with [ANONYM]
        AC ->> Clip: Write anonymized text to clipboard
        AC ->> AC: Register written hash in re-entry guard
    end

    User ->> Dest: Paste text (Ctrl+V)
    Clip -->> Dest: Deliver sanitized or reviewed text

Loading

---

Installation

Requirements:

• Python 3.10+
• Microsoft Windows 10 / 11

git clone https://github.com/file-bricks/AmpelClip.git
cd AmpelClip
pip install -r requirements.txt
python Ampel6.py

You can also launch the application via START.bat.

---

Web Companion

web_companion/ contains an implemented local PWA companion for editing ampelclip-profile-v1.json profiles and manually anonymizing example text in a browser. Its Node tests cover the anonymization engine, profile contracts, service worker, manifest, install hooks, and offline fallbacks:

cd web_companion
npm test

This is not a browser-based system clipboard monitor. Automated tests do not prove rendering, installation, or offline behavior on a real desktop or mobile browser; those acceptance smokes remain open.

---

How It Works

1. Choose red, yellow or green mode.
2. Enable built-in patterns and optionally import sensitive terms or whitelists.
3. Copy text as usual.
4. AmpelClip checks the clipboard content locally.
5. In yellow mode, review the original and anonymized preview.
6. In green mode, matching sensitive content is replaced with [ANONYM].

---

Configuration

Source runs save settings in the project-local config.json, which is created on first start. Frozen Store/EXE builds use %LOCALAPPDATA%\AmpelClip\config.json.

Setting	Description
builtin_patterns	Enabled and disabled built-in pattern types
ampel_status	Current traffic-light mode
case_sensitive	Case-sensitive matching
whole_words	Whole-word matching only
files	Previously imported list files

---

Build Executable

pip install pyinstaller
pyinstaller --onefile --noconsole --icon=ICO.ico --name=AmpelClip Ampel6.py

Or execute build_exe.bat for reproducible automated builds.

---

Windows Store Readiness

Store metadata, listing text, privacy/support pages and the conservative preflight live in:

• store_package.json
• STORE_LISTING.md
• PRIVACY_POLICY.md
• SUPPORT.md
• releases/windowsstore/WINDOWS_STORE_PREP.md

Run the preflight with:

python scripts/check_store_readiness.py --allow-blockers

Current local status:

• The Partner Center publisher DN is configured in the Store metadata and manifest.
• Two byte-identical MSIX copies are present in the current dirty worktree, but they are untracked, unsigned, and not owner-approved. Their presence is not a release or Store-readiness claim.
• The strict preflight exits with code 2 because a WACK XML report is missing. Its current MSIX check proves file presence only; substantive package validation is still open.
• No WACK acceptance, signing, Partner Center submission, Store approval, or release is evidenced.

The dirty-artifact decision, deterministic MSIX validation, and external WACK/submission gates are tracked separately. Do not upload or publish an artifact without explicit authorization.

---

Governance & Runtime Invariants

AmpelClip adheres to 10 strict operational invariants:

ID	Invariant Name	Scope	Operational Guarantee
[INV-LOCAL-01]	Local-First Zero Egress	Network / Telemetry	Zero outbound telemetry, zero cloud network calls. Processing is 100% on-device.
[INV-PERM-02]	Non-Elevated Execution	OS Security	Operates exclusively under standard user privileges (RunAsInvoker). No admin rights required.
[INV-CLIP-03]	Event-Driven Clipboard	OS Integration	Utilizes native Qt dataChanged signals without aggressive busy-polling loops.
[INV-MODE-04]	Traffic-Light State Model	Privacy Control	Strict three-state state machine: Red (Monitor), Yellow (Preview), Green (Auto-Replace).
[INV-RULE-05]	Deterministic Whitelisting	Redaction Engine	Whitelisted terms take absolute priority over built-in regex matching.
[INV-TRAY-06]	Dynamic Tray Indicator	User Experience	Visual color-coded tray indicator reflects live traffic-light status in real time.
[INV-MEM-07]	Volatile Clipboard History	Data Security	History is strictly held in memory, capped at 15 items, and never flushed to disk unencrypted.
[INV-PWA-08]	Offline PWA Companion	Portability	Companion profile editor runs client-side with zero external web dependencies.
[INV-MSIX-09]	Clean Store Packaging	Packaging Safety	Strict exclusion of runtime secrets (config.json, .env, credentials) via packaging gates.
[INV-SLA-10]	48h Vulnerability SLA	Maintenance	Defined security policy with guaranteed 48-hour response time for vulnerability reports.

---

Sibling Ecosystem (file-bricks & open-bricks)

AmpelClip is an integral component of the file-bricks local-first desktop productivity ecosystem:

Repository	Purpose	Integration with AmpelClip
file-bricks/ProSync	Real-time bidirectional file sync & folder pairing	Synchronizes redaction wordlists and profiles across workstations
file-bricks/FolderHome	Visual folder launcher and workspace manager	Quick-launch launcher and status dashboard for file-bricks desktop apps
file-bricks/TagFlow	Metadata-driven file tagging and classification	Tags sanitized output documents and audit logs
open-bricks/open-bricks	Architectural umbrella & open-source governance	Common security standards, licensing policy, and design language

---

Security Policy

Security reports are welcomed and handled under a strict 48-hour SLA ([INV-SLA-10]). Please consult SECURITY.md for full reporting guidelines and verified contact details.

---

Search Context & High-Intent SEO Queries

AmpelClip is engineered for privacy-conscious engineers and teams seeking a local clipboard guard:

• AmpelClip clipboard privacy monitor
• file-bricks AmpelClip
• local-first clipboard privacy tool
• Windows clipboard anonymization helper
• local clipboard anonymization PySide6
• Windows clipboard redaction helper
• privacy traffic light clipboard tool
• clipboard PII redaction desktop app
• PySide6 clipboard privacy utility

---

License & Legal

AmpelClip is open-source software licensed under the MIT License.

This project is an unpaid open-source donation. Liability is limited to intent and gross negligence (§ 521 German Civil Code / BGB). Use at your own risk. No warranty, maintenance guarantee or fitness-for-purpose is assumed.

---

Changelog

See CHANGELOG.md for detailed version history and milestone tracking.