收集 Tenable CSPM 記錄

支援的國家/地區：

本文說明如何使用 Google Cloud Storage V2，將 Tenable CSPM 記錄檔擷取至 Google Security Operations。

Tenable CSPM (雲端安全防護管理) 是一種雲端安全平台，可偵測設定錯誤，並監控雲端環境的法規遵循狀況。Cloud Run 函式會依排程輪詢 Tenable CSPM API，以 NDJSON 格式將調查結果寫入 GCS bucket，而 Google SecOps 則會透過 GCS V2 資訊提供擷取這些結果。

事前準備

請確認您已完成下列事前準備事項：

  • Google SecOps 執行個體
  • 已啟用 Cloud Storage API 的 GCP 專案
  • 建立及管理 GCS bucket 的權限
  • 管理 Google Cloud Storage 值區 IAM 政策的權限
  • 建立 Cloud Run 服務、Pub/Sub 主題和 Cloud Scheduler 工作的權限
  • 具備管理員權限的 Tenable Cloud Security 控制台特殊權限存取權

建立 Google Cloud Storage bucket

  1. 前往 Google Cloud 控制台。
  2. 選取專案或建立新專案。
  3. 在導覽選單中，依序前往「Cloud Storage」>「Bucket」。
  4. 按一下「建立值區」。

  5. 請提供下列設定詳細資料：

    設定 值
    為 bucket 命名 輸入全域不重複的名稱 (例如 tenable-cspm-logs)
    位置類型 根據需求選擇 (區域、雙區域、多區域)
    位置 選取位置 (例如 us-central1)
    儲存空間級別 標準 (建議用於經常存取的記錄)
    存取控管 統一 (建議)
    保護工具 選用：啟用物件版本管理或資料保留政策

  6. 點選「建立」。

收集 Tenable CSPM API 憑證

產生 API 金鑰

  1. 以管理員身分登入 Tenable Cloud Security 控制台。
  2. 依序前往「設定」>「API 金鑰」。
  3. 按一下「產生」，即可建立新的 API 金鑰配對。
  4. 複製下列詳細資料並儲存到安全位置：
    • 存取金鑰：用於驗證的 API 存取金鑰。
    • 密鑰：用於驗證的 API 密鑰。

驗證權限

如要確認帳戶是否具備必要權限，請按照下列步驟操作：

  1. 登入 Tenable Cloud Security 控制台。
  2. 前往「調查結果」或「法規遵循」> 報表。
  3. 如果可以查看調查結果資料，表示您具備必要權限。
  4. 如果沒有看到這個選項，請與 Tenable 管理員聯絡，要求管理員存取權。

測試 API 存取權

  • 請先測試憑證，再繼續進行整合：

    # Replace with your actual credentials
ACCESS_KEY="your-access-key"
SECRET_KEY="your-secret-key"

# Test API access
curl -v -H "X-ApiKeys: accessKey=${ACCESS_KEY};secretKey=${SECRET_KEY}" \
  "https://cloud.tenable.com/cspm/v1/findings?limit=1"

為 Cloud Run 函式建立服務帳戶

Cloud Run 函式需要具備 GCS bucket 寫入權限，且可由 Pub/Sub 叫用的服務帳戶。

建立服務帳戶

  1. 在 GCP 控制台中，依序前往「IAM & Admin」(IAM 與管理) >「Service Accounts」(服務帳戶)。
  2. 按一下「Create Service Account」(建立服務帳戶)。
  3. 請提供下列設定詳細資料：
    • 服務帳戶名稱：輸入 tenable-cspm-collector-sa。
    • 服務帳戶說明：輸入 Service account for Cloud Run function to collect Tenable CSPM logs。
  4. 按一下「建立並繼續」。
  5. 在「將專案存取權授予這個服務帳戶」部分，新增下列角色：
    1. 按一下「選擇角色」。
    2. 搜尋並選取「Storage 物件管理員」。
    3. 點選「+ 新增其他角色」。
    4. 搜尋並選取「Cloud Run Invoker」。
    5. 點選「+ 新增其他角色」。
    6. 搜尋並選取「Cloud Functions Invoker」(Cloud Functions 叫用者)。
  6. 按一下「繼續」。
  7. 按一下 [完成]。

這些角色適用於：

  • Storage 物件管理員：將記錄檔寫入 GCS bucket，並管理狀態檔案
  • Cloud Run 叫用者：允許 Pub/Sub 叫用函式
  • Cloud Functions 叫用者：允許函式叫用

授予 GCS 值區的 IAM 權限

將 GCS bucket 的寫入權限授予服務帳戶：

  1. 依序前往「Cloud Storage」>「Buckets」。
  2. 按一下 bucket 名稱 (例如 tenable-cspm-logs)。
  3. 前往「權限」分頁標籤。
  4. 按一下「授予存取權」。
  5. 請提供下列設定詳細資料：
    • 新增主體：輸入服務帳戶電子郵件地址 (例如 tenable-cspm-collector-sa@your-project.iam.gserviceaccount.com)。
    • 指派角色：選取「Storage 物件管理員」。
  6. 按一下 [儲存]。

建立 Pub/Sub 主題

建立 Pub/Sub 主題，Cloud Scheduler 會將訊息發布至該主題，而 Cloud Run 函式會訂閱該主題。

  1. 在 GCP Console 中，前往「Pub/Sub」>「Topics」(主題)。
  2. 按一下「建立主題」。
  3. 請提供下列設定詳細資料：
    • 主題 ID：輸入 tenable-cspm-trigger。
    • 其他設定保留預設值。
  4. 點選「建立」。

建立 Cloud Run 函式來收集記錄

Cloud Run 函式會由 Cloud Scheduler 的 Pub/Sub 訊息觸發，從 Tenable CSPM API 擷取結果，並寫入 GCS。

  1. 前往 GCP Console 的「Cloud Run」。
  2. 按一下「Create service」(建立服務)。
  3. 選取「函式」 (使用內嵌編輯器建立函式)。

  4. 在「設定」部分，提供下列設定詳細資料：

    設定 值
    服務名稱 tenable-cspm-collector
    區域 選取與 GCS bucket 相符的區域 (例如 us-central1)
    執行階段 選取 Python 3.12 以上版本

  5. 在「Trigger (optional)」(觸發條件 (選用)) 專區：

    1. 按一下「+ 新增觸發條件」。
    2. 選取「Cloud Pub/Sub」。
    3. 在「選取 Cloud Pub/Sub 主題」中，選擇主題 tenable-cspm-trigger。
    4. 按一下 [儲存]。

  6. 在「Authentication」(驗證) 部分：

    1. 選取「需要驗證」。
    2. 檢查 Identity and Access Management (IAM)。

  7. 向下捲動並展開「容器」、「網路」和「安全性」。

  8. 前往「安全性」分頁：

    • 服務帳戶：選取服務帳戶 tenable-cspm-collector-sa。

  9. 前往「容器」分頁：

    1. 按一下「變數與密鑰」。
    2. 針對每個環境變數，按一下「+ 新增變數」：
    變數名稱 範例值 說明
    GCS_BUCKET tenable-cspm-logs GCS bucket 名稱
    GCS_PREFIX tenable-cspm 記錄檔的前置字串
    STATE_KEY tenable-cspm/state.json 狀態檔案路徑
    TENABLE_ACCESS_KEY your-access-key Tenable API 存取金鑰
    TENABLE_SECRET_KEY your-secret-key Tenable API 密鑰
    MAX_RECORDS 10000 每次執行的記錄數上限
    PAGE_SIZE 1000 每頁記錄數
    LOOKBACK_HOURS 24 初始回溯期

  10. 在「變數與密鑰」分頁中向下捲動至「要求」：

    • 要求逾時：輸入 600 秒 (10 分鐘)。

  11. 前往「容器」中的「設定」分頁：

    • 在「資源」部分：
      • 記憶體：選取 512 MiB 以上。
      • CPU：選取 1。
    • 按一下 [完成]。

  12. 向下捲動至「執行環境」：

    • 選取「預設」 (建議選項)。

  13. 在「修訂版本資源調度」部分：

    • 執行個體數量下限：輸入 0。
    • 「Maximum number of instances」(執行個體數量上限)：輸入 100 (或根據預期負載調整)。

  14. 點選「建立」。

  15. 等待服務建立完成 (1 到 2 分鐘)。

  16. 服務建立完成後，系統會自動開啟內嵌程式碼編輯器。

新增函式程式碼

  1. 在「函式進入點」中輸入 main。

  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', 'tenable-cspm')
STATE_KEY = os.environ.get('STATE_KEY', 'tenable-cspm/state.json')
ACCESS_KEY = os.environ.get('TENABLE_ACCESS_KEY')
SECRET_KEY = os.environ.get('TENABLE_SECRET_KEY')
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'))

API_BASE = 'https://cloud.tenable.com'

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 Tenable CSPM
    findings and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """

    if not all([GCS_BUCKET, ACCESS_KEY, SECRET_KEY]):
        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 findings from {last_time.isoformat()} to {now.isoformat()}")

        # Fetch findings
        records, newest_event_time = fetch_findings(
            start_time=last_time,
            end_time=now,
            page_size=PAGE_SIZE,
            max_records=MAX_RECORDS,
        )

        if not records:
            print("No new findings 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}/findings_{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 findings: {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_findings(start_time: datetime, end_time: datetime, page_size: int, max_records: int):
    """
    Fetch findings from Tenable CSPM API with pagination and rate limiting.

    Args:
        start_time: Start time for findings query
        end_time: End time for findings 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)
    """
    endpoint = f"{API_BASE}/cspm/v1/findings"

    headers = {
        'X-ApiKeys': f'accessKey={ACCESS_KEY};secretKey={SECRET_KEY}',
        'Accept': 'application/json',
        'User-Agent': 'GoogleSecOps-TenableCSPMCollector/1.0'
    }

    records = []
    newest_time = None
    page_num = 0
    backoff = 1.0
    offset = 0

    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}?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('findings', data.get('data', []))

            if not page_results:
                print(f"No more results (empty page)")
                break

            # Filter by time window
            filtered = []
            for finding in page_results:
                status_time = finding.get('statusUpdateTime') or finding.get('createdAt') or finding.get('updatedAt')
                if status_time:
                    try:
                        finding_dt = parse_datetime(status_time)
                        if finding_dt >= start_time and finding_dt <= end_time:
                            filtered.append(finding)
                    except Exception:
                        filtered.append(finding)
                else:
                    filtered.append(finding)

            print(f"Page {page_num}: Retrieved {len(page_results)} findings, {len(filtered)} in time window")
            records.extend(filtered)

            # Track newest event time
            for finding in filtered:
                try:
                    event_time = finding.get('statusUpdateTime') or finding.get('createdAt') or finding.get('updatedAt')
                    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 findings: {e}")
            return [], None

    print(f"Retrieved {len(records)} total findings from {page_num} pages")
    return records, newest_time
    • 第二個檔案：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 主控台的「Cloud Scheduler」。
  2. 點選「建立工作」。

  3. 請提供下列設定詳細資料：

    設定 值
    名稱 tenable-cspm-collector-hourly
    區域 選取與 Cloud Run 函式相同的區域
    頻率 0 * * * * (每小時整點)
    時區 選取時區 (建議使用世界標準時間)
    目標類型 Pub/Sub
    主題 選取主題 tenable-cspm-trigger
    郵件內文 {} (空白 JSON 物件)

  4. 點選「建立」。

排程頻率選項

根據記錄檔量和延遲時間要求選擇頻率：

頻率 Cron 運算式 用途
每 5 分鐘 */5 * * * * 大量、低延遲
每 15 分鐘 */15 * * * * 中等
每小時 0 * * * * 標準 (建議)
每 6 小時 0 */6 * * * 少量、批次處理
每日 0 0 * * * 歷來資料集合

測試整合項目

  1. 在 Cloud Scheduler 控制台中，找出您的工作 (tenable-cspm-collector-hourly)。
  2. 按一下「強制執行」即可手動觸發。
  3. 等待幾秒鐘，然後依序前往「Cloud Run」>「Services」(服務) >「tenable-cspm-collector」>「Logs」(記錄)。

  4. 確認函式是否已順利執行。請注意以下事項：

    Fetching findings from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
Page 1: Retrieved X findings, Y in time window
Wrote X records to gs://tenable-cspm-logs/tenable-cspm/findings_YYYYMMDD_HHMMSS.ndjson
Successfully processed X records

  5. 檢查 GCS 值區 (tenable-cspm-logs)，確認是否已寫入結果。

如果記錄中顯示錯誤：

  • HTTP 401：檢查環境變數中的 API 金鑰
  • HTTP 403：確認帳戶在 Tenable Cloud Security 控制台中具有管理員權限
  • HTTP 429：頻率限制 - 函式會自動重試，並延遲一段時間
  • 缺少環境變數：檢查是否已設定所有必要變數

在 Google SecOps 中設定動態饋給，擷取 Tenable CSPM 記錄

  1. 依序前往「SIEM 設定」>「動態饋給」。
  2. 按一下「新增動態消息」。
  3. 按一下「設定單一動態饋給」。
  4. 在「動態饋給名稱」欄位中輸入動態饋給名稱 (例如 Tenable CSPM Logs)。
  5. 選取「Google Cloud Storage V2」做為「來源類型」。
  6. 選取「Tenable CSPM」做為「記錄類型」。

  7. 按一下「取得服務帳戶」，系統會顯示專屬服務帳戶電子郵件地址，例如：

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com

  8. 複製這個電子郵件地址，後續步驟會用到。

  9. 點選「下一步」。

  10. 指定下列輸入參數的值：

    • 儲存空間 bucket URL：輸入 GCS bucket URI，並加上前置路徑：

      gs://tenable-cspm-logs/tenable-cspm/
      • 取代：
        • tenable-cspm-logs：您的 GCS bucket 名稱。
        • tenable-cspm/：儲存記錄的前置字元/資料夾路徑。

    • 來源刪除選項：根據偏好設定選取刪除選項：

      • 永不：移轉後一律不刪除任何檔案 (建議用於測試)。
      • 刪除已轉移的檔案：成功轉移檔案後刪除檔案。

      • 刪除已轉移的檔案和空白目錄：成功轉移後刪除檔案和空白目錄。

    • 檔案存在時間上限：包含在過去天數內修改的檔案 (預設為 180 天)。

    • 資產命名空間：資產命名空間。

    • 擷取標籤：要套用至這個動態饋給事件的標籤。

  11. 點選「下一步」。

  12. 在「Finalize」(完成) 畫面中檢查新的動態饋給設定，然後按一下「Submit」(提交)。

將 IAM 權限授予 Google SecOps 服務帳戶

Google SecOps 服務帳戶需要 GCS bucket 的「Storage 物件檢視者」角色。

  1. 依序前往「Cloud Storage」>「Buckets」。
  2. 按一下 bucket 名稱 (tenable-cspm-logs)。
  3. 前往「權限」分頁標籤。
  4. 按一下「授予存取權」。
  5. 請提供下列設定詳細資料：
    • 新增主體：貼上 Google SecOps 服務帳戶電子郵件地址。
    • 指派角色：選取「Storage 物件檢視者」。

  6. 按一下 [儲存]。

UDM 對應表

記錄欄位 UDM 對應 邏輯
statusUpdateTime、starred、remediation.console.steps、compliances、labels、serviceNowIncidentUrls、ticketLinks、findingType、identityProviderAccount、status、subStatus、title、type、sentBy additional.fields 與 statusUpdateTime、已加星號、remediation.console.steps、compliances 陣列中的每個項目、labels 陣列中的每個項目、serviceNowIncidentUrls 陣列中的每個項目、ticketLinks 陣列中的每個項目、findingType、identityProviderAccount、status、subStatus、title、type 和 sentBy 的鍵/值標籤合併 (如果 principal_user 不為空白)
說明 metadata.description 直接複製值
has_user、has_target_resource metadata.event_type 如果 has_user 和 has_target_resource 為 true，則設為「USER_RESOURCE_ACCESS」，否則設為「GENERIC_EVENT」
id metadata.product_log_id 直接複製值
metadata.product_name 設為「Tenable CSPM」
metadata.vendor_name 設為「Tenable CSPM」
連結 network.http.referral_url 直接複製值
來源 principal.resource.attribute.labels 與來源的鍵/值標籤合併
resourceOwnerPrincipals.0.principal.mail principal.user.email_addresses 直接複製值
說明、sentBy principal.user.userid 如果描述不為空白，則使用 grok 從描述中擷取 principal_user 的值，否則使用 sentBy
category security_result.category_details 直接複製值
policyName security_result.rule_name 直接複製值
嚴重性 security_result.severity 如果嚴重程度為「Low」，則設為 LOW；如果為「Medium」，則設為 MEDIUM；如果為「High」，則設為 HIGH；如果為「Critical」，則設為 CRITICAL
cloudProvider target.cloud.environment 如果 cloudProvider == "Azure"，請設為 MICROSOFT_AZURE；如果為「AWS」，請設為 AMAZON_WEB_SERVICES
accountName、accountPath、resourceEnvironment、resourceOwner、resources target.resource.attribute.labels 與 accountName、accountPath、resourceEnvironment 陣列中的每個項目、resourceOwner 陣列中的每個項目，以及 resources 陣列中的每個項目合併的鍵/值標籤
accountId target.resource.id 直接複製值

變更記錄

查看這個剖析器的變更記錄

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求答案。