收集 Armis 活动日志
解析器版本:3.0
本文档介绍了如何使用 Google Cloud Storage V2 将 Armis 活动日志注入到 Google Security Operations。
Armis Centrix 是一款企业级资产情报平台,旨在为受管设备、非受管设备和 IoT/OT 设备提供可见性和保护。Armis Activities 数据流可捕获受监控设备上观察到的网络活动事件,包括连接事件、协议使用情况、流量模式和安全相关活动。这些活动日志可以通过 Armis REST API 导出,并写入 GCS 存储桶以供 Google SecOps 提取。
准备工作
请确保满足以下前提条件:
- Google SecOps 实例
- 已启用 Cloud Storage API 的 GCP 项目
- 创建和管理 GCS 存储分区的权限
- 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
- 具有 API 访问权限的 Armis Centrix 实例
- 具有读取活动数据权限的 Armis API 密钥
生成 Armis API 密钥
- 在
https://<your-instance>.armis.com中登录 Armis Centrix 控制台。 - 依次前往设置 > 资产管理和安全 > API 管理。
- 点击创建以生成新的 API Secret 密钥。
- 系统会显示一个对话框,其中包含密钥。
- 复制并妥善保存此密钥。
验证 API 访问权限
在继续进行集成之前,请先测试您的凭据:
ARMIS_INSTANCE="https://your-instance.armis.com" ARMIS_SECRET_KEY="your-secret-key" # Get access token ACCESS_TOKEN=$(curl -s -X POST "${ARMIS_INSTANCE}/api/v1/access_token/" \ -d "secret_key=${ARMIS_SECRET_KEY}" \ | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['access_token'])") echo "Access Token: ${ACCESS_TOKEN}" # Test activity search curl -s "${ARMIS_INSTANCE}/api/v1/search/" \ -H "Authorization: ${ACCESS_TOKEN}" \ -G \ --data-urlencode "aql=in:activity timeFrame:\"1 Hours\"" \ --data-urlencode "length=1" \ --data-urlencode "fields=title,type,time,site,sensor,protocol,content,activityUUID" \ | python3 -m json.tool
创建 Google Cloud Storage 存储桶
- 前往 Google Cloud 控制台。
- 选择您的项目或创建新项目。
- 在导航菜单中,依次前往 Cloud Storage > 存储分区。
- 点击创建存储分区。
提供以下配置详细信息:
设置 值 为存储桶命名 输入一个全局唯一的名称(例如 armis-activity-logs)位置类型 根据您的需求进行选择(区域级、双区域、多区域) 位置 选择营业地点(例如 us-central1)存储类别 标准(建议用于经常访问的日志) 访问权限控制 均匀(推荐) 保护工具 可选:启用对象版本控制或保留政策 点击创建。
为 Cloud Run 函数创建服务账号
Cloud Run 函数需要一个服务账号,该账号具有写入 GCS 存储桶的权限,并且可以由 Pub/Sub 调用。
创建服务账号
- 在 GCP 控制台中,依次前往 IAM 和管理 > 服务账号。
- 点击创建服务账号。
- 提供以下配置详细信息:
- 服务账号名称:输入
armis-activities-collector-sa - 服务账号说明:输入
Service account for Cloud Run function to collect Armis activity logs
- 服务账号名称:输入
- 点击创建并继续。
- 在向此服务账号授予对项目的访问权限部分中,添加以下角色:
- 点击选择角色。
- 搜索并选择 Storage Object Admin。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Run Invoker。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Functions Invoker。
- 点击继续。
- 点击完成。
必须拥有这些角色,才能:
- Storage Object Admin:将日志写入 GCS 存储桶并管理状态文件
- Cloud Run Invoker:允许 Pub/Sub 调用函数
- Cloud Functions Invoker:允许调用函数
授予对 GCS 存储桶的 IAM 权限
向服务账号授予对 GCS 存储桶的写入权限:
- 前往 Cloud Storage > 存储分区。
- 点击您的存储桶名称。
- 前往权限标签页。
- 点击授予访问权限。
- 提供以下配置详细信息:
- 添加主账号:输入服务账号电子邮件地址(例如
armis-activities-collector-sa@PROJECT_ID.iam.gserviceaccount.com) - 分配角色:选择 Storage Object Admin
- 添加主账号:输入服务账号电子邮件地址(例如
- 点击保存。
创建 Pub/Sub 主题
创建一个 Pub/Sub 主题,Cloud Scheduler 将向该主题发布消息,而 Cloud Run 函数将订阅该主题。
- 在 GCP 控制台中,前往 Pub/Sub > 主题。
- 点击创建主题。
- 提供以下配置详细信息:
- 主题 ID:输入
armis-activities-trigger - 将其他设置保留为默认值
- 主题 ID:输入
- 点击创建。
创建 Cloud Run 函数以收集日志
Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 Armis REST API 中提取活动日志并将其写入 GCS。
- 在 GCP 控制台中,前往 Cloud Run。
- 点击创建服务。
- 选择函数(使用内嵌编辑器创建函数)。
在配置部分中,提供以下配置详细信息:
设置 值 Service 名称 armis-activities-collector区域 选择与您的 GCS 存储桶匹配的区域(例如 us-central1)运行时 选择 Python 3.12 或更高版本 在触发器(可选)部分中:
- 点击 + 添加触发器。
- 选择 Cloud Pub/Sub。
- 在选择 Cloud Pub/Sub 主题部分,选择主题
armis-activities-trigger。 - 点击保存。
在身份验证部分中:
- 选择需要进行身份验证。
- 检查 Identity and Access Management (IAM)。
向下滚动并展开容器、网络、安全性。
前往安全性标签页:
- 服务账号:选择服务账号
armis-activities-collector-sa
- 服务账号:选择服务账号
前往容器标签页:
- 点击变量和密钥。
- 为每个环境变量点击+ 添加变量:
变量名称 示例值 说明 GCS_BUCKETarmis-activity-logsGCS 存储桶名称 GCS_PREFIXarmis-activities日志文件的前缀 STATE_KEYarmis-activities/state.json状态文件路径 ARMIS_INSTANCE_URLhttps://your-instance.armis.comArmis 实例网址 ARMIS_SECRET_KEYyour-secret-keyArmis API 密钥 PAGE_SIZE1000每个 API 页面的记录数 MAX_RECORDS50000每次运行的记录数上限 LOOKBACK_HOURS2初始回溯期 在变量和 Secret 部分中,向下滚动到请求:
- 请求超时:输入
540秒(9 分钟)
- 请求超时:输入
前往设置标签页:
- 在资源部分中:
- 内存:选择 512 MiB 或更高值
- CPU:选择 1
- 在资源部分中:
在修订版本伸缩部分中:
- 实例数下限:输入
0 - 实例数上限:输入
100(或根据预期负载进行调整)
- 实例数下限:输入
点击创建。
等待服务创建完成(1-2 分钟)。
创建服务后,系统会自动打开内嵌代码编辑器。
添加函数代码
- 在入口点字段中输入 main。
在内嵌代码编辑器中,创建两个文件:
第一个文件 - main.py::
import functions_framework from google.cloud import storage import json import os import urllib3 import urllib.parse from datetime import datetime, timezone, timedelta import time # Initialize HTTP client with timeouts http = urllib3.PoolManager( timeout=urllib3.Timeout(connect=5.0, read=60.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', 'armis-activities').strip('/') STATE_KEY = os.environ.get('STATE_KEY') or f"{GCS_PREFIX}/state.json" ARMIS_INSTANCE_URL = os.environ.get('ARMIS_INSTANCE_URL', '').rstrip('/') ARMIS_SECRET_KEY = os.environ.get('ARMIS_SECRET_KEY') PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000')) MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '50000')) LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '2')) ACTIVITY_FIELDS = [ 'title', 'type', 'time', 'site', 'sensor', 'protocol', 'content', 'activityUUID' ] def parse_datetime(value): """Parse ISO datetime string to datetime object.""" if not value: return None if value.endswith("Z"): value = value[:-1] + "+00:00" try: return datetime.fromisoformat(value) except Exception: try: return datetime.strptime(value, '%Y-%m-%dT%H:%M:%S') except Exception: return None def get_access_token(): """Obtain an access token from the Armis API.""" url = f"{ARMIS_INSTANCE_URL}/api/v1/access_token/" body = urllib.parse.urlencode({'secret_key': ARMIS_SECRET_KEY}) response = http.request( 'POST', url, body=body, headers={'Content-Type': 'application/x-www-form-urlencoded'} ) if response.status != 200: raise Exception( f"Failed to get access token: HTTP {response.status} - " f"{response.data.decode('utf-8')}" ) data = json.loads(response.data.decode('utf-8')) return data['data']['access_token'] @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch Armis Activity records and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ if not all([GCS_BUCKET, ARMIS_INSTANCE_URL, ARMIS_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"]) # Overlap by 2 minutes to catch delayed events if last_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 activity logs from " f"{last_time.isoformat()} to {now.isoformat()}" ) # Get access token access_token = get_access_token() print("Successfully obtained Armis access token.") # Fetch activity logs records, newest_event_time = fetch_activity_logs( access_token=access_token, start_time=last_time, end_time=now, ) if not records: print("No new activity 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 " f"gs://{GCS_BUCKET}/{object_key}" ) # Update state 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 activity 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): """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_activity_logs(access_token, start_time, end_time): """ Fetch activity logs from Armis REST API with pagination. Args: access_token: Armis API access token start_time: Start time for log query end_time: End time for log query Returns: Tuple of (records list, newest_event_time ISO string) """ base_url = f"{ARMIS_INSTANCE_URL}/api/v1/search/" headers = {'Authorization': access_token} # Build AQL query with time filter start_str = start_time.strftime('%Y-%m-%dT%H:%M:%S') aql_query = f'in:activity after:{start_str}' records = [] newest_time = None page_from = 0 backoff = 1.0 while True: if len(records) >= MAX_RECORDS: print(f"Reached max_records limit ({MAX_RECORDS})") break params = { 'aql': aql_query, 'from': str(page_from), 'orderBy': 'time', 'length': str(PAGE_SIZE), 'fields': ','.join(ACTIVITY_FIELDS), } try: response = http.request( 'GET', base_url, fields=params, 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). " f"Retrying after {retry_after}s..." ) time.sleep(retry_after) backoff = min(backoff * 2, 30.0) continue # Handle token expiry if response.status == 401: print("Access token expired, refreshing...") access_token = get_access_token() headers = {'Authorization': access_token} 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 records, newest_time data = json.loads(response.data.decode('utf-8')) result = data.get('data', {}).get('results', []) total = data.get('data', {}).get('total', 0) count = data.get('data', {}).get('count', 0) next_from = data.get('data', {}).get('next') if not result: print(f"No more results (empty page)") break print( f"Page from={page_from}: Retrieved {count} events " f"(total: {total})" ) records.extend(result) # Track newest event time for event in result: try: event_time = event.get('time') if event_time: if newest_time is None: newest_time = event_time else: current_dt = parse_datetime(event_time) newest_dt = parse_datetime(newest_time) if ( current_dt and newest_dt and current_dt > newest_dt ): newest_time = event_time except Exception as e: print( f"Warning: Could not parse " f"event time: {e}" ) # Check pagination if next_from is None or count < PAGE_SIZE: print("Reached last page") break page_from = next_from except Exception as e: print(f"Error fetching activity logs: {e}") return records, newest_time print(f"Retrieved {len(records)} total activity records") return records, newest_time第二个文件 - requirements.txt::
functions-framework==3.* google-cloud-storage==2.* urllib3>=2.0.0
点击部署以保存并部署该函数。
等待部署完成(2-3 分钟)。
创建 Cloud Scheduler 作业
Cloud Scheduler 会定期向 Pub/Sub 主题发布消息,从而触发 Cloud Run 函数。
- 在 GCP Console 中,前往 Cloud Scheduler。
- 点击创建作业。
提供以下配置详细信息:
设置 值 名称 armis-activities-collector-hourly区域 选择与 Cloud Run 函数相同的区域 频率 0 * * * *(每小时一次,整点时)时区 选择时区(建议选择世界协调时间 [UTC]) 目标类型 Pub/Sub 主题 选择主题 armis-activities-trigger消息正文 {}(空 JSON 对象)点击创建。
时间表频率选项
根据日志量和延迟时间要求选择频次:
| 频率 | Cron 表达式 | 使用场景 |
|---|---|---|
| 每隔 10 分钟 | */10 * * * * |
高成交量,近乎实时 |
| 每小时 | 0 * * * * |
标准(推荐) |
| 每 2 小时 | 0 */2 * * * |
调低音量 |
测试集成
- 在 Cloud Scheduler 控制台中,找到您的作业。
- 点击强制运行以手动触发作业。
- 等待几秒钟。
- 前往 Cloud Run > 服务。
- 点击函数名称
armis-activities-collector。 - 点击日志标签页。
验证函数是否已成功执行。查找:
Fetching activity logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00 Successfully obtained Armis access token. Page from=0: Retrieved X events (total: Y) Wrote X records to gs://armis-activity-logs/armis-activities/logs_YYYYMMDD_HHMMSS.ndjson Successfully processed X records前往 Cloud Storage > 存储分区。
点击您的存储桶名称。
前往前缀文件夹
armis-activities/。验证是否已创建具有当前时间戳的新
.ndjson文件。
如果您在日志中看到错误,请执行以下操作:
- HTTP 400:检查 AQL 查询语法是否正确。验证 Armis 实例网址是否没有尾随斜杠。
- HTTP 401:访问令牌已过期或无效。该函数会在出现 401 错误时自动刷新令牌。
- HTTP 429:速率限制 - 函数将自动重试并进行退避。
- “未找到访问令牌”:验证 Armis API Secret 密钥是否正确。
- 缺少环境变量:检查是否已设置所有必需的变量。
在 Google SecOps 中配置 Feed 以注入 Armis 活动日志
- 依次前往 SIEM 设置 > Feed。
- 点击添加新 Feed。
- 点击配置单个 Feed。
- 在 Feed 名称字段中,输入 Feed 的名称(例如
Armis Activities)。 - 选择 Google Cloud Storage V2 作为来源类型。
- 选择 Armis 活动作为日志类型。
点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址,例如:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com复制此电子邮件地址,以便在下一步中使用。
点击下一步。
为以下输入参数指定值:
存储桶网址:输入带有前缀路径的 GCS 存储桶 URI:
gs://armis-activity-logs/armis-activities/- 替换:
armis-activity-logs:您的 GCS 存储桶名称。armis-activities:存储日志的可选前缀/文件夹路径(留空表示根目录)。
- 替换:
来源删除选项:根据您的偏好选择删除选项:
- 永不:转移后永不删除任何文件(建议用于测试)。
- 删除已转移的文件:在成功转移后删除文件。
- 删除已转移的文件和空目录:成功转移后删除文件和空目录。
文件存在时间上限:包含在过去指定天数内修改过的文件(默认值为 180 天)
资产命名空间:资产命名空间
注入标签:要应用于此 Feed 中事件的标签
点击下一步。
在最终确定界面中查看新的 Feed 配置,然后点击提交。
向 Google SecOps 服务账号授予 IAM 权限
Google SecOps 服务账号需要您的 GCS 存储桶的 Storage Object Viewer 角色。
- 前往 Cloud Storage > 存储分区。
- 点击您的存储桶名称。
- 前往权限标签页。
- 点击授予访问权限。
- 提供以下配置详细信息:
- 添加主账号:粘贴 Google SecOps 服务账号电子邮件地址
- 分配角色:选择 Storage Object Viewer
- 点击保存。
UDM 映射表
| 日志字段 | UDM 映射 | 逻辑 |
|---|---|---|
activity_data_decision_client_offered_suites_list |
additional.fields |
已合并 |
activity_data_decision_src_device_id_label |
additional.fields |
已合并 |
activity_decision_data_category_label |
additional.fields |
已合并 |
activity_decision_data_client_device_id_label |
additional.fields |
已合并 |
activity_decision_data_connection_label |
additional.fields |
已合并 |
activity_decision_data_risk_factor_category_label |
additional.fields |
已合并 |
activity_decision_data_risk_factor_description_label |
additional.fields |
已合并 |
activity_decision_data_risk_factor_id_label |
additional.fields |
已合并 |
activity_decision_data_risk_factor_score_label |
additional.fields |
已合并 |
activity_type_label |
additional.fields |
已合并 |
policy_action_action_params_alert_classification_id |
additional.fields |
已合并 |
policy_action_action_params_alert_description |
additional.fields |
已合并 |
policy_action_action_params_emailRecipients_label |
additional.fields |
已合并 |
policy_action_action_params_endpoint |
additional.fields |
已合并 |
policy_action_action_params_timeBack_label |
additional.fields |
已合并 |
policy_action_action_params_title |
additional.fields |
已合并 |
policy_creation_time_label |
additional.fields |
已合并 |
policy_is_active_label |
additional.fields |
已合并 |
policy_is_boundary_label |
additional.fields |
已合并 |
policy_is_editable_label |
additional.fields |
已合并 |
policy_list_labels |
additional.fields |
已合并 |
policy_modification_time_label |
additional.fields |
已合并 |
policy_owner_label |
additional.fields |
已合并 |
policy_rules_and_list |
additional.fields |
已合并 |
selected_suite_label |
additional.fields |
已合并 |
source_list_boundaries |
additional.fields |
已合并 |
source_list_dataSources |
additional.fields |
已合并 |
source_sensor_name_label |
additional.fields |
已合并 |
source_sensor_type_label |
additional.fields |
已合并 |
token_vlunerabilities |
extensions.vulns.vulnerabilities |
已合并 |
type |
extensions.vulns.vulnerabilities |
已映射:Risk Factor Updated → token_vlunerabilities |
title |
metadata.description |
直接映射 |
time |
metadata.event_timestamp |
解析为 yyyy-MM-ddTHH:mm:ss.SSSZZ |
timestamp |
metadata.event_timestamp |
解析为 yyyy-MM-dd HH:mm:ss ZZ |
has_principal |
metadata.event_type |
已映射:true → STATUS_UPDATE |
has_target |
metadata.event_type |
已映射:true → NETWORK_CONNECTION |
has_user |
metadata.event_type |
已映射:true → USER_UNCATEGORIZED |
type |
metadata.product_event_type |
直接映射 |
activityUUID |
metadata.product_log_id |
直接映射 |
activity_uuid |
metadata.product_log_id |
直接映射 |
activity_type |
network.dns.answers |
已映射:DNS_QUERY → answers_temp |
answers_temp |
network.dns.answers |
已合并 |
activity_type |
network.dns.questions |
已映射:DNS_QUERY → questions_temp |
questions_temp |
network.dns.questions |
已合并 |
token_connection_id |
network.session_id |
直接映射 |
decision_data_version |
network.tls.version |
直接映射 |
deviceId |
principal.asset.asset_id |
直接映射 |
token_device_id |
principal.asset.attribute.labels |
已合并 |
token_device_name |
principal.asset.attribute.labels |
已合并 |
temp_principal_hostname |
principal.asset.hostname |
直接映射 |
decision_src_ip |
principal.asset.ip |
已合并 |
temp_principal_ip |
principal.asset.ip |
已合并 |
temp_principal_ipv6 |
principal.asset.ip |
已合并 |
temp_principal_asset_mac |
principal.asset.mac |
已合并 |
temp_principal_asset_mac |
principal.asset.product_object_id |
直接映射 |
temp_principal_hostname |
principal.hostname |
直接映射 |
decision_src_ip |
principal.ip |
已合并 |
temp_principal_ip |
principal.ip |
已合并 |
temp_principal_ipv6 |
principal.ip |
已合并 |
temp_principal_location_country |
principal.location.country_or_region |
直接映射 |
temp_principal_location_name |
principal.location.name |
直接映射 |
temp_principal_asset_mac |
principal.mac |
已合并 |
source_model_label |
principal.user.attribute.labels |
已合并 |
source_type_label |
principal.user.attribute.labels |
已合并 |
source_user |
principal.user.user_display_name |
直接映射 |
source_id |
principal.user.userid |
直接映射 |
decision_target_ip |
target.asset.hostname |
直接映射 |
decision_target_ip |
target.asset.ip |
已合并 |
decision_target_ip |
target.hostname |
直接映射 |
decision_target_ip |
target.ip |
已合并 |
target_ip |
target.ip |
已合并 |
token_interface_name |
target.labels |
已合并 |
decision_target_port |
target.port |
直接映射 |
| 不适用 | metadata.event_type |
常量:NETWORK_CONNECTION |
| 不适用 | metadata.product_name |
常量:ARMIS |
| 不适用 | metadata.vendor_name |
常量:ARMIS |
| 不适用 | network.application_protocol |
常量:HTTPS |
更新日志
需要更多帮助?获得社区成员和 Google SecOps 专业人士的解答。