toru-vault 0.3.1

ToruVault: A simple Python package for managing Bitwarden secrets

ToruVault

A secure Python secrets manager and environment variable manager for Bitwarden integration. Safely manage API keys and secrets in your Python applications.

Features

• Secrets Manager for Python: Load secrets from Bitwarden Secret Manager into environment variables
• API Key Management: Access and manage API keys securely in your Python applications
• Environment Variable Manager: Easily inject secrets as environment variables
• Bitwarden Python Integration: Seamless integration with Bitwarden Secret Manager
• Secure In-Memory Caching: Encrypted caching with automatic expiration (5 minutes)
• Project-Based Secret Filtering: Filter secrets by project ID
• Secure Storage: Machine-specific secret protection with proper file permissions
• OS Keyring Integration: Secure credential storage using your operating system's keyring

Installation

Using UV (Recommended)

# Install UV if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install toru-vault package (basic installation)
uv pip install toru-vault

# Or install with keyring support (recommended for secure storage)
uv pip install toru-vault[keyring]

# Or install in a virtual environment (recommended)
uv venv create -p python3.10 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install toru-vault[keyring]

This will install all required dependencies:

• bitwarden-sdk - For interfacing with Bitwarden API
• cryptography - For encryption/decryption operations

And when installed with the keyring option:

• keyring - For secure credential storage using OS keyring

Note: Keyring is now optional but recommended. Without keyring, some features like toru-vault init won't work, and you'll need to use the use_keyring=False parameter with the get() function to use in-memory encryption instead of the system keyring.

From Source with UV

# Clone the repository
git clone https://github.com/ToruAI/vault.git
cd vault

uv venv create -p python3.10 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt 

# Install in development mode
uv pip install -e .

Configuration

You have two options for configuring the vault:

Option 1: Initialize with Keyring Storage (Recommended)

The most secure way to set up vault is to use your operating system's secure keyring:

# Initialize vault with secure keyring storage
python -m vault init

This will prompt you to enter:

• Your Bitwarden access token (BWS_TOKEN)
• Your Bitwarden organization ID (ORGANIZATION_ID)
• The path to the state file (STATE_FILE)

How to get the BWS_TOKEN, ORGANIZATION_ID, and STATE_FILE

These credentials will be securely stored in your OS keyring and used automatically by the vault.

Option 2: Environment Variables

Alternatively, you can set the following environment variables:

• BWS_TOKEN: Your Bitwarden access token
• ORGANIZATION_ID: Your Bitwarden organization ID
• STATE_FILE: Path to the state file (must be in an existing directory)
• PROJECT_ID (optional): Your Bitwarden project ID to filter secrets
• API_URL (optional): Defaults to "https://api.bitwarden.com"
• IDENTITY_URL (optional): Defaults to "https://identity.bitwarden.com"

Setting these environment variables is useful for container environments or when keyring is not available.

CLI Commands

Initialize Vault

# Set up vault with secure credential storage
python -m vault init

Listing Available Projects

# List all projects in your organization
python -m vault list 

# With a specific organization ID
python -m vault list --org-id YOUR_ORGANIZATION_ID

Python Usage

Loading secrets into environment variables (Env Manager)

import toru_vault as vault

# Load all secrets into environment variables
vault.env_load()

# Now you can access secrets as environment variables
import os
print(os.environ.get("SECRET_NAME"))

# Load secrets for a specific project
vault.env_load(project_id="your-project-id")

# Alternatively, set PROJECT_ID environment variable and call without parameter
# export PROJECT_ID="your-project-id"  # Linux/macOS
# set PROJECT_ID=your-project-id     # Windows
vault.env_load()  # Will use PROJECT_ID from environment

# Override existing environment variables (default: False)
vault.env_load(override=True)

Getting secrets as a dictionary

import toru_vault as vault

# Get all secrets as a dictionary
secrets = vault.get()
print(secrets["SECRET_NAME"])  # Secret is only decrypted when accessed

# Force refresh the cache
secrets = vault.get(refresh=True)

# Get secrets for a specific project
secrets = vault.get(project_id="your-project-id")

# Alternatively, set PROJECT_ID environment variable and call without parameter
# export PROJECT_ID="your-project-id"  # Linux/macOS
# set PROJECT_ID=your-project-id     # Windows
secrets = vault.get()  # Will use PROJECT_ID from environment

# Use in-memory encryption instead of system keyring
secrets = vault.get(use_keyring=False)

Loading secrets from all projects

import toru_vault as vault

# Load secrets from all projects you have access to into environment variables
vault.env_load_all()

# Override existing environment variables (default: False)
vault.env_load_all(override=True)

Security Features

ToruVault provides robust security for your API keys and environment variables:

1. OS Keyring Integration: Securely stores BWS_TOKEN, ORGANIZATION_ID, and STATE_FILE in your OS keyring
2. Memory Protection: Secrets are encrypted in memory using Fernet encryption (AES-128)
3. Lazy Decryption: Secrets are only decrypted when explicitly accessed
4. Cache Expiration: Cached secrets expire after 5 minutes by default
5. Secure File Permissions: Sets secure permissions on state files
6. Machine-Specific Encryption: Uses machine-specific identifiers for encryption keys
7. Cache Clearing: Automatically clears secret cache on program exit
8. Environment Variable Protection: Doesn't override existing environment variables by default
9. Secure Key Derivation: Uses PBKDF2 with SHA-256 for key derivation
10. No Direct Storage: Never stores secrets in plain text on disk

Bitwarden Python Integration

BWS_TOKEN

Your Bitwarden access token. You can get it from the Bitwarden web app:

1. Log in to your Bitwarden account
2. Go to Secret Manager at left bottom
3. Go to the "Machine accounts" section
4. Create new machine account.
5. Go to Access Token Tab
6. This is your BWS_TOKEN.

Remember that you need to assign access to the machine account for the projects you want to use.

ORGANIZATION_ID

Your Bitwarden organization ID. You can get it from the Bitwarden web app:

1. Log in to your Bitwarden account
2. Go to Secret Manager at left bottom
3. Go to the "Machine accounts" section
4. Create new machine account.
5. Go to Config Tab
6. There is your ORGANIZATION_ID.

STATE_FILE

The STATE_FILE is used by the login_access_token method to store persistent authentication state information after successfully logging in with an access token.

You can set it to any existing file path.

Security Best Practices

When working with secrets, always follow these important guidelines:

1. Never Embed Keys in Code: Always use environment variables, keyring, or secure secret management systems.
2. Never Commit Secrets: Add secret files and credentials to your .gitignore file.
3. Use Key Rotation: Regularly rotate your access tokens as a security measure.
4. Limit Access: Only provide access to secrets on a need-to-know basis.
5. Monitor Usage: Regularly audit which applications and users are accessing your secrets.
6. Use Environment-Specific Secrets: Use different secrets for development, staging, and production environments.

Remember that the vault package is designed to protect secrets once they're in your system, but you must handle the initial configuration securely.

Why Choose ToruVault

ToruVault stands out as a comprehensive solution for Python developers who need:

• A reliable secrets manager for Python applications
• Secure API key management with encryption
• An environment variable manager that simplifies configuration
• Seamless Bitwarden Python integration for team secret sharing

By combining the security of Bitwarden with the convenience of Python's environment variables, ToruVault provides a robust solution for managing sensitive information in your applications.

License

ToruVault is released under the MIT License. See the LICENSE file for details.