Skip to content
44ompatilPublic

About

Local and Offline First, secure file manager.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

16 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿ” IronVault

A secure, encrypted file vault for the command line.
Protect your files with military-grade cryptography โ€” no cloud, no accounts, no compromises.

Python 3.12+ AES-256 + Argon2id MIT License Version 0.1.0


โœจ Features

  • ๐Ÿ”’ 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

๐Ÿ“‹ Table of Contents


๐Ÿ” Security Model

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.

Password Requirements

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. !@#$%)

๐Ÿ“ฆ Requirements

  • Python 3.12+
  • uv (recommended package manager, used in this project)
  • OR pip if you prefer

Dependencies (managed automatically):


๐Ÿš€ Installation

Option 1 โ€” Using uv (recommended)

# 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

Option 2 โ€” Using pip

# 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

โšก Quick Start

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

๐Ÿ› ๏ธ Commands

All commands follow the pattern:

python -m src.cli <command> [OPTIONS] [ARGS]

init โ€” Initialise a new vault

Creates a new .IronVault/ directory in the current working directory.

python -m src.cli init

You will be prompted for a master password (twice for confirmation). IronVault will:

  1. Validate the password strength
  2. Generate a cryptographic salt
  3. Derive an Argon2id key
  4. Write a config.json with vault metadata
  5. 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, init will refuse to overwrite it. Delete .IronVault/ manually first.


add โ€” Encrypt and store a file

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:

  1. SHA-256 checksum is computed
  2. File is encrypted (AES-256) and saved as <uuid>.enc inside the vault
  3. A manifest entry (name, size, checksum, timestamp) is added
  4. The original file is securely deleted (3-pass overwrite) unless --keep-original is 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-original

get โ€” Retrieve a file

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

  1. File is looked up in the encrypted manifest
  2. The .enc blob is decrypted to the destination path
  3. 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.docx

list โ€” List vault contents

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

remove โ€” Remove a file

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:

  1. Manifest is searched for the file by name
  2. You are prompted to confirm (unless --force is set)
  3. The .enc file is securely deleted (3-pass overwrite)
  4. 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 --force

destroy โ€” Permanently destroy the vault

Wipes every encrypted file and deletes the entire vault directory.

python -m src.cli destroy

You must type DELETE VAULT exactly to confirm. This action:

  • Securely overwrites every .enc file (3-pass)
  • Removes the entire .IronVault/ directory tree

๐Ÿšจ This is irreversible. There is no recovery mechanism. All stored files will be permanently lost.


๐Ÿ“ Vault Structure

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"
    }
}

๐Ÿค Contributing

Contributions are welcome! Here's how to get started:

  1. Fork the repository

  2. Clone your fork: git clone https://github.com/<your-username>/IronVault.git

  3. Create a feature branch: git checkout -b feature/my-new-feature

  4. Install dependencies: uv sync

  5. Make your changes and ensure the code passes linting:

    uv run ruff check src/
  6. Commit your changes: git commit -m "feat: add my new feature"

  7. Push to your branch: git push origin feature/my-new-feature

  8. Open a Pull Request against main

Commit Style

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

Reporting Issues

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

๐Ÿ“œ License

This project is licensed under the MIT License. See LICENSE for details.


Built with โค๏ธ using Typer, Rich, and cryptography.

About

Local and Offline First, secure file manager.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages