From 61f589138032d587310641d63f94e419e0b71001 Mon Sep 17 00:00:00 2001 From: srdusr Date: Mon, 10 Nov 2025 18:19:55 +0200 Subject: Improved Documentation --- push/cerberus/README.md | 275 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 push/cerberus/README.md diff --git a/push/cerberus/README.md b/push/cerberus/README.md new file mode 100644 index 0000000..a66daf8 --- /dev/null +++ b/push/cerberus/README.md @@ -0,0 +1,275 @@ +# 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 -- cgit v1.2.3