🛡️ ClipGuard

ClipGuard is a lightweight, privacy-focused system tray application for Linux that automatically masks sensitive information in your clipboard. Protect your privacy when copying and pasting emails, phone numbers, credit cards, IP addresses, and more.

✨ Features

🔒 Automatic Sensitive Data Masking

Email addresses → [REDACTED_EMAIL]
Phone numbers (US format) → [REDACTED_PHONE]
IPv4 addresses → [REDACTED_IP]
Credit card numbers → [REDACTED_CC]
Social Security Numbers → [REDACTED_SSN]

🧠 Smart Detection

ClipGuard only masks sensitive data when it's part of larger text. If you copy just an email address alone, it won't be masked—we assume you copied it intentionally.

🔗 Link Cleaning

Remove tracking parameters and unwrap redirectors:

Strips utm_*, fbclid, gclid, mc_eid, igshid
Unwraps Google and Facebook redirectors
Converts AMP URLs to canonical form

⚙️ Fully Customizable

Enable/disable any built-in rule
Add custom regex patterns for your specific needs
Settings saved to ~/.config/clipguard/settings.json

🔄 Restore Original Content

Made a mistake? Use "Restore Last Content" to get back the unmasked text anytime.

🎨 Beautiful Modern UI

Clean, professional interface with emoji icons
Tabbed settings dialog with built-in help
Smart notifications with content previews
Tooltips on every element

🚀 Installation

Prerequisites

All distributions require:

Python 3.7+
xclip or xsel (for clipboard access)

📦 Debian / Ubuntu / Linux Mint / Pop!_OS

# Install system dependencies
sudo apt update
sudo apt install python3 python3-pip python3-venv xclip git

# Clone the repository
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Run ClipGuard
./run.sh

Optional: Add to autostart

mkdir -p ~/.config/autostart
cp clipguard.desktop ~/.config/autostart/

📦 Fedora / RHEL / CentOS

# Install system dependencies
sudo dnf install python3 python3-pip xclip git

# Clone the repository
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Run ClipGuard
./run.sh

Auto-start on Login (Fedora/RHEL):

mkdir -p ~/.config/autostart
cp clipguard.desktop ~/.config/autostart/

📦 Arch Linux / Manjaro

# Install system dependencies
sudo pacman -S python python-pip xclip git

# Clone the repository
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Run ClipGuard
./run.sh

Auto-start on Login (Arch/Manjaro):

mkdir -p ~/.config/autostart
cp clipguard.desktop ~/.config/autostart/

AUR Package (Coming Soon)

yay -S clipguard

📦 openSUSE

# Install system dependencies
sudo zypper install python3 python3-pip xclip git

# Clone the repository
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Run ClipGuard
./run.sh

Auto-start on Login (openSUSE):

mkdir -p ~/.config/autostart
cp clipguard.desktop ~/.config/autostart/

📦 Universal Install (Any Distribution)

If your distribution isn't listed above:

# Ensure you have Python 3.7+ and pip installed
python3 --version
pip3 --version

# Install xclip or xsel (check your package manager)
# Examples:
# sudo apt install xclip       # Debian-based
# sudo dnf install xclip       # Fedora-based
# sudo pacman -S xclip         # Arch-based
# sudo zypper install xclip    # openSUSE

# Clone and set up
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./run.sh

📖 Quick Start

1. Launch ClipGuard

./run.sh

or

python3 main.py

2. Verify It's Running

Look for a green shield icon (🛡️) in your system tray.

3. Test Masking

Copy this text:

Contact me at john.doe@example.com or call 555-123-4567

Paste it somewhere and you should see:

Contact me at [REDACTED_EMAIL] or call [REDACTED_PHONE]

4. Test Restore

Right-click the tray icon → "🔄 Restore Last Content" → Paste again to see the original.

5. Explore Settings

Right-click the icon → "⚙️ Settings"

Browse built-in rules
Add custom patterns
Read the Help tab for examples

🎯 Usage

System Tray Menu

Right-click the ClipGuard icon to access:

📊 Status
  ⏸️  Stop Monitoring       Toggle protection on/off

⚡ Quick Actions
  🔄  Restore Last Content  Get back unmasked text
  🔗  Clean Last Link       Remove URL tracking

  ⚙️  Settings              Customize masking rules
  ℹ️  About ClipGuard       Learn about features

  ❌  Quit                  Exit application

Adding Custom Rules

Open Settings from the tray menu
Go to the "🔒 Masking Rules" tab
Fill in the "Add Custom Rule" section:
- Name: Descriptive name (e.g., "API Key")
- Pattern: Regex pattern (e.g., sk-[A-Za-z0-9]{48})
- Replacement: Placeholder (e.g., [REDACTED_API_KEY])
Click "➕ Add Rule"
Click "💾 Save & Close"

Examples:

Name	Pattern	Replacement
OpenAI API Key	`sk-[A-Za-z0-9]{48}`	`[REDACTED_API_KEY]`
Bitcoin Address	`\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b`	`[REDACTED_BTC]`
Employee ID	`EMP-\d{6}`	`[REDACTED_EMP_ID]`
AWS Key	`AKIA[0-9A-Z]{16}`	`[REDACTED_AWS_KEY]`

🖥️ Desktop Integration

Add to Application Menu (All Distributions)

mkdir -p ~/.local/share/applications
cp clipguard.desktop ~/.local/share/applications/
chmod +x ~/.local/share/applications/clipguard.desktop
update-desktop-database ~/.local/share/applications

ClipGuard will now appear in your application menu under "Utilities" or "Security".

Auto-Start on Login (All Distributions)

Make ClipGuard start automatically when you log in:

mkdir -p ~/.config/autostart
cp clipguard.desktop ~/.config/autostart/

This works on all distributions:

✅ Ubuntu / Debian / Linux Mint / Pop!_OS
✅ Fedora / RHEL / CentOS
✅ Arch Linux / Manjaro
✅ openSUSE
✅ Any distribution with XDG autostart support

Verify it's enabled:

ls -la ~/.config/autostart/clipguard.desktop

To disable autostart:

rm ~/.config/autostart/clipguard.desktop

System Tray Icon Not Showing?

GNOME Users: Install the "AppIndicator and KStatusNotifierItem Support" extension.

# Ubuntu/Debian
sudo apt install gnome-shell-extension-appindicator

# Fedora
sudo dnf install gnome-shell-extension-appindicator

# Arch
sudo pacman -S gnome-shell-extension-appindicator-git

Then enable it in GNOME Extensions/Tweaks.

📋 Configuration

Settings are stored in: ~/.config/clipguard/settings.json

Example configuration:

{
  "monitoring_active": true,
  "builtin_patterns": {
    "Email": {
      "pattern": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b",
      "replacement": "[REDACTED_EMAIL]",
      "enabled": true
    }
  },
  "custom_patterns": {
    "API Key": {
      "pattern": "sk-[A-Za-z0-9]{48}",
      "replacement": "[REDACTED_API_KEY]",
      "enabled": true,
      "custom": true
    }
  }
}

🧪 Testing

Run the included test scripts to verify functionality:

Test Cross-Application Monitoring

./test_cross_app.py

Test Restore Feature

./test_restore.py

For comprehensive testing instructions, see TESTING.md.

🛠️ Troubleshooting

Clipboard Not Being Monitored

Check monitoring is enabled: Icon should be green
Install xclip or xsel: sudo apt install xclip
Check console for errors: python3 main.py

System Tray Icon Not Showing

Install system tray extension (see Desktop Integration above)
Check if your DE supports system tray
Try restarting your desktop environment

Permission Errors

chmod +x run.sh main.py test_*.py

Python Dependencies Issues

# Update pip
pip install --upgrade pip

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

📚 Documentation

INSTALL.md - Detailed installation guide
TESTING.md - Testing procedures
UI_GUIDE.md - Complete UI tour
WHATS_NEW.md - v1.1 feature announcement
CHANGELOG.md - Version history

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/qusaismael/ClipGuard.git
cd ClipGuard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run in development mode
python3 main.py

Code Style

Follow PEP 8
Add docstrings to functions and classes
Comment complex logic
Test your changes thoroughly

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

PyQt6 - Modern GUI framework
pyperclip - Cross-platform clipboard access
Python 3 - Powerful and elegant

Inspired by the need for privacy-conscious computing on Linux.

🌟 Stars

If you find ClipGuard useful, please consider giving it a star! ⭐

🔐 Security

ClipGuard processes all data locally on your machine. No data is ever sent over the network.

If you discover a security vulnerability, You can open an issue above.

🗺️ Roadmap

Support for more data types (passport numbers, dates of birth, etc.)
Multi-language phone number support
Clipboard history with auto-masking
Export/import custom rules
Dark mode theme
Flatpak/Snap package
Wayland-native implementation

💝 Support This Project

If ClipGuard helps protect your privacy, consider:

⭐ Starring this repository
🐛 Reporting bugs you encounter
💡 Suggesting features you'd like to see
📖 Contributing code or documentation
🗣️ Spreading the word to friends and colleagues

Made with ❤️ for privacy-conscious Linux users

ClipGuard v1.0 | October 2025

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
about_dialog.py		about_dialog.py
clipboard_monitor.py		clipboard_monitor.py
clipguard.desktop		clipguard.desktop
main.py		main.py
masking_engine.py		masking_engine.py
requirements.txt		requirements.txt
run.sh		run.sh
settings_dialog.py		settings_dialog.py
settings_manager.py		settings_manager.py

Folders and files

Latest commit

History

Repository files navigation

🛡️ ClipGuard

✨ Features

🔒 Automatic Sensitive Data Masking

🧠 Smart Detection

🔗 Link Cleaning

⚙️ Fully Customizable

🔄 Restore Original Content

🎨 Beautiful Modern UI

🚀 Installation

Prerequisites

📦 Debian / Ubuntu / Linux Mint / Pop!_OS

📦 Fedora / RHEL / CentOS

📦 Arch Linux / Manjaro

📦 openSUSE

📦 Universal Install (Any Distribution)

📖 Quick Start

1. Launch ClipGuard

2. Verify It's Running

3. Test Masking

4. Test Restore

5. Explore Settings

🎯 Usage

System Tray Menu

Adding Custom Rules

🖥️ Desktop Integration

Add to Application Menu (All Distributions)

Auto-Start on Login (All Distributions)

System Tray Icon Not Showing?

📋 Configuration

🧪 Testing

Test Cross-Application Monitoring

Test Restore Feature

🛠️ Troubleshooting

Clipboard Not Being Monitored

System Tray Icon Not Showing

Permission Errors

Python Dependencies Issues

📚 Documentation

🤝 Contributing

Development Setup

Code Style

📝 License

🙏 Acknowledgments

🌟 Stars

🔐 Security

🗺️ Roadmap

💝 Support This Project

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages