path: root/push/cerberus/README.md

# 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