ThreatLocker Platform のログを収集する

以下でサポートされています。

このドキュメントでは、Google Cloud Storage V2 を使用して ThreatLocker Platform ログを Google Security Operations に取り込む方法について説明します。

ThreatLocker は、アプリケーションのホワイトリスト登録、リングフェンシング、ストレージ制御を提供するゼロトラスト エンドポイント セキュリティ プラットフォームです。Cloud Run 関数がスケジュールに従って ThreatLocker API をポーリングし、NDJSON 形式で GCS バケットにログを書き込みます。Google SecOps は、GCS V2 フィードを介してこれらのログを取り込みます。

始める前に

次の前提条件を満たしていることを確認してください。

  • Google SecOps インスタンス
  • Cloud Storage API が有効になっている GCP プロジェクト
  • GCS バケットを作成、管理する権限
  • GCS バケットの IAM ポリシーを管理する権限
  • Cloud Run サービス、Pub/Sub トピック、Cloud Scheduler ジョブを作成する権限
  • 管理者権限を持つ ThreatLocker ポータルへの特権アクセス
  • ThreatLocker サポートから提供された ThreatLocker API キーとリージョン API URL

Google Cloud Storage バケットを作成する

  1. Google Cloud コンソールに移動します。
  2. プロジェクトを選択するか、新しいプロジェクトを作成します。
  3. ナビゲーション メニューで、[Cloud Storage] > [バケット] に移動します。
  4. [バケットを作成] をクリックします。
  5. 次の構成情報を提供してください。

    設定 値
    バケットに名前を付ける グローバルに一意の名前(threatlocker-logs など)を入力します。
    ロケーション タイプ ニーズに応じて選択します(リージョン、デュアルリージョン、マルチリージョン)。
    ロケーション ロケーションを選択します(例: us-central1)。
    ストレージ クラス Standard(頻繁にアクセスされるログに推奨)
    アクセス制御 均一(推奨)
    保護ツール 省略可: オブジェクトのバージョニングまたは保持ポリシーを有効にする
  6. [作成] をクリックします。

ThreatLocker API 認証情報を収集する

