API Reference
This page contains the complete API reference for the getSecrets package.
Main Module
- getSecrets.get_home()[source]
Determines the home directory of the current user based on the operating system.
This function checks the operating system and retrieves the appropriate environment variable that represents the user’s home directory. For Windows, it uses the USERPROFILE environment variable. For other operating systems, it uses the HOME environment variable.
- Returns:
The path to the user’s home directory as a string, or None if it cannot be determined.
- Return type:
Optional[str]
- getSecrets.get_config()[source]
Parses and loads the Vault configuration file based on the operating system.
This function determines the correct location of the Vault configuration file depending on the operating system being used. It attempts to load the file’s contents into a dictionary. If the configuration file is not found, it logs an error and falls back to a default location, creating the directory if necessary. If the configuration is successfully loaded, the configuration file path is added to the resulting dictionary.
- Returns:
A dictionary containing the Vault configuration data, or None if no configuration file is found.
- Return type:
dict or None
- getSecrets.get_certs(base_url)[source]
Retrieve the certificate bundle file path for a given base URL.
This function determines the proper certificate bundle file to use, based on the provided base URL and the system’s configuration. If no valid certificate bundle is found, the function disables certificate verification and issues a warning about insecure work.
- Parameters:
base_url – A string representing the base URL for which the certificate bundle is to be resolved.
- Returns:
The file path to the certificate bundle if found and valid; otherwise, False if no valid certificate bundle is available and insecure connections are allowed.
- getSecrets.get_secret(id: str, repo: str = 'secret') dict[source]
Fetches a secret from a secure vault based on the provided ID and repository name. If the secret exists in the internal configuration cache, it is retrieved directly; otherwise, a request is sent to the vault endpoint to fetch the secret.
- Parameters:
- Returns:
A dictionary containing the retrieved secret data. Returns an empty dictionary if the request fails or the secret is not found.
- Return type:
- getSecrets.get_user_pwd(id: str, repo: str = 'secret') tuple[source]
Retrieve the username and password associated with a given id. The function first checks if the credentials are available in a local configuration. If not, it communicates with a Vault server to fetch the credentials. The credentials are expected to be stored as username and password.
- Parameters:
- Returns:
A tuple containing the username and password. If the credentials are not found or if an error occurs, returns a tuple of two None values.
- Return type:
- getSecrets.list_secret(repo: str = 'secret')[source]
Lists the secret keys from a configured Vault repository.
This function connects to a Vault service, fetches the metadata for the specified secret repository, and extracts the secret keys listed. If the response is successful, it returns the list of secret keys. Otherwise, it logs an error and returns None.
- getSecrets.upd_secret(id: str, data, repo: str = 'secret')[source]
Updates a secret with the given id and data either in the local configuration file or in the defined secret repository (e.g., Vault). If the secret exists in the local configuration, it updates and persists the changes locally. Otherwise, it interacts with the Vault API to update the secret remotely based on the provided repository.
- Parameters:
- Returns:
HTTP status code (e.g., 200) if the update was successful, or None on failure.
- Return type:
int or None
Functions
get_secret()
- getSecrets.get_secret(id: str, repo: str = 'secret') dict[source]
Fetches a secret from a secure vault based on the provided ID and repository name. If the secret exists in the internal configuration cache, it is retrieved directly; otherwise, a request is sent to the vault endpoint to fetch the secret.
- Parameters:
- Returns:
A dictionary containing the retrieved secret data. Returns an empty dictionary if the request fails or the secret is not found.
- Return type:
Description:
Retrieves a secret from HashiCorp Vault or local configuration file.
Parameters:
id (str) - The ID of the secret to retrieve
repo (str) - The name of the secrets repository (default: ‘secret’)
Returns:
dict - A dictionary containing key-value pairs from the secret, or an empty dict if retrieval fails
Behavior:
First checks if the secret exists in the local configuration file
If not found locally, queries the Vault server
Automatically handles certificate validation
Falls back to insecure mode if certificates are not available
Example:
secret = get_secret('database-config')
# Returns: {'host': 'db.example.com', 'port': 5432}
get_user_pwd()
- getSecrets.get_user_pwd(id: str, repo: str = 'secret') tuple[source]
Retrieve the username and password associated with a given id. The function first checks if the credentials are available in a local configuration. If not, it communicates with a Vault server to fetch the credentials. The credentials are expected to be stored as username and password.
- Parameters:
- Returns:
A tuple containing the username and password. If the credentials are not found or if an error occurs, returns a tuple of two None values.
- Return type:
Description:
Retrieves username and password from a secret.
Parameters:
id (str) - The ID of the secret to retrieve
repo (str) - The name of the secrets repository (default: ‘secret’)
Returns:
tuple - A tuple of (username, password) or (None, None) if retrieval fails or fields don’t exist
Behavior:
Retrieves the secret using the same logic as get_secret()
Extracts ‘username’ and ‘password’ fields if they exist
Returns (None, None) if either field is missing
Example:
username, password = get_user_pwd('postgres-creds')
# Returns: ('dbuser', 'securepassword123')
list_secret()
- getSecrets.list_secret(repo: str = 'secret')[source]
Lists the secret keys from a configured Vault repository.
This function connects to a Vault service, fetches the metadata for the specified secret repository, and extracts the secret keys listed. If the response is successful, it returns the list of secret keys. Otherwise, it logs an error and returns None.
Description:
Lists all available secret IDs in a repository.
Parameters:
repo (str) - The name of the secrets repository (default: ‘secret’)
Returns:
list - A list of secret IDs (keys) available in the repository, or (None, None) on error
Behavior:
Queries the Vault metadata endpoint for the specified repository
Returns the list of available secret keys
Does not retrieve actual secret values
Example:
secrets = list_secret()
# Returns: ['database-config', 'api-keys', 'admin-creds']
upd_secret()
- getSecrets.upd_secret(id: str, data, repo: str = 'secret')[source]
Updates a secret with the given id and data either in the local configuration file or in the defined secret repository (e.g., Vault). If the secret exists in the local configuration, it updates and persists the changes locally. Otherwise, it interacts with the Vault API to update the secret remotely based on the provided repository.
- Parameters:
- Returns:
HTTP status code (e.g., 200) if the update was successful, or None on failure.
- Return type:
int or None
Description:
Updates an existing secret with new data.
Parameters:
id (str) - The ID of the secret to update
data (dict) - The new data to store in the secret
repo (str) - The name of the secrets repository (default: ‘secret’)
Returns:
int - HTTP status code (200 on success), or (None, None) on error
Behavior:
If the secret exists in local config, updates the local YAML file
Otherwise, retrieves current version from Vault
Uses Check-And-Set (CAS) to safely update the secret
Prevents concurrent modification conflicts
Example:
new_data = {'host': 'newdb.example.com', 'port': 5432}
status = upd_secret('database-config', new_data)
# Returns: 200
Configuration
Configuration File Location
The package looks for configuration in the following locations (in order):
~/.config/.vault/vault.yml/etc/vault/vault.yml
Configuration File Format
vault:
token: "your-vault-token"
vault_addr: "https://vault.example.com:8200"
certs: "~/path/to/bundle.pem"
# Optional local secrets
secret-id:
key1: value1
key2: value2
Certificate Validation
The package uses the following logic for certificate validation:
If connecting to internal network (192.168.x.x): Uses custom certificate bundle
If connecting to public network: Uses system certificates (via certifi)
If no certificates found: Works in insecure mode (with warning)
Custom Certificate Bundle:
The bundle.pem file should contain certificates in this order:
Vault server certificate
Intermediate CA certificate
Root CA certificate
Logging
The package uses Python’s standard logging module with INFO level by default.
Log Format:
MM/DD/YYYY HH:MM:SS AM/PM message
Example Logs:
02/03/2026 10:30:45 AM No vault bundle.pem found at /path/to/cert - working insecure !!
02/03/2026 10:30:46 AM Vault api error <Response [403]>
Exceptions and Error Handling
The package handles errors gracefully:
Configuration Not Found: Logs error and exits with code 1
Certificate Not Found: Logs warning and continues in insecure mode
HTTP Errors: Logs error and returns empty dict or None values
Missing Fields: Returns None values for get_user_pwd()
System Exit Conditions:
The package will call sys.exit(1) only if:
No configuration file found in any expected location
All other errors are handled gracefully with logging and error return values.
Type Hints
While the current implementation uses basic type hints in docstrings, the functions accept and return:
Function |
Parameters |
Returns |
|---|---|---|
get_secret() |
id: str, repo: str |
dict |
get_user_pwd() |
id: str, repo: str |
tuple[str | None, str | None] |
list_secret() |
repo: str |
list[str] | tuple[None, None] |
upd_secret() |
id: str, data: dict, repo: str |
int | tuple[None, None] |