diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 305 |
1 files changed, 264 insertions, 41 deletions
@@ -1,58 +1,281 @@ -# cerberus +# 🐕 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/srdusr/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 ``` -## Description: +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. -- Password manager written in C +## 🛠️ Usage -## Requirements: +### Command Line Interface (CLI) + +```bash +# Initialize a new password vault +cerberus init -- Linux -- xclip +# Add a new password entry +cerberus add --website example.com --username user@example.com -## Usage: +# Get a password (copies to clipboard) +cerberus get example.com -- Command to compile +# 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 -$ gcc -o cerberus main.c -lcrypto +cerberus tui ``` -- Run the program: +### Graphical User Interface (GUI) +Launch the GUI with: ```bash -$ ./cerberus +cerberus gui ``` -- NOTE: This program is still in very early stages of development and should not be used in any production environment, use at your own risk. +### 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 +``` + +### Building Browser Extensions + +```bash +The Firefox development extension needs no build step. For Chromium-based browsers +and production bundles, a separate web extension build pipeline will be added. +``` + +## 🤝 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 + +NOTE: This program is still in very early stages of development and should not be used in any production environment, use at your own risk. + +## License + +MIT |