Google Backstory 公共 Protos 深度解析：SecOps 的 UDM 统一数据模型、实体建模与数据访问规范

Google Backstory 公共 Protos 深度解析：SecOps 的 UDM 统一数据模型、实体建模与数据访问规范

【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis

backstory/目录是 googleapis 仓库中面向安全运营（SecOps）场景的公共协议定义集，其 README 明确将其定位为"Common Data Access, Universal Data Model (UDM) and Entity protos used by Secops"（见 backstory/README.md）。本篇文章以该目录为核心，逐层拆解 UDM 统一事件模型、Entity 实体上下文、EntityRisk 风险评分、Collection 检测集合、Data Access 数据访问标签与 Id 命名空间的设计思路，并结合 backstory/udm.proto、backstory/entity.proto 等源码给出字段级说明，帮助读者掌握一套可用于安全日志标准化、威胁检测与调查工作流建模的完整 protobuf 协议体系。

Backstory 目录概览：一套服务于安全运营的公共协议族

backstory/目录下共包含 6 个 proto 文件、1 个服务配置 YAML 和 1 个 Bazel 构建文件，它们共同构成一个自洽的协议族：

一个值得注意的细节：README 中该协议服务于 "Secops"，而 backstory/backstory.yaml 的文档摘要写作 "used by Chronicle"，backstory/udm.proto 中也同时出现 "enriched by Chronicle" 与 backstory/entity_risk.proto 中的 "Google Security Operations UI" 等表述。从源码结构看，该协议族服务于 Google 安全运营产品线（Chronicle 为其前身命名），不同文档保留了各自的命名习惯。

UDM：统一数据模型的事件标准化

UDM 是整个协议族的核心。它的目标是：无论原始日志来自防火墙、EDR、DNS、邮件网关还是身份系统，都归一化为同一种结构化事件，使上层检测规则、调查界面和机器学习模型无需关心厂商差异。

UDM 顶层消息与六大"名词"角色

backstory/udm.proto 中的UDM消息（L36-L110）由以下部分组成：

这六个"名词"角色是 UDM 事件叙事的骨架。proto 注释给出了非常具体的建模规则：

• principal必须至少包含一个机器细节（hostname、MAC、IP、端口、产品特定 ID 如 EDR asset ID）或用户细节（如 username），可附带进程细节；禁止包含 email、files、registry keys/values 字段；
• src举例：用户 U 在机器 X 上将文件 A 复制到机器 Y 上的文件 B，则文件 A 与机器 X 都放进src；
• target举例：防火墙连接 A→B 中 A 是 principal、B 是 target；进程 C 向进程 D 注入时 C 是 principal、D 是 target；
• intermediary的关键约束是：无论中间方如何动作，principal/target 与初始动作描述必须保持一致——A→B 的成功连接与被防火墙 C 阻断的连接，都应表现为 principal: A、target: B（intermediary: C）。

Metadata：时间戳、事件类型与富化状态

Metadata消息（backstory/udm.proto L113-L767）承载事件级元信息，包含三个重要的枚举：

EventTimestampAttribute（L116-L330）用 70 余个枚举值精确描述event_timestamp所代表的时间语义，覆盖文件类（FILE_CREATION、LAST_ACCESSED、METADATA_LAST_CHANGED…）、账号类（LAST_LOGGED_IN、LAST_LOGIN_ATTEMPT、LAST_PASSWORD_SET…）、进程类（STARTED、EXITED、LAST_EXECUTED…）以及网络类（REQUEST_RECEIVED、RESPONSE_SENT…）等场景。早期几个枚举值（FILE_LAST_ACCESS_TIME 等）已标记deprecated = true，分别建议改用 LAST_ACCESSED、LAST_MODIFIED 等新值。

EventType（L341-L679）是 UDM 最重要的事件分类，按类别组织且用数字段区分：

proto 注释对 EventType 的使用给出了一条重要规则：不要依据产生日志的产品来选择事件类型，而要依据记录事件的组件来选择。例如，杀毒软件在客户端扫描邮件应生成 SMTP_PROXY 事件而非 AV 事件；DLP 设备扫描网页上传应生成 HTTP_PROXY 事件而非 DLP 事件。

EnrichmentState（L682-L691）标记事件是否已被 Chronicle 富化（ENRICHED / UNENRICHED）。

Metadata 其余关键字段包括：id（bytes，UDM 事件 ID，可用于原始/归一化事件检索）、product_log_id（厂商事件 GUID）、event_timestamp/collected_timestamp/ingested_timestamp（事件生成/采集/入站三个时间点）、vendor_name/product_name/product_version、log_type、parser_version、ingestion_labels（用户配置的摄取标签）以及tags（Chronicle 解析后添加的标签，注释明确要求解析器不得填充该字段）。

