search
github編集

サービスモードREST API

KeeperコマンダーサービスモードでREST APIをを作成

hashtag
Keeperコマンダーサービスモード

Keeperコマンダーのサービスモードモジュールは、最小限の設定で導入可能な、安全で設定可能なAPIサーバーを提供することで、REST APIの統合を可能にします。このモジュールにより、ユーザーはセキュリティと設定の柔軟性を維持しながら、REST APIインターフェースを介してコマンダーのCLIコマンドを実行できます。このサービスはローカルで実行でき、オプションでNgrokと統合して、既存のNgrokネットワークにルーティング可能なアドレスを作成することもできます。

hashtag
特徴

hashtag
コア機能

  • API サーバー: コマンダーCLI コマンドを実行するためのFlaskベースのREST APIサーバー

  • サービス管理: APIサービスのライフサイクル全体を管理

  • 構成管理: インタラクティブなセットアップと簡略化されたセットアップの両方を備えた柔軟な構成システム

  • セキュリティ制御: API キー管理、アクセス制御、レート制限、IP 許可/拒否などの包括的なセキュリティ機能

  • APIバージョン管理 同期処理 (v1) と非同期処理 (v2) の両方をサポートする2種類のAPIバージョンを提供しています。

  • リクエストキューシステム 高度な非同期リクエスト処理機能を備え、リクエストの追跡とステータスの監視が可能です。

  • 柔軟なホスティングオプション: オンプレミス、Dockerコンテナ、統合されたNgrokエージェントを使用したクラウドでの実行

hashtag
サービスコマンド

コマンド
説明

service-create

カスタマイズ可能な設定でサービスを初期化および構成する

service-start

既存の構成でサービスを開始する

service-stop

実行中のサービスを正常に停止する

service-status

現在のサービスステータスを表示する

service-config-add

新しいAPI構成とコマンドアクセス設定を追加する

service-docker-setup

KSM構成を使用したDockerサービスモードの自動セットアップ

slack-app-setup

コマンダーサービスモードを使用したSlackアプリ連携の自動セットアップ

hashtag
セキュリティ機能

  • APIキー認証

  • 設定可能なトークンの有効期限 (分/時間/日)

  • API応答のオプションのAES-256 GCM暗号化

  • 提供された証明書 (.pem) を使用したTLS対応

  • 構成可能なルールでレート制限

  • IP許可リスト (ホワイトリスト) とIP拒否リスト (ブラックリスト) の管理

  • リクエストの検証とポリシーの適用

  • 秘密鍵を使用したローカルサービス構成のJSONまたはYAMLファイル暗号化

hashtag
セキュリティ

Keeperコマンダーサービスモード機能は、既存のコマンダーセッションをREST APIでラップするセルフホステッドミドルウェアです。この機能は、高速なリクエストとシンプルなHTTPSベースのAPIが求められる環境に適しています。

この機能を最も安全に使用するためには、以下のことをお勧めします。

  • コマンダーサービス専用のサービスアカウントを使用し、必要な権限と機能のみに範囲を限定してください。

  • また、コマンドのアクセス制御についても、ユースケースに応じて必要なコマンドのみに制限することを推奨します。

  • REST APIエンドポイントへのアクセスにIPホワイトリストを適用する。

  • コマンダーサービスを実行しているマシンへのアクセスを保護する。

  • 異なるコマンドや使用ケースごとに異なるAPIトークンを使用する。

hashtag
使用法

hashtag
基本設定

Keeperコマンダーをインストールしてからシェルへログインします。

プロンプトが表示されたら、Keeperの認証情報を使用してログインします。コマンダーサービスモードは通常サービスとして実行されるため、生体認証ログイン、または永続的なログインセッションの利用を推奨します。

生体認証ログイン

または、以下のコマンドを使用して永続的なログインセッションを作成します。

※ 上記の設定により、30日間ログイン状態が維持されます。

hashtag
サービスモードの作成: 対話的設定を使用

対話形式のプロンプトを使ってサービスを作成・構成します。

実行すると、以下の項目の設定を順に求められます。

  • ポート番号

  • Ngrok認証トークン (任意)

  • Cloudflareトンネルトークン (任意)

  • TLS証明書のパス (任意)

  • リクエストキューシステムの有効化 (y/n)

  • セキュリティ設定 (任意)

  • 設定フォーマット (yaml/json) (未作成の場合)

  • 実行モード (フォアグラウンド/バックグラウンド)

  • コマンドアクセス制御