API キーを取得する

  1. API 認証情報を取得するには、ThreatLocker サポートまたは ThreatLocker アカウント マネージャーにお問い合わせください。
  2. 以下を受け取ることができます。
    • API キー: API 認証用の署名なしトークン。
    • API Base URL: リージョン API ホスト名(例: https://api.g.threatlocker.com)。
  3. これらの認証情報を安全な場所に保存します。

権限を確認する

アカウントに必要な権限があることを確認するには:

  1. 管理者アカウントで ThreatLocker ポータルにログインします。
  2. 左側のメニューで [統合監査] に移動します。
  3. 監査データが表示される場合は、必要な管理者権限が付与されています。
  4. このオプションが表示されない場合は、ThreatLocker 管理者に連絡して管理者アクセス権を付与してもらってください。

テスト API へのアクセス

  • 統合に進む前に、認証情報をテストします。

    # Replace with your actual credentials
    API_KEY="your-api-key"
    API_BASE="https://api.g.threatlocker.com"
    
    # Test API access
    curl -v -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json" \
      "${API_BASE}/audit/v1/events?startDate=2024-01-01&endDate=2024-01-02&limit=1"
    

Cloud Run functions のサービス アカウントを作成する

Cloud Run functions の関数には、GCS バケットへの書き込み権限と Pub/Sub による呼び出し権限を持つサービス アカウントが必要です。

サービス アカウントの作成

  1. GCP コンソールで、[IAM と管理] > [サービス アカウント] に移動します。
  2. [サービス アカウントを作成] をクリックします。
  3. 次の構成情報を指定します。
    • サービス アカウント名: 「threatlocker-collector-sa」と入力します。
    • サービス アカウントの説明: 「Service account for Cloud Run function to collect ThreatLocker Platform logs」と入力します。
  4. [作成して続行] をクリックします。
  5. [このサービス アカウントにプロジェクトへのアクセスを許可する] セクションで、次のロールを追加します。
    1. [ロールを選択] をクリックします。
    2. [Storage オブジェクト管理者] を検索して選択します。
    3. [+ 別のロールを追加] をクリックします。
    4. [Cloud Run 起動元] を検索して選択します。
    5. [+ 別のロールを追加] をクリックします。
    6. [Cloud Functions 起動元] を検索して選択します。
  6. [続行] をクリックします。
  7. [完了] をクリックします。

これらのロールは、次の操作に必要です。

  • Storage オブジェクト管理者: GCS バケットにログを書き込み、状態ファイルを管理します。
  • Cloud Run 起動元: Pub/Sub が関数を呼び出せるようにします。
  • Cloud Functions 起動元: 関数の呼び出しを許可します。

GCS バケットに対する IAM 権限を付与する

GCS バケットに対する書き込み権限をサービス アカウントに付与します。

  1. [Cloud Storage] > [バケット] に移動します。
  2. バケット名(threatlocker-logs など)をクリックします。
  3. [権限] タブに移動します。
  4. [アクセス権を付与] をクリックします。
  5. 次の構成情報を指定します。
    • プリンシパルを追加: サービス アカウントのメールアドレス(例: threatlocker-collector-sa@your-project.iam.gserviceaccount.com)を入力します。
    • ロールを割り当てる: [Storage オブジェクト管理者] を選択します。
  6. [保存] をクリックします。

Pub/Sub トピックの作成

Cloud Scheduler がパブリッシュし、Cloud Run functions の関数がサブスクライブする Pub/Sub トピックを作成します。

  1. GCP コンソールで、[Pub/Sub] > [トピック] に移動します。
  2. [トピックを作成] をクリックします。
  3. 次の構成情報を指定します。
    • トピック ID: 「threatlocker-trigger」と入力します。
    • その他の設定はデフォルトのままにします。
  4. [作成] をクリックします。

ログを収集する Cloud Run 関数を作成する

Cloud Run 関数は、Cloud Scheduler からの Pub/Sub メッセージによってトリガーされ、ThreatLocker API からログを取得して GCS に書き込みます。

  1. GCP Console で Cloud Run に移動します。
  2. [サービスを作成] をクリックします。
  3. [関数](インライン編集を使用して関数を作成する)を選択します。
  4. [構成] セクションで、次の構成の詳細を指定します。

    設定 値
    サービス名 threatlocker-collector
    リージョン GCS バケットに一致するリージョンを選択します(例: us-central1)。
    ランタイム [Python 3.12] 以降を選択します。
  5. [トリガー(省略可)] セクションで、次の操作を行います。

    1. [+ トリガーを追加] をクリックします。
    2. [Cloud Pub/Sub] を選択します。
    3. [Cloud Pub/Sub トピックを選択してください] で、トピック threatlocker-trigger を選択します。
    4. [保存] をクリックします。
  6. [認証] セクションで、次の操作を行います。

    1. [認証が必要] を選択します。
    2. Identity and Access Management(IAM)を確認します。
  7. 下にスクロールして、[コンテナ、ネットワーキング、セキュリティ] を開きます。

  8. [セキュリティ] タブに移動します。

    • サービス アカウント: サービス アカウント threatlocker-collector-sa を選択します。
  9. [コンテナ] タブに移動します。

    1. [変数とシークレット] をクリックします。
    2. 環境変数ごとに [+ 変数を追加] をクリックします。
    変数名 値の例 説明
    GCS_BUCKET threatlocker-logs GCS バケット名
    GCS_PREFIX threatlocker ログファイルの接頭辞
    STATE_KEY threatlocker/state.json 状態ファイルのパス
    TL_API_KEY your-api-key ThreatLocker API キー
    TL_API_BASE https://api.g.threatlocker.com ThreatLocker リージョン API URL
    MAX_RECORDS 10000 1 回の実行あたりの最大レコード数
    PAGE_SIZE 1000 1 ページあたりのレコード数
    LOOKBACK_HOURS 24 最初のルックバック期間
  10. [変数とシークレット] タブで、[リクエスト] まで下にスクロールします。

    • リクエスト タイムアウト: 600 秒(10 分)を入力します。
  11. [コンテナ] の [設定] タブに移動します。

    • [リソース] セクションで、次の操作を行います。
      • メモリ: 512 MiB 以上を選択します。
      • CPU: [1] を選択します。
    • [完了] をクリックします。
  12. [実行環境] まで下にスクロールします。

    • [デフォルト](推奨)を選択します。
  13. [リビジョン スケーリング] セクションで、次の操作を行います。

    • [インスタンスの最小数] に「0」と入力します。
    • [インスタンスの最大数]: 「100」と入力します(または、予想される負荷に基づいて調整します)。
  14. [作成] をクリックします。

  15. サービスが作成されるまで待ちます(1 ~ 2 分)。

  16. サービスが作成されると、インライン コードエディタが自動的に開きます。

関数コードを追加する

  1. [関数のエントリ ポイント] に「main」と入力します。
  2. インライン コードエディタで、次の 2 つのファイルを作成します。

    • 最初のファイル: main.py:
    import functions_framework
    from google.cloud import storage
    import json
    import os
    import urllib3
    from datetime import datetime, timezone, timedelta
    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()
    
    # Environment variables
    GCS_BUCKET = os.environ.get('GCS_BUCKET')
    GCS_PREFIX = os.environ.get('GCS_PREFIX', 'threatlocker')
    STATE_KEY = os.environ.get('STATE_KEY', 'threatlocker/state.json')
    API_KEY = os.environ.get('TL_API_KEY')
    API_BASE = os.environ.get('TL_API_BASE', 'https://api.g.threatlocker.com')
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    def parse_datetime(value: str) -> datetime:
        """Parse ISO datetime string to datetime object."""
        if value.endswith("Z"):
            value = value[:-1] + "+00:00"
        return datetime.fromisoformat(value)
    
    @functions_framework.cloud_event
    def main(cloud_event):
        """
        Cloud Run function triggered by Pub/Sub to fetch ThreatLocker Platform
        audit logs and write to GCS.
    
        Args:
            cloud_event: CloudEvent object containing Pub/Sub message
        """
    
        if not all([GCS_BUCKET, API_KEY, API_BASE]):
            print('Error: Missing required environment variables')
            return
    
        try:
            bucket = storage_client.bucket(GCS_BUCKET)
    
            # Load state
            state = load_state(bucket, STATE_KEY)
    
            # Determine time window
            now = datetime.now(timezone.utc)
            last_time = None
    
            if isinstance(state, dict) and state.get("last_event_time"):
                try:
                    last_time = parse_datetime(state["last_event_time"])
                    last_time = last_time - timedelta(minutes=2)
                except Exception as e:
                    print(f"Warning: Could not parse last_event_time: {e}")
    
            if last_time is None:
                last_time = now - timedelta(hours=LOOKBACK_HOURS)
    
            print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")
    
            # Fetch logs
            records, newest_event_time = fetch_logs(
                start_time=last_time,
                end_time=now,
                page_size=PAGE_SIZE,
                max_records=MAX_RECORDS,
            )
    
            if not records:
                print("No new log records found.")
                save_state(bucket, STATE_KEY, now.isoformat())
                return
    
            # Write to GCS as NDJSON
            timestamp = now.strftime('%Y%m%d_%H%M%S')
            object_key = f"{GCS_PREFIX}/logs_{timestamp}.ndjson"
            blob = bucket.blob(object_key)
    
            ndjson = '\n'.join([json.dumps(record, ensure_ascii=False) for record in records]) + '\n'
            blob.upload_from_string(ndjson, content_type='application/x-ndjson')
    
            print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}")
    
            # Update state with newest event time
            if newest_event_time:
                save_state(bucket, STATE_KEY, newest_event_time)
            else:
                save_state(bucket, STATE_KEY, now.isoformat())
    
            print(f"Successfully processed {len(records)} records")
    
        except Exception as e:
            print(f'Error processing logs: {str(e)}')
            raise
    
    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: {e}")
    
        return {}
    
    def save_state(bucket, key, last_event_time_iso: str):
        """Save the last event timestamp to GCS state file."""
        try:
            state = {'last_event_time': last_event_time_iso}
            blob = bucket.blob(key)
            blob.upload_from_string(
                json.dumps(state, indent=2),
                content_type='application/json'
            )
            print(f"Saved state: last_event_time={last_event_time_iso}")
        except Exception as e:
            print(f"Warning: Could not save state: {e}")
    
    def fetch_logs(start_time: datetime, end_time: datetime, page_size: int, max_records: int):
        """
        Fetch audit logs from ThreatLocker API with pagination and rate limiting.
    
        Args:
            start_time: Start time for log query
            end_time: End time for log query
            page_size: Number of records per page
            max_records: Maximum total records to fetch
    
        Returns:
            Tuple of (records list, newest_event_time ISO string)
        """
        base_url = API_BASE.rstrip('/')
        endpoint = f"{base_url}/audit/v1/events"
    
        headers = {
            'Authorization': f'Bearer {API_KEY}',
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'User-Agent': 'GoogleSecOps-ThreatLockerCollector/1.0'
        }
    
        records = []
        newest_time = None
        page_num = 0
        backoff = 1.0
        offset = 0
    
        start_date = start_time.strftime('%Y-%m-%d')
        end_date = end_time.strftime('%Y-%m-%d')
    
        while True:
            page_num += 1
    
            if len(records) >= max_records:
                print(f"Reached max_records limit ({max_records})")
                break
    
            current_limit = min(page_size, max_records - len(records))
            url = f"{endpoint}?startDate={start_date}&endDate={end_date}&limit={current_limit}&offset={offset}"
    
            try:
                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 [], None
    
                data = json.loads(response.data.decode('utf-8'))
    
                page_results = data if isinstance(data, list) else data.get('events', data.get('data', []))
    
                if not page_results:
                    print(f"No more results (empty page)")
                    break
    
                print(f"Page {page_num}: Retrieved {len(page_results)} events")
                records.extend(page_results)
    
                # Track newest event time
                for event in page_results:
                    try:
                        event_time = event.get('timestamp') or event.get('dateTime') or event.get('createdAt')
                        if event_time:
                            if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time):
                                newest_time = event_time
                    except Exception as e:
                        print(f"Warning: Could not parse event time: {e}")
    
                # Check for more results
                if len(page_results) < page_size:
                    print(f"Reached last page (size={len(page_results)} < limit={page_size})")
                    break
    
                offset += len(page_results)
    
            except Exception as e:
                print(f"Error fetching logs: {e}")
                return [], None
    
        print(f"Retrieved {len(records)} total records from {page_num} pages")
        return records, newest_time
    
    • 2 つ目のファイル: requirements.txt:
    functions-framework==3.*
    google-cloud-storage==2.*
    urllib3>=2.0.0
    
  3. [デプロイ] をクリックして関数を保存し、デプロイします。

  4. デプロイが完了するまで待ちます(2 ~ 3 分)。

