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

# 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.

# 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)

# 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:

cerberus tui

Graphical User Interface (GUI)

Launch the GUI with:

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):

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

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

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!):

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

# 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

# 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 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

This project is licensed under the MIT License - see the LICENSE file for details.