A reliable Credentials Manager CLI Application targeting CLI environments via a beautiful TUI interface and respectable encryption practices.
- About
- Features
- Installation
- Usage
- Building from Source
- Project Structure
- Security
- Documentation
- Contributing
- License
Enigma is a lightweight, offline-first credentials manager designed for CLI environments. Built entirely in Python, it combines military-grade cryptography with portability, making it ideal for securing sensitive data across different machines and environments.
- Offline-first: All data stored locally in SQLite database
- Multi-user support: Isolated credentials per user with independent encryption keys
- Cross-platform: Works on Linux, macOS, and Windows terminals
- Portable: Can run from USB flash drives without installation
- Lightweight: Minimal dependencies, fast startup
- Secure TUI Interface: Interactive terminal-based user interface using
curses - AES-256 Encryption: Military-grade symmetric encryption for credential storage
- PBKDF2 Key Derivation: Secure password-based key derivation with configurable iterations
- Fernet Multi-Key Encryption: Additional layer of protection using multi-key Fernet
- Multi-User Architecture: Each user has isolated credentials with independent encryption
- SQLite Storage: Lightweight, zero-configuration database
- ASCII Art UI: Beautiful terminal visuals
Download the latest release for your platform from the GitHub Releases page.
| Platform | File | Notes |
|---|---|---|
| Linux | enigma.bin |
Make executable: chmod +x enigma.bin |
| macOS | enigma.bin |
Allow execution in System Preferences if blocked |
| Windows | enigma.exe |
Run from Command Prompt or PowerShell |
# Clone the repository
git clone https://github.com/tuliofh01/enigma.git
cd enigma
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# or
.venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Run directly
python main.py# Install in development mode
pip install -e .
# Run via command
enigma-
Launch the application:
./enigma.bin # Linux/macOS enigma.exe # Windows
-
The application will display the greetings screen
-
To create your first user, run the initialization script:
python src/scripts/init_user.py
The TUI provides the following states:
| State | Description |
|---|---|
greetings |
Welcome screen with ASCII art |
login |
User authentication |
error |
Error display and handling |
main |
Main application interface (future) |
On first use, the initialization script creates a new user entry with:
- Username (ASCII only)
- Password (combined with salt + pepper)
- Auto-generated encryption salt
The DatabaseCtrl class provides:
| Method | Description |
|---|---|
authenticate(username, password) |
Verify user credentials |
get_all_records() |
Retrieve all credential records |
get_decrypted_target_record(id) |
Decrypt and retrieve specific record |
encrypt_and_insert_record(desc, user, pwd) |
Add new credential |
delete_target_record(id) |
Remove credential |
For instructions on compiling Enigma into standalone executables, see the Build System Documentation.
# Install Nuitka
pip install nuitka
# Build for current platform
python scripts/build.py
# Build output location
ls builds/latest/# Build for specific platform
python scripts/build.py --target win # Windows
python scripts/build.py --target linux # Linux
python scripts/build.py --target macos # macOS
# Build for all platforms (requires cross-compilers)
python scripts/build.py --all
# Clean previous builds
python scripts/build.py --cleanThe project includes GitHub Actions workflows for automated builds:
| Trigger | Action |
|---|---|
Push to main |
Dev builds for all platforms |
| Pull Request | Dev builds |
Version tag (v*) |
Release builds + GitHub Release |
enigma/
├── main.py # Application entry point
├── main.spec # PyInstaller spec (legacy)
├── requirements.txt # Runtime dependencies
├── pyproject.toml # Package configuration
│
├── src/ # Source code
│ ├── controllers/
│ │ └── database_controller.py # Database & encryption logic
│ ├── misc/
│ │ ├── config.py # Global configuration
│ │ └── resize_window.py # Terminal resize handling
│ ├── scripts/
│ │ └── init_user.py # User initialization utility
│ └── tui/
│ ├── windows/
│ │ ├── empty_window.py # Base window
│ │ └── stateful_window.py # State machine window
│ └── window_transformations/
│ ├── greetings_state.py
│ ├── login_state.py
│ ├── main_state.py
│ ├── error_state.py
│ └── old/ # Deprecated screens
│
├── assets/ # Application assets
│ ├── art/ # ASCII art files
│ │ ├── title_art.txt
│ │ ├── loading_art.txt
│ │ └── error_art.txt
│ └── data/
│ ├── env_variables.json # Configuration
│ └── sqlite3_data_file.db # Encrypted credentials
│
├── builds/ # Build output (gitignored)
│ ├── README.md # Build system documentation
│ └── YYYYMMDD_HHMMSS/ # Timestamped builds
│
└── .github/
└── workflows/
└── build.yml # CI/CD pipeline
┌─────────────────────────────────────────────────────────────┐
│ ENCRYPTION LAYERS │
├─────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: PBKDF2 (Password-Based Key Derivation) │
│ ├── Algorithm: SHA-256 │
│ ├── Iterations: Configurable (default: 100,000) │
│ └── Output: 256-bit key │
│ │
│ Layer 2: AES-256-ECB (Credential Encryption) │
│ ├── Block cipher with PKCS7 padding │
│ └── Encrypts: Password + Pepper │
│ │
│ Layer 3: Fernet Multi-Key (Record Encryption) │
│ ├── AES-128-CBC with PKCS7 padding │
│ ├── HMAC using SHA-256 for authentication │
│ └── Encrypts: Username, Password, Description │
│ │
└─────────────────────────────────────────────────────────────┘
- Salt: Unique 16-byte random salt per user (generated via
os.urandom) - Pepper: Random character appended before hashing
- Key Derivation: PBKDF2-HMAC-SHA256 with high iteration count
- Database: SQLite with encrypted credential fields
- Offline: No network transmission of credentials
- ECB mode for primary encryption (consider upgrading to CBC/GCM in future)
- No master password recovery mechanism
- Database file should be protected at filesystem level
| Document | Description |
|---|---|
| Build System | Detailed build process, CI/CD, troubleshooting |
| Security Model | Encryption layers and practices |
| API Reference | Database controller methods (TBD) |
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
# Clone and setup
git clone https://github.com/tuliofh01/enigma.git
cd enigma
python -m venv .venv
source .venv/bin/activate
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy src/This project is licensed under the MIT License.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
- Cryptography:
cryptography- Modern crypto primitives - Crypto Operations:
pycryptodome- AES implementation - TUI Framework: Python's built-in
cursesmodule - Build System:
Nuitka- Python compiler
Thank you for using Enigma! Please remember to credit the author when using, modifying, or distributing this software.