TeamViewer のログを収集する

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

このドキュメントでは、Google Cloud Storage を使用して TeamViewer ログを Google Security Operations に取り込む方法について説明します。パーサーは、JSON 形式のログから監査イベントを抽出します。イベントの詳細を反復処理し、特定のプロパティを統合データモデル(UDM)フィールドにマッピングし、参加者と発表者の情報を処理し、ユーザー アクティビティに基づいてイベントを分類します。また、ラベルの統合やタイムスタンプの標準形式への変換などのデータ変換も行います。

始める前に

次の前提条件を満たしていることを確認します。

  • Google SecOps インスタンス
  • Cloud Storage API が有効になっている GCP プロジェクト
  • GCS バケットを作成および管理する権限
  • GCS バケットの IAM ポリシーを管理する権限
  • Cloud Run サービス、Pub/Sub トピック、Cloud Scheduler ジョブを作成する権限
  • TeamViewer Management Console への特権アクセス
  • TeamViewer Business、Premium、Corporate、Tensor のいずれかのライセンス(API アクセスに必要)

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

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

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

TeamViewer の前提条件を取得する

  1. https://login.teamviewer.com/TeamViewer Management Console にログインします。
  2. 右上にあるユーザー アイコンをクリックし、[プロフィールを編集] を選択します。
  3. [アプリ] を選択します
  4. [スクリプト トークンを作成] をクリックします。
  5. 次の構成の詳細を指定します。
    • トークン名: わかりやすい名前を入力します(例: Google SecOps Integration)。
    • 権限: 次の権限を選択します。
      • アカウント管理 > アカウント データを表示する
      • セッション管理 > セッション データを表示する
      • 接続レポート > 接続レポートを表示する
  6. [作成] をクリックします。
  7. 生成されたスクリプト トークンをコピーして安全な場所に保存します。

  8. TeamViewer API ベース URL(https://webapi.teamviewer.com/api/v1)を記録します。

権限を確認する

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

  1. TeamViewer Management Console にログインします。
  2. [プロフィールを編集> アプリ] に移動します。
  3. リストでスクリプト トークンを見つけます。
  4. [接続レポート] > [接続レポートを表示] が有効になっていることを確認します。
  5. この権限が有効になっていない場合は、トークンを編集して必要な権限を追加します。

テスト API アクセス

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

    # Replace with your actual script token
    SCRIPT_TOKEN="your-script-token"
    API_BASE="https://webapi.teamviewer.com/api/v1"
    
    # Test API access
    curl -v -H "Authorization: Bearer ${SCRIPT_TOKEN}" \
      -H "Accept: application/json" \
      "${API_BASE}/reports/connections?from_date=2024-01-01T00:00:00Z&to_date=2024-01-01T01:00:00Z"
    

JSON データを含む 200 レスポンスを受け取った場合は、認証情報が正しく構成されています。

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

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

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

  1. GCP Console で、[IAM と管理>サービス アカウント] に移動します。
  2. [サービス アカウントを作成] をクリックします。
  3. 次の構成の詳細を指定します。
    • サービス アカウント名: 「teamviewer-collector-sa」と入力します。
    • サービス アカウントの説明: 「Service account for Cloud Run function to collect TeamViewer logs」と入力します。
  4. [作成して続行] をクリックします。
  5. [このサービス アカウントにプロジェクトへのアクセスを許可する] セクションで、次のロールを追加します。
    1. [ロールを選択] をクリックします。
    2. [ストレージ オブジェクト管理者] を検索して選択します。
    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. バケット名(teamviewer-logs など)をクリックします。
  3. [権限] タブに移動します。
  4. [アクセス権を付与] をクリックします。
  5. 次の構成の詳細を指定します。
    • プリンシパルを追加: サービス アカウントのメールアドレス(例: teamviewer-collector-sa@PROJECT_ID.iam.gserviceaccount.com)を入力します。
    • ロールを割り当てる: [Storage オブジェクト管理者] を選択します。
  6. [保存] をクリックします。

Pub/Sub トピックの作成

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

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

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

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

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

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

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

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

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

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

    1. [変数とシークレット] をクリックします。
    2. 環境変数ごとに [+ 変数を追加] をクリックします。
    変数名 値の例
    GCS_BUCKET teamviewer-logs
    GCS_PREFIX teamviewer/audit/
    STATE_KEY teamviewer/audit/state.json
    WINDOW_SECONDS 3600
    HTTP_TIMEOUT 60
    MAX_RETRIES 3
    USER_AGENT teamviewer-to-gcs/1.0
    SCRIPT_TOKEN your-script-token(TeamViewer の前提条件)
    API_BASE_URL https://webapi.teamviewer.com/api/v1
  10. [変数とシークレット] セクションで、[リクエスト] まで下にスクロールします。

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

    • [リソース] セクションで次の操作を行います。
      • メモリ: 512 MiB 以上を選択します。
      • CPU: [1] を選択します。
  12. [リビジョン スケーリング] セクションで、次の操作を行います。

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

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

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

関数コードを追加する

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

    • 最初のファイル: main.py:
    import functions_framework
    from google.cloud import storage
    import json
    import os
    import urllib.request
    import urllib.parse
    import urllib.error
    from datetime import datetime, timezone
    import time
    import uuid
    
    # Initialize Storage client
    storage_client = storage.Client()
    
    @functions_framework.cloud_event
    def main(cloud_event):
        """
        Cloud Run function triggered by Pub/Sub to fetch TeamViewer audit logs 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', 'teamviewer/audit/')
        state_key = os.environ.get('STATE_KEY', 'teamviewer/audit/state.json')
        window_sec = int(os.environ.get('WINDOW_SECONDS', '3600'))
        http_timeout = int(os.environ.get('HTTP_TIMEOUT', '60'))
        max_retries = int(os.environ.get('MAX_RETRIES', '3'))
        user_agent = os.environ.get('USER_AGENT', 'teamviewer-to-gcs/1.0')
    
        # TeamViewer API credentials
        api_base_url = os.environ.get('API_BASE_URL')
        script_token = os.environ.get('SCRIPT_TOKEN')
    
        if not all([bucket_name, api_base_url, script_token]):
            print('Error: Missing required environment variables')
            return
    
        try:
            # Get GCS bucket
            bucket = storage_client.bucket(bucket_name)
    
            # Load state (last processed timestamp)
            state = load_state(bucket, state_key)
            now = time.time()
            from_ts = float(state.get('last_to_ts') or (now - window_sec))
            to_ts = now
    
            print(f'Fetching TeamViewer audit data from {iso_format(from_ts)} to {iso_format(to_ts)}')
    
            # Build audit API URL
            url = build_audit_url(api_base_url, from_ts, to_ts)
    
            print(f'Fetching TeamViewer audit data from: {url}')
    
            # Fetch audit data with retries and pagination
            all_records = []
            offset_id = None
    
            while True:
                blob_data, content_type, next_offset = fetch_audit_data(
                    url, script_token, user_agent, http_timeout, max_retries, offset_id
                )
    
                # Validate JSON data
                try:
                    audit_data = json.loads(blob_data)
                    records = audit_data.get('records', [])
                    all_records.extend(records)
                    print(f"Retrieved {len(records)} audit records (total: {len(all_records)})")
    
                    # Check for pagination
                    if next_offset and len(records) == 1000:
                        offset_id = next_offset
                        print(f"Fetching next page with offset_id: {offset_id}")
                    else:
                        break
    
                except json.JSONDecodeError as e:
                    print(f"Warning: Invalid JSON received: {e}")
                    break
    
            if all_records:
                # Write to GCS
                key = put_audit_data(bucket, prefix, json.dumps({'records': all_records}), 
                                   'application/json', from_ts, to_ts)
                print(f'Successfully wrote {len(all_records)} audit records to {key}')
            else:
                print('No audit records found')
    
            # Update state
            state['last_to_ts'] = to_ts
            state['last_successful_run'] = now
            save_state(bucket, state_key, state)
    
        except Exception as e:
            print(f'Error processing TeamViewer 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: {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 iso_format(ts):
        """Convert Unix timestamp to ISO 8601 format."""
        return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(ts))
    
    def build_audit_url(api_base_url, from_ts, to_ts):
        """Build URL for TeamViewer audit API endpoint."""
        base_endpoint = f"{api_base_url.rstrip('/')}/reports/connections"
        params = {
            'from_date': iso_format(from_ts),
            'to_date': iso_format(to_ts)
        }
        query_string = urllib.parse.urlencode(params)
        return f"{base_endpoint}?{query_string}"
    
    def fetch_audit_data(url, script_token, user_agent, http_timeout, max_retries, offset_id=None):
        """Fetch audit data from TeamViewer API with retries and pagination support."""
        # Add offset_id parameter if provided
        if offset_id:
            separator = '&' if '?' in url else '?'
            url = f"{url}{separator}offset_id={offset_id}"
    
        attempt = 0
        while True:
            req = urllib.request.Request(url, method='GET')
            req.add_header('User-Agent', user_agent)
            req.add_header('Authorization', f'Bearer {script_token}')
            req.add_header('Accept', 'application/json')
    
            try:
                with urllib.request.urlopen(req, timeout=http_timeout) as r:
                    response_data = r.read()
                    content_type = r.headers.get('Content-Type') or 'application/json'
    
                    # Extract next_offset from response if present
                    try:
                        data = json.loads(response_data)
                        next_offset = data.get('next_offset')
                    except:
                        next_offset = None
    
                    return response_data, content_type, next_offset
    
            except urllib.error.HTTPError as e:
                if e.code == 429:
                    attempt += 1
                    print(f'Rate limited (429) on attempt {attempt}')
                    if attempt > max_retries:
                        raise
                    time.sleep(min(60, 2 ** attempt) + (time.time() % 1))
                else:
                    print(f'HTTP error {e.code}: {e.reason}')
                    raise
            except urllib.error.URLError as e:
                attempt += 1
                print(f'URL error on attempt {attempt}: {e}')
                if attempt > max_retries:
                    raise
                time.sleep(min(60, 2 ** attempt) + (time.time() % 1))
    
    def put_audit_data(bucket, prefix, blob_data, content_type, from_ts, to_ts):
        """Write audit data to GCS."""
        ts_path = time.strftime('%Y/%m/%d', time.gmtime(to_ts))
        uniq = f"{int(time.time() * 1e6)}_{uuid.uuid4().hex[:8]}"
        key = f"{prefix}{ts_path}/teamviewer_audit_{int(from_ts)}_{int(to_ts)}_{uniq}.json"
    
        blob = bucket.blob(key)
        blob.metadata = {
            'source': 'teamviewer-audit',
            'from_timestamp': str(int(from_ts)),
            'to_timestamp': str(int(to_ts))
        }
        blob.upload_from_string(blob_data, content_type=content_type)
    
        return key
    
    • 2 つ目のファイル: requirements.txt:
    functions-framework==3.*
    google-cloud-storage==2.*
    
  3. [デプロイ] をクリックして、関数を保存してデプロイします。

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

Cloud Scheduler ジョブの作成

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

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

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

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

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

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

統合をテストする

  1. Cloud Scheduler コンソールで、ジョブ(teamviewer-logs-collector-hourly)を見つけます。
  2. [強制実行] をクリックして、ジョブを手動でトリガーします。
  3. 数秒待ちます。
  4. Cloud Run > サービスに移動します。
  5. 関数名(teamviewer-logs-collector)をクリックします。
  6. [Logs] タブをクリックします。
  7. 関数が正常に実行されたことを確認します。次の内容を確認します。

    Fetching TeamViewer audit data from YYYY-MM-DDTHH:MM:SSZ to YYYY-MM-DDTHH:MM:SSZ
    Retrieved X audit records (total: X)
    Successfully wrote X audit records to teamviewer/audit/YYYY/MM/DD/teamviewer_audit_...json
    
  8. [Cloud Storage] > [バケット] に移動します。

  9. バケット名(teamviewer-logs)をクリックします。

  10. プレフィックス フォルダ(teamviewer/audit/)に移動します。

  11. 現在のタイムスタンプで新しい .json ファイルが作成されたことを確認します。

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

  • HTTP 401: SCRIPT_TOKEN 環境変数が TeamViewer スクリプト トークンと一致していることを確認します。
  • HTTP 403: スクリプト トークンに [接続レポート] > [接続レポートを表示] の権限があることを確認します。
  • HTTP 429: レート制限 - 関数は指数バックオフで自動的に再試行されます
  • 環境変数が不足している: 必要な変数(GCS_BUCKETAPI_BASE_URLSCRIPT_TOKEN)がすべて設定されていることを確認します。

Google SecOps サービス アカウントを取得する

Google SecOps は、一意のサービス アカウントを使用して GCS バケットからデータを読み取ります。このサービス アカウントにバケットへのアクセス権を付与する必要があります。

サービス アカウントのメールアドレスを取得する

  1. [SIEM 設定] > [フィード] に移動します。
  2. [Add New Feed] をクリックします。
  3. [単一フィードを設定] をクリックします。
  4. [フィード名] フィールドに、フィードの名前を入力します(例: TeamViewer logs)。
  5. [ソースタイプ] として [Google Cloud Storage V2] を選択します。
  6. [ログタイプ] として [TeamViewer] を選択します。
  7. [サービス アカウントを取得する] をクリックします。一意のサービス アカウント メールアドレスが表示されます(例:)。

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

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

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

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

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

  1. [SIEM 設定] > [フィード] に移動します。
  2. [Add New Feed] をクリックします。
  3. [単一フィードを設定] をクリックします。
  4. [フィード名] フィールドに、フィードの名前を入力します(例: TeamViewer logs)。
  5. [ソースタイプ] として [Google Cloud Storage V2] を選択します。
  6. [ログタイプ] として [TeamViewer] を選択します。
  7. [次へ] をクリックします。
  8. 次の入力パラメータの値を指定します。

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

      gs://teamviewer-logs/teamviewer/audit/
      
      • 次のように置き換えます。

        • teamviewer-logs: GCS バケット名。
        • teamviewer/audit/: ログが保存される接頭辞/フォルダパス。
    • Source deletion option: 必要に応じて削除オプションを選択します。

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

    • ファイルの最大経過日数: 指定した日数以内に変更されたファイルを含めます。デフォルトは 180 日です。

    • アセットの名前空間: アセットの名前空間

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

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

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

UDM マッピング テーブル

ログフィールド UDM マッピング 論理
AffectedItem metadata.product_log_id 未加工ログの AffectedItem の値は、この UDM フィールドに直接マッピングされます。
EventDetails.NewValue principal.resource.attribute.labels.value PropertyName に(server)が含まれている場合、NewValue は principal.resource.attribute.labels のラベルの値として使用されます。
EventDetails.NewValue principal.user.user_display_name PropertyName が Name of participant の場合、NewValue はプリンシパルのユーザー表示名として使用されます。
EventDetails.NewValue principal.user.userid PropertyName が参加者の ID の場合、NewValue はプリンシパルのユーザー ID として使用されます。
EventDetails.NewValue security_result.about.labels.value 他のすべての PropertyName 値(特定の条件で処理される値を除く)では、NewValue が security_result.about.labels 配列内のラベルの値として使用されます。
EventDetails.NewValue target.file.full_path PropertyName が Source file の場合、NewValue はターゲット ファイルのフルパスとして使用されます。
EventDetails.NewValue target.resource.attribute.labels.value PropertyName に(client)が含まれている場合、NewValue は target.resource.attribute.labels のラベルの値として使用されます。
EventDetails.NewValue target.user.user_display_name PropertyName が Name of presenter の場合、NewValue が解析されます。整数である場合は破棄されます。それ以外の場合は、ターゲットのユーザー表示名として使用されます。
EventDetails.NewValue target.user.userid PropertyName が発表者の ID の場合、NewValue はターゲットのユーザー ID として使用されます。
EventDetails.PropertyName principal.resource.attribute.labels.key PropertyName に(server)が含まれている場合、PropertyName は principal.resource.attribute.labels のラベルのキーとして使用されます。
EventDetails.PropertyName security_result.about.labels.key 他のすべての PropertyName 値(特定の条件で処理されるものを除く)については、PropertyName は security_result.about.labels 配列内のラベルのキーとして使用されます。
EventDetails.PropertyName target.resource.attribute.labels.key PropertyName に(client)が含まれている場合、PropertyName は target.resource.attribute.labels のラベルのキーとして使用されます。
EventName metadata.product_event_type 未加工ログの EventName の値は、この UDM フィールドに直接マッピングされます。
タイムスタンプ metadata.event_timestamp 未加工ログのタイムスタンプの値が解析され、メタデータのイベント タイムスタンプとして使用されます。
metadata.event_type src_user(参加者の ID から派生)が空でない場合は USER_UNCATEGORIZED に設定し、それ以外の場合は USER_RESOURCE_ACCESS に設定します。
metadata.vendor_name TEAMVIEWER にハードコードされています。
metadata.product_name TEAMVIEWER にハードコードされています。
network.application_protocol TEAMVIEWER にハードコードされています。

ご不明な点がございましたら、コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。