Cloud Scheduler ジョブの作成

Cloud Scheduler は、定期的に Pub/Sub トピックにメッセージをパブリッシュし、Cloud Run 関数をトリガーします。

  1. GCP Console で、[Cloud Scheduler] に移動します。
  2. [ジョブを作成] をクリックします。
  3. 次の構成情報を提供してください。

    設定 値
    名前 threatlocker-collector-hourly
    リージョン Cloud Run functions の関数と同じリージョンを選択します。
    周波数 0 * * * *(1 時間ごと、毎正時)
    タイムゾーン タイムゾーンを選択(UTC を推奨)
    ターゲット タイプ Pub/Sub
    トピック トピック threatlocker-trigger を選択します。
    メッセージ本文 {}(空の JSON オブジェクト)
  4. [作成] をクリックします。

スケジュール頻度のオプション

ログの量とレイテンシの要件に基づいて頻度を選択します。

頻度 CRON 式 ユースケース
5 分おき */5 * * * * 大容量、低レイテンシ
15 分ごと */15 * * * * 検索量が普通
1 時間ごと 0 * * * * 標準(推奨)
6 時間ごと 0 */6 * * * 少量のバッチ処理
毎日 0 0 * * * 過去のデータの収集

統合をテストする

  1. Cloud Scheduler コンソールで、ジョブ(threatlocker-collector-hourly)を見つけます。
  2. [強制実行] をクリックして手動でトリガーします。
  3. 数秒待ってから、[Cloud Run] > [サービス] > [threatlocker-collector] > [ログ] に移動します。
  4. 関数が正常に実行されたことを確認します。以下のものを探します。

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Page 1: Retrieved X events
    Wrote X records to gs://threatlocker-logs/threatlocker/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  5. GCS バケット(threatlocker-logs)をチェックして、ログが書き込まれたことを確認します。

ログにエラーが表示される場合:

  • HTTP 401: 環境変数の API キーを確認します。
  • HTTP 403: ThreatLocker ポータルでアカウントに管理者権限があることを確認します。
  • HTTP 429: レート制限 - 関数はバックオフを使用して自動的に再試行します
  • 環境変数が設定されていない: 必要な変数がすべて設定されていることを確認します。

ThreatLocker Platform のログを取り込むように Google SecOps でフィードを構成する

  1. [設定] > [データ管理] > [フィード] に移動します。SIEM のみのプラットフォームを使用している場合は、[設定] > [フィード] に移動します。
  2. [Add New Feed] をクリックします。
  3. [単一フィードを設定] をクリックします。
  4. [フィード名] フィールドに、フィードの名前を入力します(例: ThreatLocker Logs)。
  5. [Source type] として [Google Cloud Storage V2] を選択します。
  6. [ログタイプ] として [ThreatLocker Platform] を選択します。
  7. [サービス アカウントを取得する] をクリックします。一意のサービス アカウントのメールアドレスが表示されます。例:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. このメールアドレスをコピーします。次のステップでこれを使用します。

  9. [次へ] をクリックします。

  10. 次の入力パラメータの値を指定します。

    • ストレージ バケットの URL: 接頭辞パスを含む GCS バケット URI を入力します。

      gs://threatlocker-logs/threatlocker/
      
      • 次のように置き換えます。
        • threatlocker-logs: GCS バケット名。
        • threatlocker/: ログが保存されるプレフィックス / フォルダパス。
    • Source deletion option: 必要に応じて削除オプションを選択します。

      • なし: 転送後にファイルを削除しません(テストに推奨)。
      • 転送されたファイルを削除する: 転送が完了した後にファイルを削除します。
      • 転送されたファイルと空のディレクトリを削除する: 転送が成功した後にファイルと空のディレクトリを削除します。

    • ファイルの最長存続期間: 過去数日間に変更されたファイルを含めます(デフォルトは 180 日)。

    • Asset namespace: アセットの名前空間。

    • Ingestion labels: このフィードのイベントに適用されるラベル。

  11. [次へ] をクリックします。

  12. [Finalize] 画面で新しいフィードの設定を確認し、[送信] をクリックします。

Google SecOps サービス アカウントに IAM 権限を付与する

Google SecOps サービス アカウントには、GCS バケットに対する Storage オブジェクト閲覧者のロールが必要です。

  1. [Cloud Storage] > [バケット] に移動します。
  2. バケット名(threatlocker-logs)をクリックします。
  3. [権限] タブに移動します。
  4. [アクセス権を付与] をクリックします。
  5. 次の構成情報を指定します。
    • プリンシパルを追加: Google SecOps サービス アカウントのメールアドレスを貼り付けます。
    • ロールを割り当てる: [Storage オブジェクト閲覧者] を選択します。
  6. [保存] をクリックします。

UDM マッピング テーブル

ログフィールド UDM マッピング ロジック
rp extensions.auth.mechanism rp が存在する場合は「REMOTE」に設定されます。
n metadata.description 値が直接コピーされる
at、src_ip、dest_ip、ip_protocol、fp、pn metadata.event_type at == "network" または(src_ip、dest_ip、ip_protocol が存在)の場合は NETWORK_CONNECTION に設定。fp と pn が存在する場合は PROCESS_UNCATEGORIZED。at が ["execute","install"] の場合は PROCESS_LAUNCH。at == "newprocess" の場合は PROCESS_OPEN。at が ["write","move"] の場合は FILE_MODIFICATION。at == "read" の場合は FILE_READ。at == "delete" の場合は FILE_DELETION。at == "registry" の場合は REGISTRY_UNCATEGORIZED。
p metadata.product_event_type 値が直接コピーされる
metadata.product_name 「THREATLOCKER」に設定します。
metadata.vendor_name 「THREATLOCKER」に設定します。
sn network.ip_protocol sn が Tcp と一致する場合は「TCP」に設定されます。
computerId principal.asset.asset_id 「ComputerId: %{computerId}」として連結されます。
dt principal.asset.category 値が直接コピーされる
hostname principal.hostname 値が直接コピーされる
fp principal.ip at == "network" の場合に grok パターンを使用して src_ip を抽出
pn principal.process.file.full_path 値が直接コピーされる
pid principal.process.pid 文字列に変換
organizationId principal.resource.id 値が直接コピーされる
u principal.user.user_display_name 値が直接コピーされる
u principal.user.userid ドメインの後に Grok パターンを使用して抽出されたユーザー部分
e, mid, rf security_result.about.resource.attribute.labels 暗号化ステータス(e)、メンテナンス ID(mid)、リングフェンス(rf)の統合ラベル
a security_result.action a=1 の場合は「ALLOW」、a=2 の場合は「BLOCK」、a=3 の場合は「CHALLENGE」、a=4 の場合は「ALLOW_WITH_MODIFICATION」、a=5 の場合は「UNKNOWN_ACTION」、a=6 の場合は「QUARANTINE」に設定します。
所在 security_result.action_details 値が直接コピーされる
月額 security_result.outcomes モニターモードのステータスに設定(mo == "true" の場合は「モニターモード オン」、mo == "false" の場合は「モニターモード オフ」)
pyid security_result.rule_id 値が直接コピーされる
p security_result.rule_name 値が直接コピーされる
ap、dan target.application dan が空でない場合は dan の値、それ以外の場合は ap
fp target.file.full_path at が ["write","read","delete","move"] に含まれる場合に設定
h target.file.sha1 16 進数パターンに一致する場合は小文字に変換して設定
s256 target.file.sha256 16 進数パターンに一致する場合は小文字に変換して設定
s target.file.size 文字列に変換してから、符号なし整数に変換
fp target.hostname at == "network" の場合に grok パターンを使用して dest_host を抽出
fp target.ip at == "network" の場合、Grok パターンを使用して dest_ip を抽出
fp target.port at == "network" の場合に grok パターンを使用して dest_port を抽出し、整数に変換
fp target.process.file.full_path at が ["execute","install","newprocess"] に含まれている場合に設定します。
s256 target.process.file.sha256 16 進数パターンに一致する場合は小文字に変換して設定
fp target.registry.registry_key at == "registry" の場合に設定

変更ログ

このパーサーの変更ログを表示する

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。