A secure, encrypted file vault for the command line.
Protect your files with military-grade cryptography โ no cloud, no accounts, no compromises.
- ๐ AES-256 encryption (via Fernet) for every stored file
- ๐ง Argon2id key derivation โ industry-best KDF resistant to brute-force and GPU attacks
- ๐๏ธ 3-pass secure deletion โ original and vault files are overwritten with random bytes before removal
- โ SHA-256 integrity verification โ checksums are stored and verified on every retrieval
- ๐ Encrypted manifest โ file metadata is itself encrypted; no plaintext index on disk
- ๐ฅ๏ธ Rich CLI โ beautiful, colourful output with progress spinners and formatted tables
- ๐ฆ Zero cloud dependency โ your vault lives entirely on your own machine
IronVault is designed with a defence-in-depth approach:
| Layer | Technology | Purpose |
|---|---|---|
| Key Derivation | Argon2id (64 MB RAM, 2 iterations, 4 lanes) | Derives a 32-byte key from your master password |
| Encryption | AES-256 via Fernet (symmetric, authenticated) | Encrypts each file and the manifest |
| Integrity | SHA-256 checksum | Detects tampering or corruption on retrieval |
| Secure Deletion | 3-pass random overwrite + fsync |
Prevents data recovery from disk |
| Manifest | Encrypted .enc file |
File names and metadata are never stored in plaintext |
Your master password never leaves your machine. It is used only to derive the encryption key in memory, and discarded immediately after.
Passwords must meet all of the following:
- At least 12 characters long
- At least one uppercase letter
- At least one lowercase letter
- At least one digit
- At least one special character (e.g.
!@#$%)
- Python 3.12+
uv(recommended package manager, used in this project)- OR
pipif you prefer
Dependencies (managed automatically):
cryptographyโฅ 46.0.5richโฅ 14.3.2typerโฅ 0.24.0
# Clone the repository
git clone https://github.com/OmPatil44/IronVault.git
cd IronVault
# Create a virtual environment and install dependencies
uv sync
# Run the CLI
uv run python -m src.cli --help# Clone the repository
git clone https://github.com/OmPatil44/IronVault.git
cd IronVault
# Create & activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
# Install dependencies
pip install cryptography rich typer
# Run the CLI
python -m src.cli --help# 1. Initialise a vault in the current directory
python -m src.cli init
# 2. Encrypt and store a file
python -m src.cli add secret.pdf
# 3. List vault contents
python -m src.cli list
# 4. Retrieve a file
python -m src.cli get secret.pdf
# 5. Remove a file from the vault
python -m src.cli remove secret.pdfAll commands follow the pattern:
python -m src.cli <command> [OPTIONS] [ARGS]
Creates a new .IronVault/ directory in the current working directory.
python -m src.cli initYou will be prompted for a master password (twice for confirmation). IronVault will:
- Validate the password strength
- Generate a cryptographic salt
- Derive an Argon2id key
- Write a
config.jsonwith vault metadata - Create an empty, encrypted manifest
Example output:
โญโโโโโโโโโโโโโโโ Success โโโโโโโโโโโโโโโโฎ
โ โ Vault initialised successfully! โ
โ โ
โ Location : /your/path/.IronVault โ
โ Protected with Argon2id + AES-256. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ ๏ธ If a vault already exists in the directory,initwill refuse to overwrite it. Delete.IronVault/manually first.
Encrypts a file using your master password and stores it in the vault.
python -m src.cli add <FILE> [OPTIONS]| Option | Description |
|---|---|
--keep-original |
Keep the plaintext source file after encryption (default: securely deleted) |
What happens:
- SHA-256 checksum is computed
- File is encrypted (AES-256) and saved as
<uuid>.encinside the vault - A manifest entry (name, size, checksum, timestamp) is added
- The original file is securely deleted (3-pass overwrite) unless
--keep-originalis set
Example:
# Store and securely delete the original
python -m src.cli add confidential.docx
# Store but keep the original file
python -m src.cli add confidential.docx --keep-originalDecrypts and retrieves a file from the vault.
python -m src.cli get <FILENAME> [OPTIONS]| Option | Description |
|---|---|
--output <PATH> |
Destination path for the decrypted file (default: current directory) |
What happens:
- File is looked up in the encrypted manifest
- The
.encblob is decrypted to the destination path - SHA-256 checksum is verified โ if it doesn't match, the output is deleted and an error is raised
Example:
# Retrieve to current directory
python -m src.cli get confidential.docx
# Retrieve to a specific path
python -m src.cli get confidential.docx --output ~/Documents/confidential.docxDisplays all files stored in the vault in a formatted table.
python -m src.cli list [OPTIONS]| Option | Description |
|---|---|
--json |
Output raw JSON instead of a table |
Example output:
โญโโโโโโโโโโโโโโโ IronVault Contents โโโโโโโโโโโโโโโโโโโโโโฎ
โ # โ Filename โ Size โ Added โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1 โ confidential.docx โ 32.50 KB โ 2026-02-20 15:30 โ
โ 2 โ passport.jpg โ 4.10 MB โ 2026-02-18 09:12 โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
Total: 2 file(s) in vault.
Permanently removes a file from the vault. You will be asked to confirm.
python -m src.cli remove <FILENAME> [OPTIONS]| Option | Description |
|---|---|
--force |
Skip the confirmation prompt |
What happens:
- Manifest is searched for the file by name
- You are prompted to confirm (unless
--forceis set) - The
.encfile is securely deleted (3-pass overwrite) - The manifest entry is removed
# Interactive removal (recommended)
python -m src.cli remove confidential.docx
# Non-interactive removal (e.g., in scripts)
python -m src.cli remove confidential.docx --forceWipes every encrypted file and deletes the entire vault directory.
python -m src.cli destroyYou must type DELETE VAULT exactly to confirm. This action:
- Securely overwrites every
.encfile (3-pass) - Removes the entire
.IronVault/directory tree
๐จ This is irreversible. There is no recovery mechanism. All stored files will be permanently lost.
After initialisation, IronVault creates the following on disk:
.IronVault/
โโโ data/
โโโ config.json โ Vault metadata (salt, KDF params, vault ID)
โโโ manifest.enc โ Encrypted index of all stored files
โโโ <uuid>.enc โ Encrypted file blob
โโโ <uuid>.enc โ Encrypted file blob
config.json (plaintext, contains no secrets):
{
"version": "1.0",
"VaultID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"timeStamp": "2026-02-20 ...",
"salt": "deadbeef...",
"KDF_Params": {
"length": "32",
"iterations": "2",
"lanes": "4",
"memory_cost": "65536"
}
}Contributions are welcome! Here's how to get started:
-
Fork the repository
-
Clone your fork:
git clone https://github.com/<your-username>/IronVault.git -
Create a feature branch:
git checkout -b feature/my-new-feature -
Install dependencies:
uv sync -
Make your changes and ensure the code passes linting:
uv run ruff check src/
-
Commit your changes:
git commit -m "feat: add my new feature" -
Push to your branch:
git push origin feature/my-new-feature -
Open a Pull Request against
main
This project uses Conventional Commits:
| Prefix | Use for |
|---|---|
feat: |
New features |
fix: |
Bug fixes |
docs: |
Documentation changes |
refactor: |
Code refactoring |
test: |
Adding or updating tests |
chore: |
Build process, dependency updates |
Please use GitHub Issues to report bugs or request features. Include:
- Your OS and Python version
- Steps to reproduce (if a bug)
- Expected vs actual behaviour
This project is licensed under the MIT License. See LICENSE for details.
Built with โค๏ธ using Typer, Rich, and cryptography.