收集 Keeper Enterprise Security 日志

支持的平台:

本文档介绍了如何使用 Google Cloud Storage V2 将 Keeper Enterprise Security 日志注入到 Google Security Operations。

Keeper Enterprise Security 是一款企业密码管理和特权访问管理平台,可保护凭据、密钥和敏感数据。它通过 Reporting and Alerts API 生成保险柜访问、密码更改、共享事件和管理操作的审核日志。

准备工作

请确保满足以下前提条件:

  • Google SecOps 实例
  • 启用了 Cloud Storage API 的 GCP 项目
  • 创建和管理 GCS 存储桶的权限
  • 管理 GCS 存储桶的 IAM 政策的权限
  • 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
  • 对 Keeper 管理控制台的特权访问权限(具有管理员权限)
  • 已启用高级报告和提醒模块 (ARAM) 的 Keeper Enterprise 或 Business 方案

创建 Google Cloud Storage 存储桶

  1. 前往 Google Cloud 控制台。
  2. 选择您的项目或创建一个新项目。
  3. 在导航菜单中,依次前往 Cloud Storage > 存储桶。
  4. 点击创建存储分区。
  5. 提供以下配置详细信息:

    设置 值
    为存储桶命名 输入一个全局唯一的名称(例如 keeper-audit-logs)
    位置类型 根据您的需求进行选择(区域级、双区域级、多区域级)
    位置 选择位置(例如 us-central1)
    存储类别 标准(建议用于频繁访问的日志)
    访问权限控制 均匀(推荐)
    保护工具 可选:启用对象版本控制或保留政策
  6. 点击创建。

收集 Keeper Enterprise Security API 凭据

创建 API 密钥

  1. 登录 Keeper 管理控制台。
  2. 依次前往管理 > 报告和提醒。
  3. 点击 API 密钥,或前往 API 密钥管理部分。
  4. 点击创建 API 密钥。
  5. 输入 API 密钥的名称(例如 Google Security Operations Integration)。
  6. 请复制以下详细信息并将其保存在安全的位置:
    • API 密钥:生成的 API 密钥值
    • 私钥:下载私钥文件(用于生成令牌)
  7. 在管理控制台中记下 Keeper Enterprise 企业 ID。

确定 API 基本网址

  • Keeper API 基础网址取决于您的数据中心区域:

    区域 API 基本网址
    美国 https://keepersecurity.com
    欧盟 https://keepersecurity.eu
    AU https://keepersecurity.com.au
    CA https://keepersecurity.ca
    JP https://keepersecurity.jp
    美国 GovCloud https://govcloud.keepersecurity.us

验证权限

如需验证账号是否具有所需权限,请执行以下操作:

  1. 登录 Keeper 管理控制台。
  2. 依次前往管理 > 报告和提醒。
  3. 如果您能看到报告和提醒信息中心以及 API 密钥部分,则表示您拥有所需的权限。
  4. 如果您看不到此选项,请与 Keeper 管理员联系,以启用 ARAM 模块并授予管理员访问权限。

测试 API 访问权限

  • 在继续进行集成之前,请测试您的凭据:

    # Replace with your actual credentials
    KEEPER_API_KEY="your-api-key"
    KEEPER_BASE="https://keepersecurity.com"
    
    # Test API access - get audit events (requires signed token)
    # Note: Keeper uses a signed JWT for authentication.
    # Refer to Keeper Commander CLI for testing:
    keeper audit-report --format json --limit 1
    

为 Cloud Run 函数创建服务账号

Cloud Run 函数需要一个服务账号,该账号具有写入 GCS 存储桶和被 Pub/Sub 调用的权限。

创建服务账号

  1. 在 GCP 控制台中,依次前往 IAM 和管理 > 服务账号。
  2. 点击创建服务账号。
  3. 提供以下配置详细信息:
    • 服务账号名称:输入 keeper-logs-collector-sa
    • 服务账号说明:输入 Service account for Cloud Run function to collect Keeper Enterprise Security logs
  4. 点击创建并继续。
  5. 在向此服务账号授予对项目的访问权限部分,添加以下角色:
    1. 点击选择角色。
    2. 搜索并选择 Storage Object Admin。
    3. 点击 + 添加其他角色。
    4. 搜索并选择 Cloud Run Invoker。
    5. 点击 + 添加其他角色。
    6. 搜索并选择 Cloud Functions Invoker。
  6. 点击继续。
  7. 点击完成。

以下操作需要这些角色:

  • Storage Object Admin:将日志写入 GCS 存储桶并管理状态文件
  • Cloud Run Invoker:允许 Pub/Sub 调用函数
  • Cloud Functions Invoker:允许调用函数