Network：网络事件的结构化细节

Network消息（backstory/udm.proto L799-L1246）统一存放所有网络细节，其中包含 4 个枚举与多类协议子消息：

• Direction：UNKNOWN_DIRECTION / INBOUND / OUTBOUND / BROADCAST；
• IpProtocol：覆盖 ICMP(1)、TCP(6)、UDP(17)、GRE(47)、ESP(50)、ICMP6(58)、SCTP(132) 等常用 IP 协议（取值沿用 IANA 协议号）；
• ApplicationProtocol：约 78 种应用层协议，涵盖 HTTP(2000)/HTTPS(2001)、DNS(3000)、DHCP(4000)、QUIC(1000)、SMTP(50)、SSH(52)、RDP(36)、SMB(49)、LDAP(23)、KERBEROS(KRB5=65)、TOR(57) 以及 OT/工控协议如 MODBUS(26)、DNP3(70)、IEC104(72)、GOOSE(71) 等，取值有独立编号体系；
• ConnectionState：LISTENING / ESTABLISHED / TIME_WAIT / CLOSE_WAIT / CLOSED / SYN_SENT 等 TCP 状态；
• 协议子消息：ftp、email、dns、dhcp、http、tls、smtp；其中Smtp（L1749-L1771）记录 HELO、MAIL FROM、RCPT TO、server_response、message_path、is_webmail、is_tls 等 SMTP 专有字段；
• 通用字段：sent_bytes/received_bytes/total_bytes、sent_packets/received_packets、session_duration、session_id/parent_session_id、community_id、asn、dns_domain、carrier_name、organization_name、ip_subnet_range、is_proxy及proxy_info。

ProxyInfo（L1248-L1282）进一步细分代理类型：anonymous、anonymous_vpn、public_proxy、tor_exit_node、smart_dns_proxy、hosting_provider、vpn_datacenter、residential_proxy、proxy_over_vpn、relay_proxy，并记录vpn_service_name，为检测代理隧道与 Tor 流量提供精确语义。

Extensions：承载一等事件的扩展区

Extensions消息（backstory/udm.proto L1284-L1324）明确"协议元数据不要放进 Extensions，应放入 Network"；Extensions 只存放事件特定的一等元数据，共 10 个子扩展：

认证扩展的 proto 注释还给出了 auth 事件的三角色建模指引：认证来源（客户端 IP/hostname）放principal，被登录/登出的机器放target，若经第三方（如公司 SSO 记录登录 Chronicle 云服务）则 SSO 方案放intermediary。

Entity：为 UDM 事件补充实体上下文

UDM 事件回答"发生了什么"，而Entity（backstory/entity.proto L206-L227）回答"这个实体是谁、什么背景"。proto 注释给出了典型场景：PROCESS_LAUNCH 事件只描述用户abc@example.corp启动了进程shady.exe，却不知道该用户是近期被解雇、管理着存放财务数据的服务器的离职员工——这些上下文由一条或多条 Entity 补充。

Entity 消息结构

