https://github.com/mk2112/guardian-sync
PGP encryption layer for cloud file synchronization
https://github.com/mk2112/guardian-sync
encryption file-sync gnupg pgp privacy python zero-trust
Last synced: 9 months ago
JSON representation
PGP encryption layer for cloud file synchronization
- Host: GitHub
- URL: https://github.com/mk2112/guardian-sync
- Owner: MK2112
- License: mit
- Created: 2025-03-18T15:17:39.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-21T17:37:17.000Z (9 months ago)
- Last Synced: 2025-09-21T19:28:35.957Z (9 months ago)
- Topics: encryption, file-sync, gnupg, pgp, privacy, python, zero-trust
- Language: Python
- Homepage:
- Size: 71.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# guardian-sync
guardian-sync provides a PGP encryption layer for zero-trust cloud storage. Files are automatically encrypted with PGP before they sync, and decrypted locally when needed.
All encryption and decryption happens on your device, ensuring your data remains private and secure.
## Features
- Automatic PGP encryption of files before they sync
- Automatic decryption of files when they're updated
- Works with your existing cloud sync client installation
- Monitoring for local changes
- Event-based checking for remote changes
## Requirements
- Python 3.10.x or higher
- GnuPG installed on your system
- Some cloud sync client installed and configured on your computer
## Installation
1. Clone the repository:
```
git clone https://github.com/MK2112/guardian-sync.git
cd guardian-sync
```
2. Install the package:
```
pip install -r requirements.txt
```
3. Create a PGP key if you don't already have one:
```
gpg --full-generate-key
```
Follow the prompts to create your key. Remember the name you use for your key.
4. Create or update the configuration file (`config.json`):
```json
{
"local": {
"monitored_path": "./secure_files",
"decrypted_path": "./secure_files"
},
"sync_folder": {
"path": "",
"encrypted_folder": "encrypted_files"
},
"pgp": {
"key_name": "your_key_name",
"passphrase": "",
"gnupghome": "~/.gnupg",
"always_trust": false
},
"sync": {
"check_interval": 60
},
"log_file": null
}
```
**Notes:**
- Use `sync_folder.path` to specify the full path to your cloud sync folder (e.g. for DropBox, Google Drive, SyncThing, etc.)
- Set `pgp.key_name` to the name you used when creating your PGP key
- Leave `pgp.passphrase` empty to be prompted each time, or set it for automatic operation (less secure)
- Set `pgp.always_trust` to `true` only if you understand the risks; by default it is `false` for better security
- Persisted logging is optional:
- Set `log_file` to a path (e.g. `"guardian-sync.log"`) to enable file logging
- Set `log_file` to `null` to disable file logging entirely (only console logs)
- All files in the monitored directory, including hidden files, are encrypted and synced.
- The tool automatically handles file overwrites and creates conflict files if both local and remote versions change independently.
## Usage
### Quick Start
1. **Add files to encrypt:**
Place any files you want to keep secure into your chosen "monitored" directory (e.g. `secure_files/`).
*An example could be:*
```bash
echo "my-secret-password" > secure_files/passwords.txt
```
2. **Start guardian-sync:**
Run the application to automatically encrypt new or changed files in your monitored directory:
```bash
guardian-sync
```
You can specify a custom config file if needed:
```bash
guardian-sync --config /path/to/your/config.json
```
3. **Encrypted files appear:**
guardian-sync will automatically:
- Detect new or updated files in your monitored directory.
- Encrypt them using your PGP key.
- Place the encrypted versions (e.g. `passwords.txt.gpg`) in the configured encrypted folder (e.g. `encrypted_files/`).
4. **Accessing your files elsewhere:**
- To decrypt a file, guardian-sync will automatically detect new encrypted files in your encrypted folder and decrypt them back to your monitored directory.
- You can safely sync the encrypted folder (`encrypted_files/`) with any cloud service (e.g. Dropbox, Google Drive, OneDrive, Syncthing, etc.), knowing only encrypted data leaves your device.
### Tests
Run the tests with:
```bash
pytest ./tests/
```
### Example Workflow
- Add a file to `secure_files/`
- guardian-sync encrypts it to `encrypted_files/filename.gpg`.
- Sync `encrypted_files/filename.gpg` to another device
- guardian-sync decrypts it back to `secure_files/filename`.
Your files are always encrypted before leaving your device. Only you, with your PGP key, can decrypt them.
## Security Considerations
- Your files are only stored in encrypted state in the cloud
- Decryption happens locally on your device
- Your PGP private key never leaves your device
- It is recommended to use a strong, unique passphrase for your PGP key
- If you specify your passphrase in the config file, which isn't recommended, ensure the file is properly secured
- Only you should know your passphrase and private key, nobody else, at any point
## Troubleshooting
- If enabled, check your log file for detailed information and auditability
- Ensure your PGP key is properly set up and accessible
- Verify your sync folder folder path is correct
- Make sure the sync folder client is running and properly syncing
- Make sure you have proper permissions for the directories in your config
## License
MIT.