Yandex Lockbox Client

This library is a simple client for working with Yandex Lockbox over REST API, simplifying work with secrets and allowing you to work with them in the OOP paradigm.

Supports two modes: synchronous and asynchronous.

Full library documentation link

Supported Python versions:

• 3.10
• 3.11
• 3.12

Dependencies:

• Pydantic V2
• Crypthography
• PyJWT
• Requests

Extra dependencies:

• aiohttp

Currently, the following operations are not supported by the library:

• List secret access bindings
• Set secret access bindings
• Update secret access bindings
• List secret operations

In the near future release:

• Tests
• Async client implementation
• Implement access bindings methods and view operations
• Ansible action and lookup plugins

Install

Installing via pip:

pip install yc-lockbox

Also, you can install from source with:

git clone https://github.com/akimrx/python-yc-lockbox
cd python-yc-lockbox make install

For async mode support use

pip install yc-lockbox[aio]

Usage

• Authenticate via your OAuth token

fromyc_lockboximportYandexLockboxClientlockbox=YandexLockboxClient("y0_xxxxxxxxxxxx")

• Authenticate via IAM token

If you pass a IAM token as credentials, you need to take care of the freshness of the token yourself.

fromyc_lockboximportYandexLockboxClientlockbox=YandexLockboxClient("t1.xxxxxx.xxxxxxx")

• Authenticate using service account key

importjsonfromyc_lockboximportYandexLockboxClientwithopen("/path/to/key.json", "r") askeyfile:
credentials=keyfile.read()
lockbox=YandexLockboxClient(credentials)

Create a new secret

fromyc_lockboximportYandexLockboxClient, INewSecret, INewSecretPayloadEntrylockbox=YandexLockboxClient("oauth_or_iam_token")
create_secret_operation=lockbox.create_secret(
INewSecret(
folder_id="b1xxxxxxxxxxxxxx",
name="my-secret",
version_payload_entries=[
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value".encode()),
],
)
)
ifcreate_secret_operation.done:
new_secret=create_secret_operation.resourceprint(new_secret.id)
new_secret.deactivate()

Get secret from Lockbox

fromyc_lockboximportYandexLockboxClient, Secretlockbox=YandexLockboxClient("oauth_or_iam_token")
secret: Secret=lockbox.get_secret("e6qxxxxxxxxxx")
print(secret.status, secret.name)
payload=secret.payload(version_id=secret.current_version.id) # id is optional, by default using current versionprint(payload.entries) # list of SecretPayloadEntry objects# Direct accessentry=payload["secret_entry_1"] # or payload.get("secret_entry_1")print(entry.text_value) # return MASKED value like ***********print(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()

Add new version of secret

fromyc_lockboximportYandexLockboxClient, Secret, INewSecretVersion, INewSecretPayloadEntrylockbox=YandexLockboxClient("oauth_or_iam_token")
secret: Secret=lockbox.get_secret("e6qxxxxxxxxxxxx")
secret.add_version(
INewSecretVersion(
description="a new version",
base_version_id=secret.current_version.id,
payload_entries= [
INewSecretPayloadEntry(key="secret_entry_1", text_value="secret_entry_text_value"),
INewSecretPayloadEntry(key="secret_entry_2", binary_value="secret_entry_binary_value"),
]
)
)
# alternativelockbox.add_secret_version(
"secret_id",
version=INewSecretVersion(
description="a new version",
base_version_id=secret.current_version.id,
payload_entries=[INewSecretPayloadEntry(...), INewSecretPayloadEntry(...)]
)
)

Other operations with secret

fromyc_lockboximportYandexLockboxClientlockbox=YandexLockboxClient("oauth_or_iam_token")
forsecretinlockbox.list_secrets(folder_id="b1xxxxxxxxxx", iterator=True):
print(secret.name, secret.status)
secret.deactivate()
secret.activate()
forversioninsecret.list_versions(iterator=True): # if iterator=False returns paginated list with ``next_page_token``ifversion.id!=secret.current_version.id:
version.schedule_version_destruction()
version.cancel_version_destruction()

Async mode

The client supports asynchronous mode using the aiohttp library. The signature of the methods does not differ from the synchronous implementation.

Just import async client:

fromyc_lockboximportAsyncYandexLockboxClientlockbox=AsyncYandexLockboxClient("oauth_or_iam_token")

Alternative:

fromyc_lockboximportYandexLockboxFacadelockbox=YandexLockboxFacade("oauth_or_iam_token", enable_async=True).client

Example usage:

secret: Secret=awaitlockbox.get_secret("e6qxxxxxxxxxx")
payload=awaitsecret.payload()
print(payload.entries) # list of SecretPayloadEntry objects# Direct accessentry=payload["secret_entry_1"] # or payload.get("secret_entry_1")print(entry.text_value) # return MASKED value like ***********print(entry.reveal_text_value()) # similar to entry.text_value.get_secret_value()# Async iteratorssecret_versions=awaitsecret.list_versions(iterator=True)
asyncforversioninsecret_versions:
ifversion.id!=secret.current_version.id:
awaitversion.schedule_version_destruction()
awaitversion.cancel_version_destruction()