Python SDK

Keeperシークレットマネージャー向けPython SDKの詳細情報

ダウンロードとインストール

PIPによるインストール

pip3 install -U keeper-secrets-manager-core

ソースコード

Pythonのソースコードは、GitHubリポジトリで入手できます。

SDKの使用

初期化

トークンのみを使用して新しい構成ファイルを生成するには、トークンをバインドし、config.jsonに完全に読み込むために少なくとも1回の読み取り操作が必要です。

シークレットマネージャー

SecretsManager(token, config)
# トークンのみを使用して（後で使用するために）設定を生成するには、
# トークンをバインドするアクセス操作が少なくとも1回必要です
#get_secrets(uids=None)

例

パラメータ	必須	説明	型
token	はい	ワンタイムアクセストークン	String
config	はい	ストレージの設定	KeyValueStorage

シークレットの取得

シークレットの取得

get_secrets(uids=None)

例: すべてのシークレットを取得

例: フィルタを使用してシークレットを取得

パラメータ	型	必須	デフォルト	説明
uids	String[]	オプション	None	取得するUIDレコード

戻り値

型: Record[]

Keeperのすべてのレコード、または指定されたUIDを持つレコード。

シークレットから値を取得

パスワードを取得

Keeperシークレットマネージャーからシークレットを取得すると、このショートカットでそのシークレットのパスワードを取得します。

パスワードを取得

secret.field('password', single=True)

例

標準フィールドを取得

フィールド

secret.field(field_type, single=False, value=None)

例

パラメータ	型	必須	デフォルト	説明
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

フィールドタイプはKeeperレコードタイプに基づきます。利用可能なフィールドの詳細な一覧については、コマンダーで record-type-info コマンドをご参照ください。

カスタムフィールドを取得

カスタムフィールド

secret.custom_field(label, field_type=None, single=False, value=None)

例

パラメータ	型	必須	デフォルト	説明
label	String	はい		カスタムフィールドのラベル
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

カスタムフィールドとは、レコードタイプの定義に含まれていないが、ユーザーが追加できるフィールドのことです。

同じカスタムタイプの複数のフィールドを1つのレコードに表示することができます。これらのフィールドを区別するには、フィールドラベルが必要です。

戻り値

型: StringまたはString[]

フィールドの1つまたは複数の値。 single=Trueオプションを指定した場合のみ、単一の値になります。

タイトルによってシークレットを取得

タイトルによるレコード

# 一致するレコードをすべて取得
get_secrets_by_title(record_title)

# 最初に一致するレコードのみを取得
get_secret_by_title(record_title)

例

パラメータ	型	必須	説明
record_title	String	はい	検索するレコードタイトル

Keeper表記法を使用して値を取得

Get Notation

get_notation(query)

例

Keeper表記法の形式と機能については、Keeper表記法のページをご参照ください。

パラメータ	型	必須	デフォルト	説明
query	String	はい		指定したフィールドの値を取得するためのKeeper表記法を使用したクエリ

戻り値

型: string or string[]

照会したフィールドの値

TOTPコードを取得

TOTPコードを取得

get_totp_code(url)

例

パラメータ	型	必須	デフォルト	説明
url	String	はい		TOTP Url

シークレットを更新

レコード更新コマンドは、成功時にローカルのレコードデータ (特にレコードリビジョンの更新) を更新しないため、既に更新されたレコードを継続的に更新してもリビジョンの不一致により失敗となります。各更新バッチの後に、更新済みのレコードをすべてリロードするようにしてください。

変更をシークレットに保存

シークレットを保存

save(record:KeeperRecord)

例

トランザクションの更新

パラメータ	型	必須	デフォルト	説明
record	KeeperRecord	はい		ストレージとクエリの設定

fieldメソッドを使用してフィールド値を設定します。

利用可能なフィールドの詳細な一覧については、コマンダーで record-type-info コマンドをご参照ください。一部のフィールドは複数の値を持つことができ、その場合は値をリストとして設定できます。

標準フィールド値を更新

フィールド

secret.field(field_type, single=False, value=None)

例

パラメータ	型	必須	デフォルト	説明
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

カスタムフィールド値の更新

カスタムフィールド

secret.custom_field(label, field_type=None, single=False, value=None)

例

パラメータ	型	必須	デフォルト	説明
label	String	はい		カスタムフィールドのラベル
field_type	String	はい		取得するフィールドタイプ
single	boolean	オプション	False	最初の値のみを返す
value	StringまたはString[]	オプション	None	指定すると、フィールドの値を指定値に設定

ランダムなパスワードを生成

パスワードを生成

generate_password(length, lowercase, uppercase, digits, specialCharacters)

例

パラメータ	型	必須	デフォルト
length	int	オプション	64
lowercase	int	オプション	0
uppercase	int	オプション	0
digits	int	オプション	0
specialCharacters	int	オプション	0

各パラメータは、使用する文字の種類の最小数を示します。たとえば、「uppercase」は、使用する大文字の最小数となります。

ファイルのダウンロード

ファイルを保存

file.save_file(file_path, create_folders=False)

例

パラメータ	型	必須	デフォルト	説明
file_path	String	はい		ファイルの保存先のパス
create_folders	boolean	いいえ	False	存在しない場合はfile_pathにフォルダを作成

ファイルのアップロード

ファイルのアップロード

ファイルのアップロード

upload_file(owner_record, file: my_file)

Keeperファイルアップロードオブジェクトを作成

KeeperFileUpload.from_file(path, file_name=None, file_title=None, mime_type=None)

例

ファイルのアップロード

パラメータ	型	必須	説明
owner_record	KeeperRecord	はい	アップロードされたファイルを添付するレコード
file	KeeperFileUpload	はい	アップロードするファイル

ファイルからのKeeperファイルのアップロード

パラメータ	型	必須	デフォルト	説明
path	string	はい		アップロードするファイルへのパス
file_name	string	いいえ	None	アップロード後にKeeperに格納されるファイルの名前
file_title	string	いいえ	None	アップロード後にKeeperに格納されるファイルのタイトル
mime_type	string	いいえ	None	ファイル内のデータの種類。 何も指定しない場合は、「application/octet-stream」が使用されます。

戻り値

型: string

添付ファイルのファイルUID

シークレットの作成

要件

• 共有フォルダのUID

  • 共有フォルダには、シークレットマネージャーアプリケーションからアクセスできる必要があります。

  • あなたとシークレットマネージャーアプリケーションには編集権限が必要です。

  • 共有フォルダには、少なくとも1つのレコードが存在する必要があります。

• 作成されたレコードとレコードのフィールドは正しく書式設定されている必要があります。

  • レコードタイプごとの適切なフィールド形式については、こちらのページをご参照ください。

• TOTPフィールドには、KSM SDK以外で生成されたURLのみを指定できます。

• レコードの作成後は、upload_fileを使用して添付ファイルをアップロードできます。

レコードを作成

secrets_manager.create_secret(folder_uid, record)

パラメータ	型	必須	デフォルト
folder_uid	String	はい
record	KeeperRecord	はい

サブフォルダにレコードを作成

ログインのレコードの例

カスタムタイプの例

戻り値

型: string

新規レコードのレコードUID

シークレットの削除

Python KSM SDKでKeeperボルトのレコードを削除できます。

シークレットの削除

secrets_manager.delete_secret(record_uid)

パラメータ	型	必須
record_uid	string	はい

例

キャッシュ

ネットワークアクセスが失われたときにシークレットにアクセスできなる状況を避けるため、Python SDKを使用してシークレットを暗号化されたファイルでローカルマシンにキャッシュできます。

キャッシュの設定と構成

Python SDKでキャッシュを設定するには、SecretsManager オブジェクトを作成するときにキャッシュポスト関数を含める必要があります。

Python SDKには、KSMCache クラスにデフォルトのキャッシュ機能が含まれており、キャッシュされたクエリをローカルファイルに保存し、復旧機能として使用できます (ネットワーク接続がある場合は常にネットワークデータを優先し、ウェブボルトにアクセスできない場合にのみキャッシュを使用します)。独自のキャッシュ機能を作成することも可能で、KSMCache を出発点として利用できます。例えば、ネットワークアクセスよりもローカルキャッシュを優先し、独自のキャッシュ管理を行う (例: キャッシュデータを5分ごとに更新する) 機能を作成できます。

secrets_manager = SecretsManager(
    token='<One Time Access Token>',
    config=FileKeyValueStorage('ksm-config.json'),
    custom_post_function=KSMCache.caching_post_function
)

KSMCache クラスのデフォルトキャッシュ機能は、常に最後のリクエストのみを保存します。例えば、UID1に対するフィルタリングリクエストがキャッシュされている場合、ネットワーク切断時に同じキャッシュからUID2をリクエストすると、空のレスポンスが返されます (UID2が同じKSMアプリに共有されている場合でも、それがキャッシュされていなければ利用できません)。

キャッシュからのレコード更新 (または新しいレコードの作成) は、キャッシュされたレコードデータを無効にし、同じレコードを連続して更新する操作は失敗します。異なるレコードを修正する場合、バッチ更新は機能します。キャッシュされたレコードを更新した後は、常に get_secrets 関数を呼び出してキャッシュをリフレッシュし、ボルトから新しいレコードリビジョンなどの更新されたメタデータを取得するようにしてください。

独自のキャッシュ関数の作成

まず、次の引数を使用してキャッシュ関数を作成し、post_function を呼び出します。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )
    # ここにカスタムキャッシュ処理を記述 ...

    # 常に KSMHttpResponse オブジェクトを返すようにする
    return ksm_rs

次に、KSMCacheを使用して任意のキャッシュ処理ロジックを実装できます。

以下は基本的なサンプルです。

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.core import KSMCache, KSMHttpResponse
from keeper_secrets_manager_core.storage import FileKeyValueStorage
from http import HTTPStatus

def caching_post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs=True, proxy_url=None
):
    ksm_rs = SecretsManager.post_function(
        url, transmission_key, encrypted_payload_and_signature, verify_ssl_certs
    )

    if ksm_rs.status_code < 400:
        KSMCache.save_cache(transmission_key.key + ksm_rs.data)
        return ksm_rs

    # KSMCache が空の場合がある    
    cached_data = KSMCache.get_cached_data()
    cached_transmission_key = cached_data[:32]
    transmission_key.key = cached_transmission_key
    data = cached_data[32 : len(cached_data)]

    new_rs = KSMHttpResponse(HTTPStatus.OK, data, None)
    return new_rs


secrets_manager = SecretsManager(
    config=FileKeyValueStorage('ksm-config.json'),
    verify_ssl_certs=False,
    custom_post_function=caching_post_function
)

フォルダ

フォルダは完全なCRUD (作成、読み取り、更新、削除操作) をサポートしています。

フォルダの読み取り

フォルダの完全な階層構造をダウンロードします。

get_folders()

レスポンス

型: List[KeeperFolder]

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
folders = secrets_manager.get_folders()

フォルダの作成

CreateOptions とフォルダ名の指定が必要です。CreateOptions はフォルダのUIDパラメータ (共有フォルダのUID) が必須ですが、サブフォルダのUIDはオプションであり、指定されていない場合は、通常の新しいフォルダが親 (共有フォルダ) の直下に作成されます。サブフォルダは、親の共有フォルダの直接の下位オブジェクトである必要はありません。親フォルダから何階層も深い位置にサブフォルダを作成することができます。

create_folder(create_options:CreateOptions, folder_name: str, folders=None)

パラメータ	型	必須	デフォルト	説明
create_options	CreateOptions	はい		親およびサブフォルダのUID
folder_name	str	はい		フォルダ名
folders	List[KeeperFolder]	いいえ	None	CreateOptionsで作成した親とサブフォルダの検索に使用するフォルダのリスト

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
co = CreateOptions(folder_uid="[SHARED_FOLDER_UID]", subfolder_uid="")
new_folder_uid = secrets_manager.create_folder(co, "new_folder")

フォルダの更新

フォルダのメタデータ (現在はフォルダ名のみ) を更新します。

update_folder(folder_uid: str, folder_name: str, folders=None)

パラメータ	型	必須	デフォルト	説明
folder_uid	str	はい		フォルダのUID
folder_name	str	はい		新しいフォルダ名
folders	List[KeeperFolder]	いいえ	None	親フォルダの検索に使用するフォルダのリスト

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.update_folder("[FOLDER_UID]", "new_folder_name")

フォルダの削除

フォルダのリストを削除します。空でないフォルダを削除するには、force_deletion フラグを使用します。

forceDeletion を使用する場合は、親フォルダと子フォルダのUIDを一緒に送信しないようにしてください。削除する順序によっては、エラーが発生する可能性があります。たとえば、親が子を先に強制削除した場合などです。リストが必ずしもFIFO順で処理される保証はありません。

ボルトに存在しないフォルダのUIDやKSMアプリケーションで共有されていないフォルダのUIDはエラーになりません。

delete_folder(folder_uids:List[str], force_deletion: bool = False)

パラメータ	型	必須	デフォルト	説明
folder_uids	List[str]	はい		フォルダUIDリスト
force_deletion	bool	いいえ	False	空でないフォルダを強制的に削除

使用例

from keeper_secrets_manager_core import SecretsManager
from keeper_secrets_manager_core.storage import FileKeyValueStorage

secrets_manager = SecretsManager(config=FileKeyValueStorage('ksm-config.json'))
secrets_manager.delete_folder(["[FOLDER_UID1]", "[FOLDER_UID2]"], True)