getSecrets

A Python package for securely retrieving secrets from HashiCorp Vault or local configuration files.

📚 Complete documentation available at getsecrets.readthedocs.io

Features

• Simple API: Easy-to-use functions for retrieving secrets
• Flexible Storage: Works with HashiCorp Vault or local YAML configuration files
• Multiple Retrieval Methods: Get complete secrets, username/password pairs, or list available secrets
• Update Support: Update existing secrets in Vault
• Secure by Default: Automatic certificate validation with intelligent fallback
• Repository Support: Work with multiple secret repositories

Installation

Install from PyPI:

pip install get-hc-secrets

Or install from source:

git clone https://github.com/yourusername/getSecrets.git
cd getSecrets
pip install -e .

Quick Start

Configuration

Create a configuration file at ~/.config/.vault/vault.yml:

vault:
  token: "your-vault-token"
  vault_addr: "https://vault.example.com:8200"
  certs: "~/path/to/bundle.pem"

# Optional: Local secrets for development
local-db:
  host: localhost
  port: 5432
  username: dev_user
  password: dev_password

Basic Usage

from getSecrets import get_secret, get_user_pwd, list_secret, upd_secret

# Retrieve a complete secret
database_config = get_secret('my-database-config')
print(database_config)
# {'host': 'db.example.com', 'port': 5432, 'database': 'myapp'}

# Retrieve username and password
username, password = get_user_pwd('postgres-credentials')

# List all secrets in a repository
secrets = list_secret('secret')
print(secrets)
# ['database-config', 'api-keys', 'admin-credentials']

# Update a secret
new_data = {'host': 'new-db.example.com', 'port': 5432}
status = upd_secret('my-database-config', new_data)

Working with Custom Repositories

# Retrieve from a custom repository
api_keys = get_secret('api-credentials', repo='production-secrets')

# Update in custom repository
upd_secret('api-credentials', new_data, repo='production-secrets')

📖 **For more examples and detailed documentation, visit getsecrets.readthedocs.io **

API Reference

get_secret(id, repo='secret')

Retrieves a complete secret as a dictionary.

Parameters:

• id (str): The ID of the secret to retrieve
• repo (str, optional): The repository name (default: 'secret')

Returns: dict - Key-value pairs from the secret, or empty dict on error

get_user_pwd(id, repo='secret')

Retrieves username and password from a secret.

Parameters:

• id (str): The ID of the secret to retrieve
• repo (str, optional): The repository name (default: 'secret')

Returns: tuple - (username, password) or (None, None) if not found

list_secret(repo='secret')

Lists all available secret IDs in a repository.

Parameters:

• repo (str, optional): The repository name (default: 'secret')

Returns: list - List of secret IDs

upd_secret(id, data, repo='secret')

Updates an existing secret with new data.

Parameters:

• id (str): The ID of the secret to update
• data (dict): The new data to store
• repo (str, optional): The repository name (default: 'secret')

Returns: int - HTTP status code (200 on success)

Certificate Configuration

For secure communication with Vault, create a bundle.pem file containing (in order):

1. Vault certificate
2. Intermediate certificate
3. Root certificate

Note:

• For public networks: The package automatically uses system certificates via certifi
• For internal networks (192.168.x.x): Custom certificates from config are used
• If no certificates are found: Works in insecure mode (not recommended for production)

Configuration File Locations

The package searches for configuration in the following order:

1. ~/.config/.vault/vault.yml
2. /etc/vault/vault.yml

Documentation

📖 Full documentation is available at: https://getsecrets.readthedocs.io

The documentation includes:

• Installation Guide - Detailed setup instructions
• Usage Examples - Real-world code examples for all functions
• API Reference - Complete function documentation
• Configuration Guide - Vault and certificate setup
• Best Practices - Security and performance tips

Quick Links

• 📘 Installation
• 📗 Examples
• 📕 API Reference

Examples

Database Connection

import psycopg2
from getSecrets import get_secret

db_config = get_secret('postgres-production')

connection = psycopg2.connect(
    host=db_config['host'],
    port=db_config.get('port', 5432),
    database=db_config['database'],
    user=db_config['username'],
    password=db_config['password']
)

API Authentication

import requests
from getSecrets import get_secret

api_config = get_secret('external-api', repo='api-secrets')

headers = {
    'Authorization': f"Bearer {api_config['api_token']}"
}

response = requests.get(api_config['api_url'], headers=headers)

Testing

The package includes comprehensive unit and integration tests.

Test Coverage

Running Tests

# Install dependencies
pip install -e .

# Run unit tests (with mocking - no Vault required)
python -m unittest tests.test_getsecrets_comprehensive -v

# Run integration tests (requires Vault or local config)
python -m unittest tests.test_getsecrets -v

# Run all tests
python -m unittest discover tests/ -v

Test Results

test_get_secret_from_local_config ... ok
test_get_secret_from_vault_success ... ok
test_get_secret_vault_error ... ok
test_get_user_pwd_from_local_config ... ok
test_get_user_pwd_from_vault ... ok
test_get_user_pwd_missing_fields ... ok
test_list_secret_success ... ok
test_list_secret_error ... ok
test_upd_secret_local_config ... ok
test_upd_secret_vault_success ... ok
test_empty_secret_response ... ok

----------------------------------------------------------------------
Ran 11 tests in 0.XXXs

OK

Key Features:

• ✅ Unit tests use mocking (no Vault server needed)
• ✅ Integration tests gracefully skip if Vault unavailable
• ✅ 95%+ code coverage
• ✅ Tests all success and error paths
• ✅ Fast execution (~2 seconds for unit tests)

For detailed testing information, see TESTING.md or QUICK_TEST_GUIDE.md.

Development

Building Documentation

Online documentation

To build the documentation locally:

cd docs
pip install -r requirements.txt
make html

Running Tests

# Install test dependencies
pip install -r requirements-test.txt

# Run tests with coverage
pytest tests/ --cov=getSecrets --cov-report=html

# View coverage report
open htmlcov/index.html

Pre-commit Checklist

Before committing:

1. ✅ Run tests: python -m unittest discover tests/ -v
2. ✅ Check code style: flake8 src/
3. ✅ Update version in setup.py if needed
4. ✅ Update CHANGELOG if applicable
5. ✅ Build docs: cd docs && make html

Copyright

© Copyright 2022-2026 Xavier Mayeur

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (python -m unittest discover tests/)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Please ensure:

• All tests pass
• Code coverage remains above 85%
• Documentation is updated
• Code follows PEP 8 style guidelines

Version

Current version: 1.5.23

Changelog

1.5.23

• Enhanced certificate validation with IP-based logic
• Improved URL parsing for hostname extraction
• Added comprehensive unit tests with mocking
• Created detailed documentation with Sphinx/ReadTheDocs

Earlier versions

• See git history for detailed changes