例: TLS証明書 (https) を使用してサービスモードを作成する

hashtag
ストリームライン構成

1つのコマンドでサービスをすばやく構成できます (デフォルトではHTTP・フォアグラウンドモードで実行されます)。

Ngrokを使用してすばやく構成する場合 (Ngrokの認証トークンとサブドメインを指定)

Cloudflareを使用してすばやく構成する場合 (Cloudflareの認証トークンとドメイン名を指定)

詳細オプションを使用して構成する場合

ストリームラインパラメータ

  • -p、--port サービスのポート番号 (簡易セットアップを開始するために必須)

  • -c、--commands 許可コマンドまたはエイリアスのカンマ区切りリスト (必須)

  • -ng、--ngrok クラウド管理のURLアクセス用のngrok認証トークン (任意)

  • -cd Ngrokのカスタムドメイン。サブドメイン部分のみ (任意)

  • -cf、--cloudflare Cloudflareトンネルトークン (クラウド経由でURLアクセスを行うための認証トークン) (任意)

  • -cfd Cloudflareカスタムドメイン (任意)

  • -crtf、--certfile SSL証明書ファイルのパス。拡張子 .crt / .pem / .key に対応 (任意)

  • -crtp、--certpassword SSL証明書のパスワード (任意)

  • -q、--queue_enabled リクエストキュー機構を有効化 (y/n) デフォルト: y

  • -rm、--run_mode サービスの実行モード (foreground/background) デフォルト: foreground

  • -f、--fileformat 構成ファイル形式 (json/yaml) - セットアップを促す前に、サービスはローカルの構成ファイルとボルトを確認し、既存の構成形式があるかをチェックします。

  • -rl、--ratelimit IPアドレスごと、かつエンドポイントごとのレート制限を指定します。 例: 10/minute、100/hour、1000/day (任意)

  • -aip、--allowedip アクセスを許可するIPアドレスのリストを指定します。 デフォルト: 0.0.0.0/0, ::/0 (任意)

  • -dip アクセスを拒否するIPアドレスのリストを指定します。 (任意)

  • -ek、--encryption_key レスポンスをAES-256で暗号化するための、Base64形式の32バイト鍵を指定します。 (任意)

  • -te、--token_expiration APIキーの有効期限を指定します。 例: 30m、24h、7d (任意)

  • -ur、--update-record <RECORD_UID> 生成されたAPIキーとサービスURLを、指定したボルトレコードに保存します。 ログにAPIキーを出力しないようにする目的で有用です。 (任意)

hashtag
構成ファイル

初期設定が完了すると、ボルト内に「Commander Service Mode」というタイトルのレコードが作成されます。このレコードにはservice_config.yamlというYAML/JSONファイルが含まれています。

コマンダーサービスモードレコード

次回以降のサービス起動では、パラメータなしの service-create コマンドを実行します。構成はローカルで暗号化済みの service_config ファイルから読み込まれます。

circle-info

構成はボルトに安全に保存されていますが、サービスは起動時にローカルにキャッシュされた暗号化ファイルを使用します。ボルトからの再読み込みを強制するには、service-start を実行する前にローカルの構成ファイル (~/.keeper/service_config.json または .yaml) を削除してください。

hashtag
例: ターミナルからフォアグラウンドで起動する場合

サービスはシステムのターミナルから起動できます。以下の例では、/api/v1 をフォアグラウンドモードで実行します (/api/v2 を使用する場合は -q y でキューモードを有効化します)。

Ctrl + C でサービスを停止できます。一度サービスを作成した後は、次のようにして再起動できます。

生体認証ログインまたは永続ログインモードtohaが有効になっている場合、サービスの起動はシームレスに行われます。

hashtag
サービス管理

サービスステータスを確認します。

追加の構成を追加します。

サービスを開始します。

サービスを停止します。

hashtag
ヘルスチェック

コマンダーのサービスモードでは、サービスの稼働状態を確認するためのヘルスチェック用URLが用意されています。以下は、サービスがlocalhostのポート8080で稼働している場合の例です。

リクエスト

レスポンス

hashtag
サポート

サポートや機能のリクエストについては、Githubarrow-up-rightでIssueを提出するか、下記までお問い合わせください。

hashtag
次の手順

前へ自動実行次へAPIの使用

最終更新