授予对 GCS 存储桶的 IAM 权限

向服务账号授予对 GCS 存储桶的写入权限:

  1. 前往 Cloud Storage > 存储桶。
  2. 点击您的存储桶名称(例如 keeper-audit-logs)。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息:
    • 添加主账号:输入服务账号电子邮件地址(例如 keeper-logs-collector-sa@PROJECT_ID.iam.gserviceaccount.com)
    • 分配角色:选择 Storage Object Admin
  6. 点击保存。

创建 Pub/Sub 主题

创建一个 Pub/Sub 主题,供 Cloud Scheduler 发布消息,并供 Cloud Run 函数订阅。

  1. 在 GCP 控制台中,前往 Pub/Sub > 主题。
  2. 点击创建主题。
  3. 提供以下配置详细信息:
    • 主题 ID:输入 keeper-logs-trigger
    • 将其他设置保留为默认值
  4. 点击创建。

创建 Cloud Run 函数以收集日志

Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 Keeper Reporting and Alerts API 中提取日志并将其写入 GCS。

  1. 在 GCP 控制台中,前往 Cloud Run。
  2. 点击创建服务。
  3. 选择函数(使用内嵌编辑器创建函数)。
  4. 在配置部分中,提供以下配置详细信息:

    设置 值
    Service 名称 keeper-logs-collector
    区域 选择与您的 GCS 存储桶匹配的区域(例如 us-central1)
    运行时 选择 Python 3.12 或更高版本
  5. 在触发器(可选)部分中:

    1. 点击 + 添加触发器。
    2. 选择 Cloud Pub/Sub。
    3. 在选择 Cloud Pub/Sub 主题中,选择主题 keeper-logs-trigger。
    4. 点击保存。
  6. 在身份验证部分中:

    1. 选择需要进行身份验证。
    2. 检查 Identity and Access Management (IAM)。
  7. 向下滚动并展开容器、网络、安全性。

  8. 前往安全标签页:

    • 服务账号:选择服务账号 keeper-logs-collector-sa。
  9. 前往容器标签页:

    1. 点击变量和密钥。
    2. 为每个环境变量点击 + 添加变量:
    变量名称 示例值 说明
    GCS_BUCKET keeper-audit-logs GCS 存储桶名称
    GCS_PREFIX keeper 日志文件的前缀
    STATE_KEY keeper/state.json 状态文件路径
    KEEPER_API_BASE https://keepersecurity.com Keeper API 基本网址
    KEEPER_API_KEY your-api-key Keeper API 密钥
    KEEPER_PRIVATE_KEY base64-encoded-private-key Base64 编码的私钥
    KEEPER_ENTERPRISE_ID 12345 企业 ID
    MAX_RECORDS 5000 每次运行的记录数上限
    PAGE_SIZE 1000 每页记录数
    LOOKBACK_HOURS 24 初始回溯期
  10. 在变量和密钥部分中,向下滚动到请求:

    • 请求超时:输入 600 秒(10 分钟)
  11. 前往设置标签页:

    • 在资源部分中:
      • 内存:选择 512 MiB 或更高值
      • CPU:选择 1
  12. 在修订版本伸缩部分中:

    • 实例数下限:输入 0
    • 实例数上限:输入 100(或根据预期负载进行调整)
  13. 点击创建。

  14. 等待服务创建完成(1-2 分钟)。

  15. 创建服务后,系统会自动打开内嵌代码编辑器。

添加函数代码

  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
        import base64
        import hashlib
        import hmac
      
        # 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', 'keeper')
        STATE_KEY = os.environ.get('STATE_KEY', 'keeper/state.json')
        KEEPER_API_BASE = os.environ.get('KEEPER_API_BASE', 'https://keepersecurity.com')
        KEEPER_API_KEY = os.environ.get('KEEPER_API_KEY')
        KEEPER_PRIVATE_KEY = os.environ.get('KEEPER_PRIVATE_KEY')
        KEEPER_ENTERPRISE_ID = os.environ.get('KEEPER_ENTERPRISE_ID')
        MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000'))
        PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000'))
        LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
      
        def to_unix_millis(dt: datetime) -> int:
          """Convert datetime to Unix epoch milliseconds."""
          if dt.tzinfo is None:
            dt = dt.replace(tzinfo=timezone.utc)
          dt = dt.astimezone(timezone.utc)
          return int(dt.timestamp() * 1000)
      
        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)
      
        def get_auth_token():
          """
          Generate authentication token for Keeper Reporting API.
          Uses HMAC-SHA512 signing with the private key.
          """
          api_base = KEEPER_API_BASE.rstrip('/')
          token_url = f"{api_base}/api/rest/enterprise/auth/token"
      
          # Build token request
          timestamp = str(int(time.time()))
          message = f"{KEEPER_API_KEY}:{timestamp}"
      
          # Decode private key from base64
          private_key_bytes = base64.b64decode(KEEPER_PRIVATE_KEY)
      
          # Sign with HMAC-SHA512
          signature = hmac.new(
            private_key_bytes,
            message.encode('utf-8'),
            hashlib.sha512
          ).digest()
          signature_b64 = base64.b64encode(signature).decode('utf-8')
      
          body = json.dumps({
            'api_key': KEEPER_API_KEY,
            'timestamp': timestamp,
            'signature': signature_b64,
            'enterprise_id': KEEPER_ENTERPRISE_ID
          })
      
          headers = {
            'Content-Type': 'application/json',
            'Accept': 'application/json'
          }
      
          backoff = 1.0
          for attempt in range(3):
            response = http.request('POST', token_url, body=body, headers=headers)
      
            if response.status == 429:
              retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
              print(f"Rate limited (429) on token request. Retrying after {retry_after}s...")
              time.sleep(retry_after)
              backoff = min(backoff * 2, 30.0)
              continue
      
            if response.status != 200:
              raise RuntimeError(f"Failed to get auth token: {response.status} - {response.data.decode('utf-8')}")
      
            data = json.loads(response.data.decode('utf-8'))
            return data.get('token', data.get('access_token'))
      
          raise RuntimeError("Failed to get auth token after 3 retries")
      
        @functions_framework.cloud_event
        def main(cloud_event):
          """
          Cloud Run function triggered by Pub/Sub to fetch Keeper Enterprise
          Security audit logs and write to GCS.
      
          Args:
            cloud_event: CloudEvent object containing Pub/Sub message
          """
      
          if not all([GCS_BUCKET, KEEPER_API_KEY, KEEPER_PRIVATE_KEY, KEEPER_ENTERPRISE_ID]):
            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"])
                # Overlap by 2 minutes to catch any delayed events
                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()}")
      
            # Get auth token
            token = get_auth_token()
      
            # Fetch logs
            records, newest_event_time = fetch_logs(
              token=token,
              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(token: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int):
          """
          Fetch audit event logs from Keeper Reporting and Alerts API
          with pagination and rate limiting.
      
          Args:
            token: Authentication token
            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)
          """
          api_base = KEEPER_API_BASE.rstrip('/')
          endpoint = f"{api_base}/api/rest/enterprise/audit-events"
      
          headers = {
            'Authorization': f'Bearer {token}',
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'User-Agent': 'GoogleSecOps-KeeperCollector/1.0'
          }
      
          records = []
          newest_time = None
          page_num = 0
          backoff = 1.0
      
          # Convert to Unix epoch seconds for Keeper API
          start_epoch = int(start_time.timestamp())
          end_epoch = int(end_time.timestamp())
          cursor = None
      
          while True:
            page_num += 1
      
            if len(records) >= max_records:
              print(f"Reached max_records limit ({max_records})")
              break
      
            # Build request body
            body = {
              'start_time': start_epoch,
              'end_time': end_epoch,
              'limit': min(page_size, max_records - len(records)),
              'enterprise_id': KEEPER_ENTERPRISE_ID
            }
            if cursor:
              body['cursor'] = cursor
      
            try:
              response = http.request(
                'POST',
                endpoint,
                body=json.dumps(body),
                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.get('audit_events', data.get('events', []))
      
              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_ts = event.get('timestamp') or event.get('created')
                  if event_ts:
                    if isinstance(event_ts, (int, float)):
                      event_dt = datetime.fromtimestamp(event_ts, tz=timezone.utc)
                      event_time = event_dt.isoformat()
                    else:
                      event_time = str(event_ts)
                    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
              cursor = data.get('cursor') or data.get('next_cursor')
              if not cursor:
                print("No more pages (no next cursor)")
                break
      
            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
      
    • 第二个文件 - 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. 提供以下配置详细信息:

    设置 值
    名称 keeper-logs-collector-hourly
    区域 选择与 Cloud Run 函数相同的区域
    频率 0 * * * *(每小时整点)
    时区 选择时区(建议选择世界协调时间 [UTC])
    目标类型 Pub/Sub
    主题 选择主题 keeper-logs-trigger
    消息正文 {}(空 JSON 对象)
  4. 点击创建。

时间表频率选项

根据日志量和延迟时间要求选择频次:

频率 Cron 表达式 使用场景
每隔 5 分钟 */5 * * * * 大容量、低延迟
每隔 15 分钟 */15 * * * * 搜索量中等
每小时 0 * * * * 标准(推荐)
每 6 小时 0 */6 * * * 低量批处理
每天 0 0 * * * 历史数据收集

测试集成

  1. 在 Cloud Scheduler 控制台中,找到您的作业。
  2. 点击强制运行以手动触发作业。
  3. 等待几秒钟。
  4. 前往 Cloud Run > 服务。
  5. 点击 keeper-logs-collector。
  6. 点击日志标签页。
  7. 验证函数是否已成功执行。查找:

    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://keeper-audit-logs/keeper/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  8. 前往 Cloud Storage > 存储桶。

  9. 点击您的存储桶名称 (keeper-audit-logs)。

  10. 转到 keeper/ 文件夹。

  11. 验证是否已创建具有当前时间戳的新 .ndjson 文件。

如果您在日志中看到错误,请执行以下操作:

  • HTTP 401:检查环境变量中的 API 凭据
  • HTTP 403:在 Keeper 管理控制台中验证账号是否具有所需的 ARAM 权限
  • HTTP 429:速率限制 - 函数将自动重试并进行退避
  • 缺少环境变量:检查是否已设置所有必需的变量

在 Google SecOps 中配置 Feed 以注入 Keeper Enterprise Security 日志

  1. 前往 SIEM 设置 > Feed。
  2. 点击添加新 Feed。
  3. 点击配置单个 Feed。
  4. 在 Feed 名称字段中,输入 Feed 的名称(例如 Keeper Enterprise Security Logs)。
  5. 选择 Google Cloud Storage V2 作为来源类型。
  6. 选择 Keeper Enterprise Security 作为日志类型。
  7. 点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址,例如:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. 复制电子邮件地址。

  9. 点击下一步。

  10. 为以下输入参数指定值:

    • 存储桶网址:输入带有前缀路径的 GCS 存储桶 URI:

      gs://keeper-audit-logs/keeper/
      
      • 替换:
        • keeper-audit-logs:您的 GCS 存储桶名称。
        • keeper:存储日志的可选前缀/文件夹路径(留空表示根目录)。
    • 来源删除选项:根据您的偏好选择删除选项:

      • 永不:转移后永不删除任何文件(建议用于测试)。
      • 删除已转移的文件:成功转移后删除文件。
      • 删除已转移的文件和空目录:成功转移后删除文件和空目录。

    • 文件存在时间上限:包含在过去指定天数内修改过的文件(默认值为 180 天)

    • 资源命名空间:资源命名空间

    • 注入标签:要应用于此 Feed 中事件的标签

  11. 点击下一步。

  12. 在最终确定界面中查看新的 Feed 配置,然后点击提交。

向 Google SecOps 服务账号授予 IAM 权限

Google SecOps 服务账号需要对您的 GCS 存储桶具有 Storage Object Viewer 角色。

  1. 前往 Cloud Storage > 存储桶。
  2. 点击您的存储桶名称。
  3. 前往权限标签页。
  4. 点击授予访问权限。
  5. 提供以下配置详细信息:
    • 添加主账号:粘贴 Google SecOps 服务账号电子邮件地址
    • 分配角色:选择 Storage Object Viewer
  6. 点击保存。

UDM 映射表

日志字段 UDM 映射 逻辑
logData.channel extensions.auth.type 如果值位于 ["SSO", "MACHINE", "VPN", "PHYSICAL", "TACACS"] 中,则设置为大写值,否则设置为“AUTHTYPE_UNSPECIFIED”
logData.timestamp metadata.event_timestamp 使用 ISO8601 格式转换
logData.audit_event, logData.remote_address metadata.event_type 如果 audit_event 与“login”匹配且 remote_address 不为空,则设置为“USER_LOGIN”;否则,如果 remote_address 不为空,则设置为“STATUS_UPDATE”;否则设置为“GENERIC_EVENT”
logData.audit_event metadata.product_event_type 直接复制值
logData.enterprise_id metadata.product_log_id 已转换为字符串
metadata.product_name 设置为“KEEPER”
metadata.vendor_name 设置为“KEEPER”
logData.client_version network.http.parsed_user_agent 直接复制值,然后转换为 parseduseragent
logData.client_version network.http.user_agent 直接复制值
logData.remote_address principal.asset.ip 直接复制值
logData.remote_address principal.ip 直接复制值
logData.category security_result.category_details 从来源合并
logData.shared_folder_uid, logData.folder_uid security_result.detection_fields 合并为具有键“shared_folder_uid”和“folder_uid”的标签
logData.email target.user.email_addresses 从来源合并
logData.username target.user.userid 直接复制值

更新日志

查看相应解析器的更新日志

需要更多帮助?获得社区成员和 Google SecOps 专业人士的解答。