diff options
Diffstat (limited to 'push')
| -rw-r--r-- | push/cerberus/README.md | 275 |
1 files changed, 0 insertions, 275 deletions
diff --git a/push/cerberus/README.md b/push/cerberus/README.md deleted file mode 100644 index a66daf8..0000000 --- a/push/cerberus/README.md +++ /dev/null @@ -1,275 +0,0 @@ -# Cerberus Password Manager - -A secure, high-performance password manager with a C core for cryptographic operations, featuring a modern TUI, GUI, and browser extensions. - -## Features - -- **High-performance** cryptographic operations powered by a C core -- **Secure** password storage with zero-knowledge encryption -- **Cross-platform** support (Windows, macOS, Linux) -- **Multiple Interfaces**: - - Command Line Interface (CLI) - - Terminal User Interface (TUI) - - Graphical User Interface (GUI) - - Browser Extensions (Firefox, Chrome/Edge) -- **Smart Password Management**: - - Auto-detection of password change forms - - One-click password rotation - - Password strength analysis - - Breach monitoring -- **Browser Integration**: - - Auto-fill login forms - - Auto-save new logins - - Auto-update changed passwords - - Smart detection of login forms -- **Import/Export** from other password managers -- **Biometric** authentication support -- **Secure Sharing** of passwords (coming soon) -- **CLI, TUI, and GUI** interfaces for all operations - -## Installation - -### Prerequisites - -- Python 3.8+ -- CMake 3.10+ -- OpenSSL development libraries -- C compiler (GCC/Clang) -- Node.js 16+ (for browser extensions) -- Optional for TUI: `textual`, `rich` (install with extra `ui-tui`) -- Optional for GUI: `PyQt6` (install with extra `ui-gui`) - -### Quick Start - -```bash -# Clone the repository -git clone https://github.com/yourusername/cerberus.git -cd cerberus - -# Install base package -pip install -e . - -# Optional extras -# TUI -pip install -e .[ui-tui] -# GUI -pip install -e .[ui-gui] -# Selenium automation (optional) -pip install -e .[automation-selenium] - -# Build and install the C core -mkdir -p build && cd build -cmake .. -make -make install - -# Initialize your password vault -cerberus init -``` - -### One-command install (Linux) - -Use the provided `scripts/cerberus-install.sh` to automate Python install, C core build, and (optionally) native messaging setup. - -```bash -# Base install -bash scripts/cerberus-install.sh - -# With extras (TUI, GUI, Selenium) and Firefox native messaging manifest -CERB_EXTRAS="ui-tui,ui-gui,automation-selenium" CERB_INSTALL_FF=1 bash scripts/cerberus-install.sh - -# With Chrome native messaging manifest -CERB_INSTALL_CHROME=1 bash scripts/cerberus-install.sh - -# Skip C core build (if already built/installed) -CERB_SKIP_BUILD=1 bash scripts/cerberus-install.sh -``` - -Environment variables: - -- `CERB_EXTRAS`: comma-separated extras to install (e.g., `ui-tui,ui-gui,automation-selenium`). -- `CERB_INSTALL_FF=1`: also install Firefox native messaging manifest. -- `CERB_INSTALL_CHROME=1`: also install Chrome native messaging manifest. -- `CERB_SKIP_BUILD=1`: skip building the C core via CMake. - -## 🛠️ Usage - -### Command Line Interface (CLI) - -```bash -# Initialize a new password vault -cerberus init - -# Add a new password entry -cerberus add --website example.com --username user@example.com - -# Get a password (copies to clipboard) -cerberus get example.com - -# List all entries -cerberus list - -# Rotate a password (local vault only) -cerberus rotate example.com - -# Web-rotate via browser automation with dynamic discovery -# Simulate (dry-run) across all entries -cerberus web-rotate --dry-run --all - -# Rotate for a single target using Playwright (default) -cerberus web-rotate example.com - -# Use Selenium instead -cerberus web-rotate example.com --engine selenium - -# Launch the GUI -pip install -e .[ui-gui] -cerberus gui -``` - -### Terminal User Interface (TUI) - -Launch the TUI with: -```bash -cerberus tui -``` - -### Graphical User Interface (GUI) - -Launch the GUI with: -```bash -cerberus gui -``` - -### Browser Extensions - -Currently, a development Firefox extension is included under `webext/firefox/`. - -Manual install steps for development: - -1. Open `about:debugging#/runtime/this-firefox` in Firefox -2. Click "Load Temporary Add-on..." -3. Select `webext/firefox/manifest.json` -4. A Cerberus icon will appear in the toolbar -5. Use the popup to fill credentials on the current tab - -Note: This extension is a scaffold for development. A native messaging bridge to the local -vault is planned for secure autofill and save. Today it supports simple page form fill. - -### Native Messaging (development) - -Native messaging lets the browser extension talk to your local Cerberus vault securely. - -1) Install the native host (installed as a console script): - -```bash -pip install -e . -# The host command will be available as: -which cerberus-native-host -``` - -2) Install the native messaging manifest for your browser: - -- Firefox (Linux): copy the provided manifest and adjust the `path` if needed - -```bash -mkdir -p ~/.mozilla/native-messaging-hosts/ -cp native/manifests/firefox_com.cerberus.pm.json ~/.mozilla/native-messaging-hosts/com.cerberus.pm.json -# Ensure the path points to your cerberus-native-host binary (e.g., /usr/local/bin/cerberus-native-host) -sed -i "s#/usr/local/bin/cerberus-native-host#$(command -v cerberus-native-host | sed 's#/#\\/#g')#" ~/.mozilla/native-messaging-hosts/com.cerberus.pm.json -``` - -- Chrome/Edge (Linux): create manifest at the standard location - -```bash -mkdir -p ~/.config/google-chrome/NativeMessagingHosts/ -cat > ~/.config/google-chrome/NativeMessagingHosts/com.cerberus.pm.json << 'EOF' -{ - "name": "com.cerberus.pm", - "description": "Cerberus Password Manager Native Messaging Host (dev)", - "path": "/usr/local/bin/cerberus-native-host", - "type": "stdio", - "allowed_origins": [ - "chrome-extension://REPLACE_WITH_EXTENSION_ID/" - ] -} -EOF -# Replace the path with $(command -v cerberus-native-host) -sed -i "s#/usr/local/bin/cerberus-native-host#$(command -v cerberus-native-host | sed 's#/#\\/#g')#" ~/.config/google-chrome/NativeMessagingHosts/com.cerberus.pm.json -``` - -3) Unlocking the vault for native host: - -For development, you can pass the master via environment variable (only for local dev!): - -```bash -CERB_MASTER='your-master' CERB_DATA_DIR=~/.cerberus cerberus-native-host -# Typically launched by the browser; running manually is for debugging only. -``` - -In the extension popup, click "Fetch from Vault" to retrieve credentials for the current tab. - -## Password Change Automation - -Cerberus can automatically detect and handle many password change flows via web automation. -It uses a hybrid approach: - -- Tries a site-specific flow when available (e.g., `GithubFlow` in `cerberus/automation/sites/`) -- Falls back to heuristic discovery (`cerberus/automation/discovery.py`): - - Scans the DOM for common "Change/Reset Password" links/buttons - - Tries common settings paths like `/settings/security` and `/settings/password` - - Attempts to locate current/new/confirm password inputs and submit - -```bash -# Automatically detect and update password for a website -cerberus web-rotate example.com - -# Check for password changes on all supported sites -cerberus web-rotate --all - -Tip: Use `--dry-run` first to preview actions without making changes. - -Limitations: Some sites require MFA/2FA or complex flows; in those cases the tool will -return a NEEDS_MANUAL status and avoid unsafe actions. -``` - -## Development - -### Setup Development Environment - -```bash -# Install development dependencies -pip install -e ".[dev]" - -# Install pre-commit hooks -pre-commit install - -# Run tests -pytest - -# Run type checking -mypy . - -# Format code -black . - -# Lint code -flake8 -``` - - -## Contributing - -Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details. - -## License - -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. - -## Security - -For security-related issues, please email security@example.com instead of using the issue tracker. - -## License - -MIT |