SDKとしてのコマンダーCLI

Python開発者向けのKeeperコマンダーCLIライブラリの利用方法

インストール

以下は、Pythonの仮想環境で依存関係を分離しつつ、ソースコードからコマンダーを開発・テストする手順です。コマンダーCLIはライブラリとして利用することも、必要に応じてCLIのソースコードをカスタマイズすることも可能です。

コマンダーリポジトリをクローンする

Keeper-Security/CommanderのGitHubリポジトリをローカルマシンにクローンします。

git clone https://github.com/Keeper-Security/Commander
cd Commander

「master」ブランチは本番リリースと同期されます。「release」ブランチは今後のリリースに対応しています。任意で「release」ブランチに切り替えるには、以下を実行します。

git checkout release

Pythonをインストールする

python.orgから最新のPython3をインストールします。

仮想環境を作成して有効にする

macOS / Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
.\venv\Scripts\activate

依存関係をインストールし、開発モードでセットアップする

pip install -r requirements.txt
pip install -e .

オプションのメール依存関係

OAuth、SendGrid、AWS SES などのメールプロバイダーに対応するには、以下のオプション依存関係をインストールします。

pip install -e '.[email]'

セットアップ完了

コマンダーCLIを起動できるようになりました。

keeper shell

認証プロセスの詳細についてはログインのページをご参照ください。利用できるコマンドのページもあわせてご確認ください。

---

Pythonコード

認証

SDKを使ってKeeperコマンダーにサインインするには、主に2つの方法があります。

手動認証: ユーザー名を入力すると、コマンダーからログインプロンプトが表示されます。ユーザーが認証を完了すると、プログラムの処理が続行されます。

from keepercommander.params import KeeperParams
from keepercommander import api

params = KeeperParams()
params.user = input('User email: ')
api.login(params) # Initiates login prompts
api.sync_down(params)

自動認証: ログイン状態維持の構成を作成した際に生成された config.json ファイルを使用します。設定ファイルが有効であれば、プログラムはコマンダーにプロンプトなしでサインインします。設定ファイルが無効または期限切れの場合は、ログインプロンプトに戻ります。

from keepercommander.__main__ import get_params_from_config

params = get_params_from_config("{{path_to_config_file}}")

---

ボルト操作

Pythonスクリプト内でbash形式のCLIコマンドを直接実行するには、keepercommander ライブラリの cli パッケージをインポートし、do_command 関数を使用します。

from keepercommander.__main__ import get_params_from_config
from keepercommander import cli

# Login
params = get_params_from_config("{{path_to_config_file}}")

# Execute command
cli.do_command(params, "{{cli_command}}")

do_command 関数は、単独のCLIコマンドを実行するときに便利です。api.login() や api.sync_down() を使わずに実行することもできますが、戻り値は取得できません。Python内でオブジェクトを直接取得する用途には向きません。

戻り値を返すPython関数は、keepercommanderモジュール配下にあり、利用前に api.login() と api.sync_down() の実行が必要です。api.pyパッケージにも便利な関数が多く、以下の例ではその一部を紹介します。

from keepercommander.__main__ import get_params_from_config
from keepercommander import api

# Login
params = get_params_from_config("{{path_to_config_file}}")
api.login(params)
api.sync_down(params)

# Search shared folder
shared_folder_name = 'Example Shared Folder'
folder_search = api.search_shared_folders(params, shared_folder_name)

# Get full record dictionaries if folder exists
keeper_folder = None
if folder_search:
    keeper_folder = folder_search[0]
    for record in keeper_folder.records:
        record_obj = api.get_record(params, record["record_uid"])
        print(record_obj.to_dictionary())
else:
    print('No folder found')

---

エンタープライズ利用

エンタープライズデータへのアクセスには、あらかじめ api.query_enterprise() で params.enterprise を設定する必要があります。未設定の場合はデータは取得されません。以下のプログラムは、audit-report コマンドのJSON出力をPython内で直接取得する例です。

from keepercommander.__main__ import get_params_from_config
from keepercommander import api
from keepercommander.commands.aram import AuditReportCommand

from json import loads

# Login
params = get_params_from_config("{{path_to_config_file}}")
api.login(params)
api.sync_down(params)

api.query_enterprise(params) # Populate enterprise

# Get JSON report directly in Python
kwargs = {
    'report_type':'raw', 
    'format':'json',
    'limit':-1,
    'aggregate':['occurences']
}
command_class = AuditReportCommand()
command_run = command_class.execute(params, **kwargs)
report = loads(command_run)

---

バルクコマンドスクリプト

コマンダースクリプトの一般的な活用事例のひとつは、フォルダ内のすべてのレコードに対してコマンドを一括実行することです。

以下のスクリプトは、共有フォルダ・個人用フォルダ・ネストされたフォルダから対象を指定し、フォルダ内の各レコードにコマンド (デフォルトは get) を一括実行します。直接の子レコードだけを対象にするか、子孫レコードまで再帰的に対象にするかを選べます。

スクリプト末尾のコマンドを置き換えて実行すると、選択したフォルダ内のすべてのレコードに対してコマンドを実行できます。

from keepercommander.params import KeeperParams
from keepercommander import api, cli
from keepercommander.subfolder import get_contained_record_uids

# Login
params = KeeperParams()
params.user = input('User email: ')
api.login(params)
api.sync_down(params)

# Basic CLI to collect folders
folder_list = []
folders_complete = False
while not folders_complete:
    folder_prompt = input('Enter a shared folder name / UID (enter / if all shared folders added): ')
    if folder_prompt == '/':
        # Deduplicate
        folder_list = list(set(folder_list))
        print(folder_list)
        confirm = input('Are all these folder names valid? (y/n) ')
        if confirm.lower() == 'y':
            folders_complete = True
        elif confirm.lower() == 'n':
            print('Restarting...')
            folder_list = []
        else:
            print('Wrong input')
    else:
        folder_list.append(folder_prompt)
recursive_complete = False
# Basic CLI to enable/disable recursive execution
while not recursive_complete:
    recursive_input = input('Only execute commands for direct children records (y/n)? ')
    if recursive_input.lower() == 'n':
        children_only = False
        recursive_complete = True
    elif recursive_input.lower() == 'y':
        children_only = True
        recursive_complete = True

# Iterate through collected folder names
keeper_folders = {params.folder_cache[x].name:x for x in params.folder_cache}
selected_folder_uids = []
for folder in folder_list:
    # entry is a UID
    if folder in params.folder_cache:
        selected_folder_uids.append(folder)
    # entry is a name
    elif folder in keeper_folders:
        selected_folder_uids.append(keeper_folders[folder])
    # entry not found
    else:
        print(f'No folder found for {folder}')
    
# Enumerate folder content
record_uids = []
for uid in selected_folder_uids:
    content = get_contained_record_uids(params, uid, children_only)
    for folder in content:
        record_uids += [x for x in content[folder]]
# Deduplicate
record_uids = list(set(record_uids))

# Run bulk command
for uid in record_uids:
    cli.do_command(params,f'get {uid}') # <-- Replace with your command

---

コマンダーCLIの内部クラスや関数を活用すれば、CLIの全機能を利用できます。レコードの検索、チームの作成、フォルダの共有などの例を含むスタンドアロンPythonスクリプトはこちらで確認できます。