message Entity { EntityMetadata metadata = 1; // 实体元数据：时间戳、产品、类型 Noun entity = 2; // 该实体在 UDM 事件中对应的 Noun repeated Relation relations = 4; // 实体与其他实体的关系 google.protobuf.Struct additional = 3; // 无法形式化表达的额外数据 optional EntityRisk risk_score = 5; // 实体风险评分 Metric metric = 6; // 预计算统计指标（entity_type 为 METRIC 时使用） }

EntityMetadata：实体类型与来源

EntityMetadata（L34-L148）定义了两组关键枚举：

• EntityType：ASSET(1)、USER(10000)、GROUP(10001)、RESOURCE(2)、IP_ADDRESS(3)、CIDR_BLOCK(9)、FILE(4)、DOMAIN_NAME(5)、URL(6)、MUTEX(7)、METRIC(8)；
• SourceType：ENTITY_CONTEXT（从客户摄取，如 AD_CONTEXT、DLP_CONTEXT）、DERIVED_CONTEXT（从客户数据推导，如 prevalence、first/last seen 统计）、GLOBAL_CONTEXT（全局上下文，如 WHOIS、Safe Browsing）。

其余字段包括product_entity_id（厂商实体 ID，如 GUID/LDAP/OID）、collected_timestamp/creation_timestamp、interval（实体版本有效时间区间）、vendor_name/product_name/product_version、feed（威胁情报源名称）、description、threat（识别实体为恶意的威胁情报 SecurityResult 列表）、source_labels、event_metadata、extracted与ati_prioritization。

AtiPrioritization：威胁情报优先级因子

AtiPrioritization（L152-L198）承载 ATI 策划规则用于计算实体优先级分数的各类因子：来自 GTI 的gti_verdict/gti_severity/gti_threat_score、mandiant_analyst_confidence、gti_update_time、active_ir（是否有 Mandiant 应急响应客户环境出现过该指标）、global_customer_count/global_hit_count（近 30 天）、exclusive（是否至多被一个威胁行为者使用）、osint、scanner、reviewed，以及attributed_malware/attributed_threat_actors（关联的恶意软件家族与威胁行为者，类型为SecurityResult.Association）。

Relation：实体关系建模

Relation（L230-L316）描述实体 a 与实体 b 之间的关系：

• Relationship：OWNS、ADMINISTERS、MEMBER、EXECUTES、DOWNLOADED_FROM、CONTACTS；
• Directionality：BIDIRECTIONAL（双向建模 a→b 与 b→a）、UNIDIRECTIONAL（单向 a→b）；
• EntityLabel：PRINCIPAL、TARGET、OBSERVER、SRC、NETWORK、SECURITY_RESULT、INTERMEDIARY——把关系中的 b 端对应回 UDM 的"名词"角色，实现事件角色与实体图谱的打通；
• 其余字段：entity（b 端 Noun）、entity_type、uid（关系 UID）。

Metric：预计算聚合指标

Metric（L319-L629）存放实体的预计算分析数据，用于支撑"实体画像"类查询，包含：

• AggregateFunction：MIN、MAX、COUNT、SUM、AVG、STDDEV；
• MetricName：40 种预定义指标，如 NETWORK_BYTES_INBOUND/OUTBOUND/TOTAL、AUTH_ATTEMPTS_SUCCESS/FAIL/TOTAL、DNS_QUERIES_SUCCESS/FAIL、FILE_EXECUTIONS_SUCCESS/FAIL、HTTP_QUERIES_SUCCESS/FAIL、WORKSPACE_EMAILS_SENT_TOTAL、RESOURCE_CREATION_SUCCESS/FAIL/TOTAL 等；
• Dimension：39 种分组维度，如 PRINCIPAL_DEVICE、TARGET_USER、PRINCIPAL_IP、TARGET_IP、PRINCIPAL_FILE_HASH、PRINCIPAL_COUNTRY、SECURITY_CATEGORY、NETWORK_ASN、DNS_DOMAIN、HTTP_USER_AGENT、LOG_TYPE 等；
• 字段：first_seen/last_seen、sum_measure、total_events、metric_name、dimensions、export_window，以及自定义指标的display_name、outcome_variables/match_variables（FindingVariable 类型）与time_range。

EntityRisk：实体风险评分模型

backstory/entity_risk.proto 从 entity.proto 中拆出，注释说明是为了避免 udm.proto 与 entity.proto 之间的循环依赖。EntityRisk（L37-L89）的核心字段：

RiskDelta（L92-L104）描述两个时间点之间的分数差异：previous_range_end_time、risk_score_delta（归一化分数差）、previous_risk_score、risk_score_numeric_delta（数值差）。

Collection：检测与调查工作流的容器

Collection（backstory/collection.proto L45-L199）把事件、实体上下文元数据、检测发现元数据与调查状态装进一个容器，覆盖从"检测发现 → 调查"的完整链路，可扩展建模包含多个子发现/子事件的 incident 以及修复动作。

关键字段与枚举：

• CollectionType（使用allow_alias）：TELEMETRY_ALERT(1)、GCTI_FINDING(2)（别名 UPPERCASE_ALERT）、RULE_DETECTION(3)、MACHINE_INTELLIGENCE_ALERT(4)、SOAR_ALERT(5)；
• DetectionTimingDetails：DETECTION_TIMING_DETAILS_REPROCESSING（重处理运行）、DETECTION_TIMING_DETAILS_RETROHUNT（回溯狩猎）；
• RunFrequency：REALTIME / HOURLY / DAILY；
• id（类型相关，规则检测时为 detection ID）、id_namespace（复用 Id.Namespace）、created_time/last_updated_time、time_window；
• collection_elements（repeated Element）：构成集合的元素，每个元素内的引用共享同一关联（correlation association）；
• detection（repeated SecurityResult）：检测元数据，可含规则细节、ML 模型元数据与涉及指标（用 .about 字段）；
• detection_time：多事件规则取时间窗结束时刻，单事件规则取事件时刻，迟达事件触发新告警时取事件时间；
• investigation：调查详情（分类、状态等）；
• tags、case_name（关联的 Case 资源名，格式projects/{project id}/locations/{region}/chronicle/cases/{internal_case_id}）、data_access_scope；
• SOAR 相关：soar_alert、soar_alert_metadata（源 SIEM 的 alert_id、source_rule、vendor、source_system、product、source_system_ticket_id、source_system_uri）、response_platform_info（SOAR 平台类型与告警 ID，目前支持 Siemplify）；
• 延迟度量：detection_timing_details、latency_metrics（LatencyMetrics：oldest/newest_ingestion_time、oldest/newest_event_time、ingestion_latency，由全部贡献事件计算而非仅采样）；
• 模拟事件：simulated_event_count与simulated_event_names（通过 ingestion_labels 中 key 为 SIMULATED 的标签标记，用于验证完整检测生命周期）。

Element（L299-L329）含association（SecurityResult 关联）、references（共享关联的 UDM/Entity 引用，单个元素内只含一种类型）、label、references_sampled（来自 detection 的 too_many_event_samples，为真时引用数被截断到采样上限）与latency_metrics。Reference（L268-L297）通过 one-of 引用event（UDM）或entity，并附带id、joined_data_table_rows（关联的数据表行）、graph_enrichment（实体图谱富化：APPEND 追加或 OVERRIDE 覆盖）与log_batch_token。

Data Access：数据访问标签

backstory/data_access.proto 定义安全运营场景下的数据访问控制标签：

• DataAccessIngestionLabel：摄取标签的 key/value 对；
• DataAccessLabels：log_types（LogType 标签列表）、namespaces、custom_labels（基于 UDM 搜索语法的复杂标签）、ingestion_kv_labels（key/value 摄取标签，取代已废弃的ingestion_labels）、allow_scoped_access（标签是否已就绪以支持作用域访问）。

这些标签被 Metadata 中的base_labels（基础事件的访问标签）与enrichment_labels（富化该事件的所有上下文事件的访问标签）所引用，实现"原始事件 + 富化来源"双轨的数据访问审计。

Id：统一标识与命名空间

backstory/id.proto 提供 UDM 对象（事件、实体、集合）的统一标识。Id.Namespace用高 32 位划分标识空间：NORMALIZED_TELEMETRY(0)、RAW_TELEMETRY(1)、RULE_DETECTIONS(2)、UPPERCASE(3)、MACHINE_INTELLIGENCE(4)、SECURITY_COMMAND_CENTER(5)、UNSPECIFIED(6)、SOAR_ALERT(7)、VIRUS_TOTAL(8)。Id消息本身是便于 RPC 使用的封装（namespace+idbytes +string_id，后者用于无法转成 bytes 的字符串 ID，如de_aaaaaaaa-aaaa...形式的检测 ID），注释说明持久化场景大多应使用反规范化的完整标识。

构建与发布：多语言覆盖

backstory/BUILD.bazel 展示了这套协议族的工程化程度：

• proto_library(name = "backstory_proto")聚合 6 个 proto，依赖//google/type:interval_proto、//google/type:latlng_proto以及 protobuf 的 duration/struct/timestamp；
• Go 产物：go_grpc_library(name = "backstory_go_proto")，importpath 为cloud.google.com/go/backstory/backstorypb（与各 proto 文件顶部的option go_package一致），并通过go_gapic_assembly_pkg生成backstory-go发布包；
• Python 产物：py_gapic_library指定warehouse-package-name=google-backstory、transport 为grpc+rest，生成backstory-py发布包；
• 其余语言：Java（java_gapic_assembly_gradle_pkg生成backstory-java）、PHP、Ruby、C#（package_name "Backstory"）、C++ 均有对应 target；
• backstory/backstory.yaml 声明服务名为backstory.googleapis.com、launch_stage 为 GA，并为 8 种语言统一配置了 PACKAGE_MANAGER 发布目标，说明该协议族已具备正式对外发布与消费的成熟度。

结语

从 backstory/README.md 的一句话定位出发，backstory/实际承载了一整套面向 SecOps 的公共协议：UDM 解决"多源日志如何归一化为统一事件叙事"，Entity 解决"事件背后的实体背景与关系图谱"，EntityRisk 解决"实体风险如何量化与追踪"，Collection 解决"检测发现到调查修复的全流程建模"，Data Access 与 Id 则分别解决"访问控制"与"跨命名空间标识"。这套协议族以 6 个 proto 文件相互引用（如 entity.proto 复用 udm.proto 的 Noun 与 Metadata，collection.proto 同时依赖 entity、id 与 udm），并通过 Bazel 规则面向 7 种语言产出可用代码，是理解 Google Security Operations 事件模型与检测数据结构的直接入口。

【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis