Citrix Analytics のログを収集する
このドキュメントでは、Google Cloud Storage を使用して Citrix Analytics ログを Google Security Operations に取り込む方法について説明します。Citrix Analytics for Performance(Cloud Software Group)は、Citrix Virtual Apps and Desktops 環境から集計されたパフォーマンス データを提供します。これにより、OData API を介してセッション、マシン、ユーザーのデータを取得できます。Citrix Analytics for Security は、Kafka ベースの SIEM 統合を通じてエクスポートできるリスク分析情報とデータソース イベントを提供します。
始める前に
次の前提条件を満たしていることを確認してください。
- Google SecOps インスタンス
- Cloud Storage API が有効になっている GCP プロジェクト
- GCS バケットを作成および管理する権限
- Cloud Run サービス、Pub/Sub トピック、Cloud Scheduler ジョブを作成する権限
- Citrix Analytics for Performance テナントへの特権アクセス
- Citrix Cloud API 認証情報(クライアント ID、クライアント シークレット、顧客 ID)
Citrix Analytics API の認証情報を収集する
Citrix Cloud API の認証情報を取得する
- Citrix Cloud Console にログインします。
- 画面の左上にあるメニュー アイコンをクリックします。
- メニューから [Identity and Access Management] を選択します。
- [API アクセス] タブを選択します。
- [クライアントを作成] をクリックします。
- 次の詳細をコピーして安全な場所に保存します。
- クライアント ID
- クライアント シークレット
- お客様 ID(Citrix Cloud URL または IAM ページにあります)
API ベース URL を特定する
OData API のベース URL は、Citrix Cloud のリージョンによって異なります。
| 地域 | API ベース URL |
|---|---|
| 米国 | https://api.cloud.com/casodata |
| 欧州連合 | https://api.eu.cloud.com/casodata |
| アジア太平洋南部 | https://api.ap-s.cloud.com/casodata |
権限を確認する
アカウントに必要な権限があることを確認するには:
- Citrix Cloud にログインします。
- [Identity and Access Management]> [管理者] に移動します。
- API 認証情報の作成に使用したアカウントに、Citrix Analytics for Performance の権限が有効になっている [フルアクセス] または [カスタム アクセス] があることを確認します。
- 必要な権限が表示されない場合は、Citrix Cloud 管理者に連絡してアクセス権を付与してもらってください。
テスト API へのアクセス
統合に進む前に、認証情報をテストします。
CITRIX_CUSTOMER_ID="your-customer-id" CITRIX_CLIENT_ID="your-client-id" CITRIX_CLIENT_SECRET="your-client-secret" # Get bearer token TOKEN=$(curl -s -X POST \ "https://api.cloud.com/cctrustoauth2/${CITRIX_CUSTOMER_ID}/tokens/clients" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=${CITRIX_CLIENT_ID}&client_secret=${CITRIX_CLIENT_SECRET}" \ | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])") # Test OData API access curl -v -H "Authorization: CwsAuth bearer=${TOKEN}" \ -H "Citrix-CustomerId: ${CITRIX_CUSTOMER_ID}" \ -H "Accept: application/json" \ "https://api.cloud.com/casodata/sessions?\$top=1"
Google Cloud Storage バケットを作成する
- Google Cloud Console に移動します。
- プロジェクトを選択するか、新しいプロジェクトを作成します。
- ナビゲーション メニューで、[Cloud Storage > バケット] に移動します。
- [バケットを作成] をクリックします。
次の構成情報を提供してください。
設定 値 バケットに名前を付ける グローバルに一意の名前を入力します(例: citrix-analytics-logs)。ロケーション タイプ ニーズに基づいて選択します(リージョン、デュアルリージョン、マルチリージョン)。 ロケーション ロケーションを選択します(例: us-central1)。ストレージ クラス Standard(頻繁にアクセスされるログにおすすめ) アクセス制御 均一(推奨) 保護ツール 省略可: オブジェクトのバージョニングまたは保持ポリシーを有効にする [作成] をクリックします。
Cloud Run functions のサービス アカウントを作成する
Cloud Run 関数には、GCS バケットに書き込み、Pub/Sub によって呼び出される権限を持つサービス アカウントが必要です。
サービス アカウントの作成
- GCP Console で、[IAM と管理>サービス アカウント] に移動します。
- [サービス アカウントを作成] をクリックします。
- 次の構成の詳細を入力します。
- サービス アカウント名: 「
citrix-analytics-collector-sa」と入力します。 - サービス アカウントの説明:
Service account for Cloud Run function to collect Citrix Analytics logsと入力します。
- サービス アカウント名: 「
- [作成して続行] をクリックします。
- [このサービス アカウントにプロジェクトへのアクセスを許可する] セクションで、次のロールを追加します。
- [ロールを選択] をクリックします。
- [ストレージ オブジェクト管理者] を検索して選択します。
- [+ 別のロールを追加] をクリックします。
- [Cloud Run 起動元] を検索して選択します。
- [+ 別のロールを追加] をクリックします。
- [Cloud Functions 起動元] を検索して選択します。
- [続行] をクリックします。
- [完了] をクリックします。
これらのロールは、次の操作に必要です。
- Storage オブジェクト管理者: ログを GCS バケットに書き込み、状態ファイルを管理する
- Cloud Run 起動元: Pub/Sub が関数を呼び出すことを許可します
- Cloud Functions 起動元: 関数の呼び出しを許可する
GCS バケットに対する IAM 権限を付与する
GCS バケットに対する書き込み権限をサービス アカウントに付与します。
- [Cloud Storage] > [バケット] に移動します。
- バケット名をクリックします。
- [権限] タブに移動します。
- [アクセス権を付与] をクリックします。
- 次の構成の詳細を入力します。
- プリンシパルを追加: サービス アカウントのメールアドレス(例:
citrix-analytics-collector-sa@PROJECT_ID.iam.gserviceaccount.com)を入力します。 - ロールを割り当てる: [ストレージ オブジェクト管理者] を選択します。
- プリンシパルを追加: サービス アカウントのメールアドレス(例:
- [保存] をクリックします。
Pub/Sub トピックの作成
Cloud Scheduler がパブリッシュし、Cloud Run functions の関数がサブスクライブする Pub/Sub トピックを作成します。
- GCP Console で、[Pub/Sub> トピック] に移動します。
- [トピックを作成] をクリックします。
- 次の構成の詳細を入力します。
- トピック ID: 「
citrix-analytics-trigger」と入力します。 - その他の設定はデフォルトのままにします。
- トピック ID: 「
- [作成] をクリックします。
ログを収集する Cloud Run 関数を作成する
Cloud Run 関数は、Cloud Scheduler からの Pub/Sub メッセージによってトリガーされ、Citrix Analytics OData API からログを取得して GCS に書き込みます。
- GCP Console で、[Cloud Run] に移動します。
- [サービスを作成] をクリックします。
- [関数] を選択します(インライン エディタを使用して関数を作成します)。
[構成] セクションで、次の構成の詳細を指定します。
設定 値 サービス名 citrix-analytics-collectorリージョン GCS バケットと一致するリージョンを選択します(例: us-central1)。ランタイム [Python 3.12] 以降を選択します。 [トリガー(省略可)] セクションで、次の操作を行います。
- [+ トリガーを追加] をクリックします。
- [Cloud Pub/Sub] を選択します。
- [Cloud Pub/Sub トピックを選択してください] で、トピック
citrix-analytics-triggerを選択します。 - [保存] をクリックします。
[認証] セクションで次の操作を行います。
- [認証が必要] を選択します。
- Identity and Access Management(IAM)を確認します。
下にスクロールして、[コンテナ、ネットワーキング、セキュリティ] を開きます。
[セキュリティ] タブに移動します。
- サービス アカウント: サービス アカウント
citrix-analytics-collector-saを選択します。
- サービス アカウント: サービス アカウント
[コンテナ] タブに移動します。
- [変数とシークレット] をクリックします。
- 環境変数ごとに [+ 変数を追加] をクリックします。
変数名 値の例 説明 GCS_BUCKETcitrix-analytics-logsGCS バケット名 GCS_PREFIXcitrix_analyticsログファイルの接頭辞 STATE_KEYcitrix_analytics/state.json状態ファイルのパス CITRIX_CLIENT_IDyour-client-idCitrix Cloud クライアント ID CITRIX_CLIENT_SECRETyour-client-secretCitrix Cloud クライアント シークレット CITRIX_CUSTOMER_IDyour-customer-idCitrix Cloud お客様 ID API_BASEhttps://api.cloud.com/casodataOData API のベース URL ENTITIESsessions,machines,users収集するエンティティ タイプ TOP_N10001 ページあたりのレコード数 LOOKBACK_MINUTES75最初のルックバック期間 [変数とシークレット] セクションで [リクエスト] まで下にスクロールします。
- リクエストのタイムアウト:
600秒(10 分)を入力します。
- リクエストのタイムアウト:
[設定] タブに移動します。
- [リソース] セクションで次の操作を行います。
- メモリ: 512 MiB 以上を選択します。
- CPU: 1 を選択します。
- [リソース] セクションで次の操作を行います。
[リビジョン スケーリング] セクションで、次の操作を行います。
- [インスタンスの最小数]: 「
0」と入力します。 - インスタンスの最大数:
100と入力します(または、予想される負荷に基づいて調整します)。
- [インスタンスの最小数]: 「
[作成] をクリックします。
サービスが作成されるまで待ちます(1 ~ 2 分)。
サービスが作成されると、インライン コードエディタが自動的に開きます。
関数コードを追加する
- [エントリ ポイント] フィールドに「main」と入力します。
インライン コードエディタで、次の 2 つのファイルを作成します。
main.py:
import functions_framework from google.cloud import storage import json import os import urllib3 from datetime import datetime, timedelta, timezone import urllib.parse import time # Initialize HTTP client with timeouts http = urllib3.PoolManager( timeout=urllib3.Timeout(connect=5.0, read=30.0), retries=False, ) # Initialize Storage client storage_client = storage.Client() CITRIX_TOKEN_URL_TMPL = "https://api.cloud.com/cctrustoauth2/{customerid}/tokens/clients" DEFAULT_API_BASE = "https://api.cloud.com/casodata" @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch logs from Citrix Analytics OData API and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ # Get environment variables bucket_name = os.environ.get('GCS_BUCKET') prefix = os.environ.get('GCS_PREFIX', 'citrix_analytics').strip('/') state_key = os.environ.get('STATE_KEY') or f"{prefix}/state.json" customer_id = os.environ.get('CITRIX_CUSTOMER_ID') client_id = os.environ.get('CITRIX_CLIENT_ID') client_secret = os.environ.get('CITRIX_CLIENT_SECRET') api_base = os.environ.get('API_BASE', DEFAULT_API_BASE) entities = [e.strip() for e in os.environ.get('ENTITIES', 'sessions,machines,users').split(',') if e.strip()] top_n = int(os.environ.get('TOP_N', '1000')) lookback_minutes = int(os.environ.get('LOOKBACK_MINUTES', '75')) if not all([bucket_name, customer_id, client_id, client_secret]): print('Error: Missing required environment variables') return try: # Get GCS bucket bucket = storage_client.bucket(bucket_name) # Determine target hour to collect now = datetime.now(timezone.utc) fallback_target = (now - timedelta(minutes=lookback_minutes)).replace(minute=0, second=0, microsecond=0) # Load state (last processed timestamp) state = load_state(bucket, state_key) last_processed_str = state.get('last_hour_utc') if last_processed_str: last_processed = datetime.fromisoformat(last_processed_str.replace('Z', '+00:00')).replace(tzinfo=None) target_hour = last_processed + timedelta(hours=1) else: target_hour = fallback_target print(f'Processing logs for hour: {target_hour.isoformat()}Z') # Get authentication token token = get_citrix_token(customer_id, client_id, client_secret) headers = { 'Authorization': f'CwsAuth bearer={token}', 'Citrix-CustomerId': customer_id, 'Accept': 'application/json', 'Content-Type': 'application/json', } total_records = 0 # Process each entity type for entity in entities: records = [] for row in fetch_odata_entity(entity, target_hour, top_n, headers, api_base): enriched_record = { 'citrix_entity': entity, 'citrix_hour_utc': target_hour.isoformat() + 'Z', 'collection_timestamp': datetime.now(timezone.utc).isoformat() + 'Z', 'raw': row } records.append(enriched_record) # Write in batches to avoid memory issues if len(records) >= 1000: blob_name = f"{prefix}/{entity}/year={target_hour.year:04d}/month={target_hour.month:02d}/day={target_hour.day:02d}/hour={target_hour.hour:02d}/part-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S%f')}.ndjson" write_ndjson_to_gcs(bucket, blob_name, records) total_records += len(records) records = [] # Write remaining records if records: blob_name = f"{prefix}/{entity}/year={target_hour.year:04d}/month={target_hour.month:02d}/day={target_hour.day:02d}/hour={target_hour.hour:02d}/part-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S%f')}.ndjson" write_ndjson_to_gcs(bucket, blob_name, records) total_records += len(records) # Update state file save_state(bucket, state_key, {'last_hour_utc': target_hour.isoformat() + 'Z'}) print(f'Successfully processed {total_records} records for hour {target_hour.isoformat()}Z') except Exception as e: print(f'Error processing logs: {str(e)}') raise def get_citrix_token(customer_id, client_id, client_secret): """Get Citrix Cloud authentication token.""" url = CITRIX_TOKEN_URL_TMPL.format(customerid=customer_id) payload = { 'grant_type': 'client_credentials', 'client_id': client_id, 'client_secret': client_secret, } data = urllib.parse.urlencode(payload).encode('utf-8') response = http.request( 'POST', url, body=data, headers={ 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', } ) if response.status != 200: print(f'Token request failed with status {response.status}') print(f'Response: {response.data.decode("utf-8")}') raise Exception(f'Failed to get Citrix token: HTTP {response.status}') token_response = json.loads(response.data.decode('utf-8')) return token_response['access_token'] def fetch_odata_entity(entity, when_utc, top, headers, api_base): """Fetch data from Citrix Analytics OData API with pagination and rate limiting.""" year = when_utc.year month = when_utc.month day = when_utc.day hour = when_utc.hour base_url = f"{api_base.rstrip('/')}/{entity}?year={year:04d}&month={month:02d}&day={day:02d}&hour={hour:02d}" skip = 0 backoff = 1.0 while True: url = f"{base_url}&$top={top}&$skip={skip}" response = http.request('GET', url, headers=headers) # Handle rate limiting with exponential backoff if response.status == 429: retry_after = int(response.headers.get('Retry-After', str(int(backoff)))) print(f'Rate limited (429). Retrying after {retry_after}s...') time.sleep(retry_after) backoff = min(backoff * 2, 30.0) continue backoff = 1.0 if response.status != 200: print(f'HTTP Error: {response.status}') response_text = response.data.decode('utf-8') print(f'Response body: {response_text}') return data = json.loads(response.data.decode('utf-8')) items = data.get('value', []) if not items: break for item in items: yield item if len(items) < top: break skip += top def load_state(bucket, key): """Load state from GCS.""" try: blob = bucket.blob(key) if blob.exists(): state_data = blob.download_as_text() return json.loads(state_data) except Exception as e: print(f'Warning: Could not load state: {str(e)}') return {} def save_state(bucket, key, state): """Save state to GCS.""" try: blob = bucket.blob(key) blob.upload_from_string( json.dumps(state, separators=(',', ':')), content_type='application/json' ) except Exception as e: print(f'Warning: Could not save state: {str(e)}') def write_ndjson_to_gcs(bucket, key, records): """Write records as NDJSON to GCS.""" body_lines = [] for record in records: json_line = json.dumps(record, separators=(',', ':'), ensure_ascii=False) body_lines.append(json_line) body = ('\n'.join(body_lines) + '\n').encode('utf-8') blob = bucket.blob(key) blob.upload_from_string(body, content_type='application/x-ndjson')requirements.txt:
functions-framework==3.* google-cloud-storage==2.* urllib3>=2.0.0
[デプロイ] をクリックして、関数を保存してデプロイします。
デプロイが完了するまで待ちます(2 ~ 3 分)。
Cloud Scheduler ジョブの作成
Cloud Scheduler は、定期的に Pub/Sub トピックにメッセージをパブリッシュし、Cloud Run functions の関数をトリガーします。
- GCP Console で、[Cloud Scheduler] に移動します。
- [ジョブを作成] をクリックします。
次の構成情報を提供してください。
設定 値 名前 citrix-analytics-collector-hourlyリージョン Cloud Run functions と同じリージョンを選択する 周波数 0 * * * *(1 時間ごとに正時)タイムゾーン タイムゾーンを選択します(UTC を推奨) ターゲット タイプ Pub/Sub トピック トピック citrix-analytics-triggerを選択します。メッセージ本文 {}(空の JSON オブジェクト)[作成] をクリックします。
スケジュールの頻度のオプション
ログの量とレイテンシの要件に基づいて頻度を選択します。
| 頻度 | CRON 式 | ユースケース |
|---|---|---|
| 1 時間ごと | 0 * * * * |
標準(推奨) |
| 2 時間ごと | 0 */2 * * * |
音量を下げる |
| 6 時間ごと | 0 */6 * * * |
少量、バッチ処理 |
統合をテストする
- Cloud Scheduler コンソールで、ジョブを見つけます。
- [強制実行] をクリックして、ジョブを手動でトリガーします。
- 数秒待ちます。
- Cloud Run > サービスに移動します。
- 関数名
citrix-analytics-collectorをクリックします。 - [Logs] タブをクリックします。
関数が正常に実行されたことを確認します。以下のものを探します。
Processing logs for hour: YYYY-MM-DDTHH:00:00Z Successfully processed X records for hour YYYY-MM-DDTHH:00:00Z[Cloud Storage] > [バケット] に移動します。
バケット名をクリックします。
プレフィックス フォルダ
citrix_analytics/に移動します。新しい
.ndjsonファイルが現在のタイムスタンプで作成されたことを確認します。
ログにエラーが表示された場合:
- HTTP 401: 環境変数で API 認証情報を確認する
- HTTP 403: Citrix Cloud でアカウントに必要な権限があることを確認する
- HTTP 429: レート制限 - 関数はバックオフで自動的に再試行されます
- 環境変数が不足している: 必要な変数がすべて設定されていることを確認します
Citrix Analytics のログを取り込むように Google SecOps でフィードを構成する
- [SIEM 設定] > [フィード] に移動します。
- [Add New Feed] をクリックします。
- [単一フィードを設定] をクリックします。
- [フィード名] フィールドに、フィードの名前を入力します(例:
Citrix Analytics logs)。 - [ソースタイプ] として [Google Cloud Storage V2] を選択します。
- [ログタイプ] として [Citrix Analytics] を選択します。
[サービス アカウントを取得する] をクリックします。一意のサービス アカウントのメールアドレスが表示されます(例:)。
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.comこのメールアドレスをコピーして、次のステップで使用します。
[次へ] をクリックします。
次の入力パラメータの値を指定します。
ストレージ バケットの URL: 接頭辞パスを含む GCS バケット URI を入力します。
gs://citrix-analytics-logs/citrix_analytics/- 次のように置き換えます。
citrix-analytics-logs: GCS バケット名。citrix_analytics: ログが保存されるオプションの接頭辞/フォルダパス(ルートの場合は空のままにします)。
- 次のように置き換えます。
Source deletion option: 必要に応じて削除オプションを選択します。
- なし: 転送後にファイルを削除しません(テストにおすすめ)。
- 転送されたファイルを削除する: 転送が完了した後にファイルを削除します。
- 転送されたファイルと空のディレクトリを削除する: 転送が完了した後にファイルと空のディレクトリを削除します。
ファイルの最大経過日数: 過去の日数内に変更されたファイルを含めます(デフォルトは 180 日)。
アセットの名前空間: アセットの名前空間
Ingestion labels: このフィードのイベントに適用されるラベル
[次へ] をクリックします。
[Finalize] 画面で新しいフィードの設定を確認し、[送信] をクリックします。
Google SecOps サービス アカウントに IAM 権限を付与する
Google SecOps サービス アカウントには、GCS バケットに対する Storage オブジェクト閲覧者ロールが必要です。
- [Cloud Storage] > [バケット] に移動します。
- バケット名をクリックします。
- [権限] タブに移動します。
- [アクセス権を付与] をクリックします。
- 次の構成の詳細を入力します。
- プリンシパルを追加: Google SecOps サービス アカウントのメールアドレスを貼り付けます。
- ロールを割り当てる: [Storage オブジェクト閲覧者] を選択します。
[保存] をクリックします。
UDM マッピング テーブル
| ログフィールド | UDM マッピング | ロジック |
|---|---|---|
occurrence_event_type |
extensions.auth.type |
マッピング: Session.Logon → AUTHTYPE_UNSPECIFIED、Session.End → AUTHTYPE_UNSPECIFIED |
server_name |
intermediary.asset.hostname |
直接マッピングされます。 |
server_name |
intermediary.hostname |
直接マッピングされます。 |
event_type |
metadata.description |
直接マッピングされます。 |
timestamp |
metadata.event_timestamp |
ISO8601 として解析済み |
udm_event_type |
metadata.event_type |
マッピング: "USER_LOGIN", "USER_LOGOUT" → GENERIC_EVENT |
tenant_id |
metadata.product_deployment_id |
直接マッピングされます。 |
occurrence_event_type |
metadata.product_event_type |
直接マッピングされます。 |
event_id |
metadata.product_log_id |
直接マッピングされます。 |
product |
metadata.product_name |
直接マッピングされます。 |
product_version |
metadata.product_version |
直接マッピングされます。 |
ui_link |
metadata.url_back_to_product |
直接マッピングされます。 |
session_key |
network.session_id |
直接マッピングされます。 |
domain |
principal.administrative_domain |
直接マッピングされます。 |
device_id |
principal.asset.hostname |
直接マッピングされます。 |
client_ip |
principal.asset.ip |
統合済み |
vulnerability |
principal.asset.vulnerabilities |
統合済み |
device_id |
principal.hostname |
直接マッピングされます。 |
client_ip |
principal.ip |
統合済み |
os_name |
principal.platform |
マッピングされた値(合計 6 個、例: (?i)windows → WINDOWS、(?i)windows → MAC、(?i)windows... |
os_extra_info |
principal.platform_patch_level |
直接マッピングされます。 |
os_version |
principal.platform_version |
直接マッピングされます。 |
entity_id |
principal.user.email_addresses |
マッピング: ^.+@.+$ → entity_id |
entity_type |
principal.user.email_addresses |
マッピング: user → entity_id |
session_user_name |
principal.user.user_display_name |
直接マッピングされます。 |
entity_id |
principal.user.userid |
直接マッピングされます。 |
session_user_name |
principal.user.userid |
直接マッピングされます。 |
alert_message |
security_result.action_details |
直接マッピングされます。 |
analytic |
security_result.analytics_metadata |
統合済み |
category |
security_result.category |
統合済み |
indicator_category |
security_result.category |
マッピング: Data exfiltration → category |
indicator_name |
security_result.description |
直接マッピングされます。 |
label |
security_result.detection_fields |
統合済み |
label |
security_result.outcomes |
統合済み |
severity |
security_result.severity |
直接マッピングされます。 |
app_name |
target.application |
直接マッピングされます。 |
app_name |
target.process.file.names |
統合済み |
printer_name |
target.resource.name |
直接マッピングされます。 |
entity_id |
target.user.email_addresses |
マッピング: ^.+@.+$ → entity_id |
entity_type |
target.user.email_addresses |
マッピング: user → entity_id |
session_user_name |
target.user.user_display_name |
直接マッピングされます。 |
entity_id |
target.user.userid |
直接マッピングされます。 |
session_user_name |
target.user.userid |
直接マッピングされます。 |
| なし | extensions.auth.type |
定数: AUTHTYPE_UNSPECIFIED |
| なし | metadata.event_type |
定数: GENERIC_EVENT |
| なし | metadata.vendor_name |
定数: CITRIX_ANALYTICS |
| なし | principal.platform |
定数: WINDOWS |
| なし | security_result.confidence_score |
定数: risk_probability |
| なし | security_result.risk_score |
定数: cur_riskscore |
さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。