Password store

Version 1 (UNSTABLE): cmk.password_store.v1_unstable

Warning

This version of the API is work in progress and not yet stable. It is not recommended to use this version in production systems.

However: we do intend to stabilize this API version in the future and release it, so you are encouraged to experiment and give us feedback.

Scope

This API provides functionality to be used by server-side programs running on the Checkmk server. It is written with special agents and active checks in mind – we do not guarantee they work in other circumstances.

This is the first version of the password store API.

class Secret(value, /)

Bases: Generic

A class to hold secrets.

This class is a simple protection against accidental logging of secrets:

>>> s = Secret("s3cr37!")
>>> # it will not show in strings or reprs:
>>> print(s)
'****'
>>> repr(s)
'Secret(****)'
>>> # but you can still get the value:
>>> s.reveal()
's3cr37!'
parser_add_secret_option(parser, /, *, short=None, long, help, required)

Add mutually exclusive secret options to an argument parser.

Creates two mutually exclusive options for handling secrets:

  • A direct secret option using the provided long an short names. This is intended for debuggnig purposes, but keep in mind that using it will expose the actual secret in the commandline.

  • An option to provide the password store reference using the long name with “-id” suffix: ‘<long>-id’. This should be used in the commandline that is created by the server side calls plugin. This prevents the actual secret from showing on the commandline or in the fetcher configuration.

Parameters:

  • parser (ArgumentParser) – The argument parser to add options to

  • short (str | None) – Optional short option name (e.g., “-s”) for convenience. It will only be used for the direct option. Must start with exactly one “-“.

  • long (str) – Long option name (must start with “–”, e.g., “–password”)

  • help (str) – Help text for the direct secret option

  • required (bool) – Whether one of the two options must be provided

Raises:

ValueError – If long option doesn’t start with “–”

Return type:

None

Example

To create the options: –password, -p, –password-id

>>> OPTION_NAME = "password"  # reuse this for `resolve_secret_option`
>>> parser = argparse.ArgumentParser()
>>> parser_add_secret_option(
...     parser,
...     short="-p",
...     long=f"--{OPTION_NAME}",
...     help="Database password",
...     required=True
... )
resolve_secret_option(args, option_name)

Resolves a secret option from the argument parser namespace.

Depending what “long” option you used in parser_add_secret_option, this function will either dereference the secret given by “–<LONG>-id” or use the explicit secret given by “–<LONG>”.

Parameters:
Raises:

TypeError – If neither of the two options where specified.

Return type:

Secret[str]

Example usage (assuming you created the options using parser_add_secret_option()):

#!/usr/bin/env python3 … args = parser.parse_args() secret = resolve_secret_option(args, OPTION_NAME)

dereference_secret(raw, /)

Look up the password with id <id> in the file <file> and return it.

Raises:

PasswordStoreError – If the password store cannot be loaded or the password id is not found.

Parameters:

raw (str) – A string of the form “<id>:<file>” where <file> is the path to the password store file and <id> is the identifier of the password in that store.

Return type:

Secret[str]

Returns:

The password as found in the password store.

exception PasswordStoreError

Bases: RuntimeError

class PasswordStore(secret, /)

Bases: object

A password store that can load and save passwords in an encrypted file.

This is not intended to be used by plugins directly!

get_store_secret()

Read the main secret of the password store.

This is not intended to be used by plugins directly!

Raises:

PasswordStoreError – If the secret file cannot be determined.

Return type:

Secret[bytes]

Returns:

The master secret as bytes or None if no such secret exists.