Secrets Core

chaos.lib.secrets

Module for handling secret management operations such as adding/removing keys, editing secrets, and printing secrets.

gatherImportSec(payload)

Checks if confirmation is needed for importing keys.

Parameters:

Name	Type	Description	Default
payload	SecretsImportPayload	The payload containing import context.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: A request for user confirmation if required, else None.

gatherRotateAdd(payload)

Checks if confirmation is needed for rotating/adding keys.

Parameters:

Name	Type	Description	Default
payload	SecretsRotatePayload	The payload containing rotation options and context.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: A request for user confirmation if required, else None.

gatherRotateRemove(payload)

Checks if confirmation is needed for rotating/removing keys.

Parameters:

Name	Type	Description	Default
payload	SecretsRotatePayload	The payload containing rotation options and context.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: A request for user confirmation if required, else None.

gatherSetShamir(payload)

Checks if confirmation is needed for setting/removing Shamir threshold.

Parameters:

Name	Type	Description	Default
payload	SecretsSetShamirPayload	The payload containing shamir settings context.	required

Returns:

Type	Description
DataGatherRequest | None	DataGatherRequest | None: A request for user confirmation if required, else None.

handleExportSec(payload, global_config)

Exports secrets via a resolved provider.

Parameters:

Name	Type	Description	Default
payload	SecretsExportPayload	The payload details for the export.	required
global_config	dict | DictConfig	The global configuration.	required

Returns:

Name	Type	Description
ResultPayload	ResultPayload[Any]	The result payload of the export operation.

handleImportSec(payload, global_config)

Imports secrets via a resolved provider.

Parameters:

Name	Type	Description	Default
payload	SecretsImportPayload	The payload details for the import.	required
global_config	dict | DictConfig	The global configuration.	required

Returns:

Name	Type	Description
ResultPayload	ResultPayload	The result payload of the import operation.

handleRotateAdd(payload)

Adds a new key to the sops config file and (if -u), updates all secrets.

Parameters:

Name	Type	Description	Default
payload	SecretsRotatePayload	The payload defining the rotation target and context.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: The result payload of the rotation add operation.

Notes

Check secret_backends/utils.py for shared functions and their docs.

handleRotateRemove(payload)

Removes a key from the sops config file and (if -u), updates all secrets.

Parameters:

Name	Type	Description	Default
payload	SecretsRotatePayload	The payload defining the rotation removal target and context.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: The result payload of the rotation remove operation.

handleSecCat(payload)

Decrypts the secrets file and returns the values of the specified keys.

Parameters:

Name	Type	Description	Default
payload	SecretsCatPayload	The payload detailing the keys to extract.	required

Returns:

Type	Description
ResultPayload[dict[Literal['values'], list[tuple[str, str]]]]	ResultPayload[dict[Literal["values"], list[tuple[str, str]]]]: The result payload containing a list of values found for the keys.

handleSecEdit(payload)

Opens the secrets file in SOPS for editing.

Parameters:

Name	Type	Description	Default
payload	SecretsEditPayload	The payload containing context for editing secrets.	required

Returns:

Type	Description
ResultPayload[SecEditData]	ResultPayload[SecEditData]: The result payload containing related file paths and settings.

handleSecPrint(payload)

Decrypts the secrets file and returns the decrypted content as a string.

Parameters:

Name	Type	Description	Default
payload	SecretsPrintPayload	The payload indicating what to print.	required

Returns:

Type	Description
ResultPayload[dict[str, str]]	ResultPayload[dict[str, str]]: The result payload containing the decrypted content under 'dec'.

handleSetShamir(payload)

Sets or removes the Shamir threshold for a given creation rule in the sops config file.

Parameters:

Name	Type	Description	Default
payload	SecretsSetShamirPayload	The payload containing the shamir configuration details.	required

Returns:

Type	Description
ResultPayload[None]	ResultPayload[None]: The result payload indicating success or failure.

listFp(payload)

Lists all keys of a certain type from the sops config file.

Parameters:

Name	Type	Description	Default
payload	SecretsListPayload	The payload defining the target type and context.	required

Returns:

Type	Description
ResultPayload[set[str]]	ResultPayload[set[str]]: The result payload containing a set of key fingerprints or names.

Raises:

Type	Description
FileNotFoundError	If no sops config file is found.

chaos.lib.secret_backends.utils

Utility functions for handling SOPS file operations, provider resolution, and decryption workflows.

decrypt_secrets(secrets_file, sops_file, config, context)

Decrypts a secrets file using SOPS and the active environment context.

Delegates decryption to a resolved secret provider plugin if available; otherwise, it falls back to directly invoking the SOPS CLI tool.

Parameters:

Name	Type	Description	Default
secrets_file	str	The path to the encrypted secrets file.	required
sops_file	str	The path to the SOPS configuration file.	required
config	dict | DictConfig	The global chaos configuration.	required
context	SecretsContext	The secrets context detailing ephemeral settings.	required

Returns:

Name	Type	Description
str	ResultPayload[str]	The raw decrypted text content.

Raises:

Type	Description
EnvironmentError	If the 'sops' CLI tool is missing.
PermissionError	If Vault authentication fails.
RuntimeError	If the SOPS decryption process fails.
FileNotFoundError	If 'sops' cannot be found in the system PATH.

flatten(items)

Turns a concatenated or nested list into a single flat generator.

Parameters:

Name	Type	Description	Default
items	Iterable	An iterable of items or nested lists.	required

Yields:

Name	Type	Description
Any	Any	Unpacked items from the nested iterables.

get_sops_files(sops_file_override, secrets_file_override, team)

Gets the appropriate SOPS and secrets files based on overrides, team context, and global configuration.

Parameters:

Name	Type	Description	Default
sops_file_override	str | None	A path overriding the default SOPS configuration file.	required
secrets_file_override	str | None	A path overriding the default secrets file.	required
team	str | None	The team context (e.g., 'company.team.group').	required

Returns:

Type	Description
tuple[str, str, DictConfig]	tuple[str, str, dict | DictConfig]: A tuple containing: - The path to the secrets file. - The path to the SOPS configuration file. - The global configuration mapping.

Raises:

Type	Description
ValueError	If the team string is malformed or if there are path traversal attempts.
FileNotFoundError	If the specified team directory or override files are not found.

handleUpdateAllSecrets(context)

Updates encryption keys for all related secret files and rambles.

Iterates over the main secrets file and any associated ramble files to apply sops updatekeys, ensuring all files reflect the current key configuration.

Parameters:

Name	Type	Description	Default
context	SecretsContext	The execution context defining file overrides and team structure.	required

Returns:

Type	Description
tuple[list[str], list[str]]	tuple[list[str], list[str]]: A tuple containing a list of informational messages and a list of error messages encountered during the update.

mac_ram_disk()

Creates an ephemeral RAM Disk on macOS Yields: The mount point of the RAM Disk

setup_gpg_keys(gnupghome)

Sets up a temporary GNUPGHOME directory to keep imported GPG keys ephemeral.

Copies existing private keys and trustdb from the user's main GNUPGHOME (if present) to the temporary directory, and imports public keys so they are available in the ephemeral context.

Parameters:

Name	Type	Description	Default
gnupghome	Path | TemporaryDirectory	The temporary directory path to configure.	required

setup_pipe(token)

Creates a Unix pipe or FIFO to pass a token securely.

Parameters:

Name	Type	Description	Default
token	str	The secret token string to pass.	required

Returns:

Type	Description
tuple[str, int | None]	tuple[str, int | None]: The file path to access the pipe, and the file descriptor (FD) number if applicable.

setup_vault_keys(vaultAddr, keyPath)

Reads and validates a Vault token for exporting. Constructs a formatted string containing the Vault address and token for storing in an external provider. Args: vaultAddr (str): The HashiCorp Vault server address. keyPath (Path): The file path containing the Vault token.

Returns:

Name	Type	Description
str	str	The formatted key content string with address and token.

Raises:

Type	Description
EnvironmentError	If the 'vault' CLI tool is missing.
ValueError	If the key format is invalid.

zero_out(s)

Overwrites the contents of a string in memory to reduce the risk of sensitive data lingering. Args: s (str): The string to be zeroed out. Returns: None

chaos.lib.secret_backends.crypto

Cryptographic utilities for key validation, extraction, and ephemeral environment setup.

check_vault_auth()

Checks if the current HashiCorp Vault authentication is valid.

Verifies the presence and validity of the VAULT_ADDR and VAULT_TOKEN environment variables.

Returns:

Type	Description
tuple[bool, str]	tuple[bool, str]: A tuple where the first element is a boolean indicating whether authentication is valid, and the second element is an accompanying message.

decompress(encoded_data)

Decompresses base85-encoded zlib data back to bytes.

Parameters:

Name	Type	Description	Default
encoded_data	str	The base85-encoded, compressed string.	required

Returns:

Name	Type	Description
bytes	bytes	The decompressed original raw bytes data.

Raises:

Type	Description
RuntimeError	If data decoding or decompression fails.

extract_age_keys(key_content)

Extracts age public and private keys from a text block.

Parameters:

Name	Type	Description	Default
key_content	str	The multiline string content containing the age keys.	required

Returns:

Type	Description
tuple[list[str], list[str], list[str]]	tuple[list[str], list[str], list[str]]: A tuple containing lists of public keys, secret keys, and headers found.

extract_gpg_keys(fingerprints)

Extracts and encodes GPG secret keys for export.

Exports the secret keys for the given fingerprints, compresses them using zlib, and encodes them into a custom ASCII-armored block.

Parameters:

Name	Type	Description	Default
fingerprints	list[str]	A list of GPG fingerprints to export.	required

Returns:

Name	Type	Description
str	str	The compressed and encoded secret key block.

Raises:

Type	Description
RuntimeError	If the GPG export operation fails or no keys are found.

is_valid_age_key(pubKey)

Validates a public age key.

Parameters:

Name	Type	Description	Default
pubKey	str	The public age key string to validate.	required

Returns:

Name	Type	Description
bool	bool	True if the key matches the age public key format, False otherwise.

is_valid_age_secret_key(secKey)

Validates a private (secret) age key.

Parameters:

Name	Type	Description	Default
secKey	str	The secret age key string to validate.	required

Returns:

Name	Type	Description
bool	bool	True if the key matches the age secret key format, False otherwise.

is_valid_fp(fingerprint)

Checks for GPG fingerprint validity.

Validates if the provided string is a valid 40-character hexadecimal GPG fingerprint.

Parameters:

Name	Type	Description	Default
fp	str	The fingerprint string to validate.	required

Returns:

Name	Type	Description
bool	bool	True if it is a valid GPG fingerprint, False otherwise.

is_vault_in_use(sops_file_path)

Checks if HashiCorp Vault is configured in the given SOPS file.

Parameters:

Name	Type	Description	Default
sops_file_path	str	The file path to the SOPS configuration file.	required

Returns:

Name	Type	Description
bool	bool	True if a Vault key group is found in the configuration, False otherwise.

pgp_exists(fingerprint)

Checks if a GPG fingerprint exists in the local keyring.

Parameters:

Name	Type	Description	Default
fp	str	The GPG fingerprint to check.	required

Returns:

Name	Type	Description
bool	bool	True if the key exists locally, False otherwise.