Improved Documentation

1 files changed, 275 insertions, 0 deletions

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