Google Backstory 公共 Protos 深度解析SecOps 的 UDM 统一数据模型、实体建模与数据访问规范【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapisbackstory/目录是 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 构建文件它们共同构成一个自洽的协议族文件职责backstory/udm.proto定义 UDMUnified Data Model统一数据模型事件、Metadata、Network、Extensions、Noun、File、User 等核心消息是整套协议的地基约 6600 行字段覆盖极广backstory/entity.proto定义 Entity 实体上下文、EntityMetadata、Relation 关系、Metric 预计算指标、AtiPrioritization 威胁情报优先级backstory/entity_risk.proto定义 EntityRisk 实体风险评分与 RiskDelta 风险变化量backstory/collection.proto定义 Collection 集合检测/告警/调查的容器、Element、Reference、LatencyMetrics 等backstory/data_access.proto定义 DataAccessLabels / DataAccessIngestionLabel 数据访问标签backstory/id.proto定义 Id 与 Id.Namespace 标识命名空间backstory/backstory.yaml服务配置name: backstory.googleapis.com标题 Malachite Common Protos声明文档摘要为 Common Universal Data Model (UDM) and Entity protos used by Chroniclebackstory/BUILD.bazelBazel 构建规则为 Java/Go/Python/PHP/Ruby/C#/C 生成多语言产物一个值得注意的细节README 中该协议服务于 Secops而 backstory/backstory.yaml 的文档摘要写作 used by Chroniclebackstory/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由以下部分组成字段类型语义metadataMetadata事件元数据时间戳、来源产品、事件类型等additionalgoogle.protobuf.Struct无法放入正式字段的厂商特有数据principalNoun发起活动的行为主体发起者srcNoun被参与者作用的对象及其所在的设备/进程上下文源targetNoun事件指向的目标实体或目标上的对象目标intermediaryrepeated Noun处理活动流经的中间实体如代理、SMTP 中继observerNoun观察并上报事件、但非直接中间方的实体如抓包器、扫描器aboutrepeated Noun事件提及但不属于上述角色的实体如邮件附件、正文内嵌域名/URL/IP、PROCESS_LAUNCH 中加载的 DLLsecurity_resultrepeated SecurityResult安全检测结果列表networkNetwork网络细节含各协议子消息extensionsExtensions其他一等事件元数据扩展extractedgoogle.protobuf.Struct从日志中提取的扁平化字段groupedoptional GroupedFields分组关联的 UDM 字段这六个名词角色是 UDM 事件叙事的骨架。proto 注释给出了非常具体的建模规则principal必须至少包含一个机器细节hostname、MAC、IP、端口、产品特定 ID 如 EDR asset ID或用户细节如 username可附带进程细节禁止包含 email、files、registry keys/values 字段src举例用户 U 在机器 X 上将文件 A 复制到机器 Y 上的文件 B则文件 A 与机器 X 都放进srctarget举例防火墙连接 A→B 中 A 是 principal、B 是 target进程 C 向进程 D 注入时 C 是 principal、D 是 targetintermediary的关键约束是无论中间方如何动作principal/target 与初始动作描述必须保持一致——A→B 的成功连接与被防火墙 C 阻断的连接都应表现为 principal: A、target: Bintermediary: C。Metadata时间戳、事件类型与富化状态Metadata消息backstory/udm.proto L113-L767承载事件级元信息包含三个重要的枚举EventTimestampAttributeL116-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 等新值。EventTypeL341-L679是 UDM 最重要的事件分类按类别组织且用数字段区分类别取值范围示例进程类PROCESS_UNCATEGORIZED(10000)、PROCESS_LAUNCH(10001)、PROCESS_INJECTION(10002)、PROCESS_PRIVILEGE_ESCALATION(10003)、PROCESS_MODULE_LOAD(10006)注册表类REGISTRY_CREATION(11001)、REGISTRY_MODIFICATION(11002)、REGISTRY_DELETION(11003)文件类FILE_CREATION(14001)、FILE_DELETION(14002)、FILE_COPY(14005)、FILE_MOVE(14007)、FILE_SYNC(14008)用户类USER_LOGIN(15001)、USER_LOGOUT(15002)、USER_CREATION(15003)、USER_BADGE_IN(15007)、USER_COMMUNICATION(15012)网络类NETWORK_FLOW(16001)、NETWORK_CONNECTION(16002)、NETWORK_FTP(16003)、NETWORK_DHCP(16004)、NETWORK_DNS(16005)、NETWORK_HTTP(16006)、NETWORK_SMTP(16007)状态类STATUS_HEARTBEAT(17001)、STATUS_STARTUP(17002)、STATUS_UPDATE(17004)扫描类SCAN_FILE(18001)、SCAN_PROCESS(18003)、SCAN_HOST(18004)、SCAN_VULN_HOST(18005)、SCAN_VULN_NETWORK(18006)邮件类EMAIL_TRANSACTION(19001)EMAIL_URL_CLICK 已废弃改用 NETWORK_HTTP计划任务类SCHEDULED_TASK_CREATION(20001)、SCHEDULED_TASK_ENABLE(20003)服务类SERVICE_CREATION(22001)、SERVICE_START(22003)、SERVICE_STOP(22004)群组类GROUP_CREATION(23001)分析人员类ANALYST_UPDATE_VERDICT(24000)、ANALYST_ADD_COMMENT(24008)、ANALYST_UPDATE_PRIORITY(24009)、ANALYST_UPDATE_RISK_SCORE(24012)资源类RESOURCE_CREATION(1)、RESOURCE_READ(4)、RESOURCE_WRITTEN(5)其他ENTITY_RISK_CHANGE(26000)、TRIAGE_AGENT_UPDATE_INVESTIGATION(27000)、GENERIC_EVENT(100000)proto 注释对 EventType 的使用给出了一条重要规则不要依据产生日志的产品来选择事件类型而要依据记录事件的组件来选择。例如杀毒软件在客户端扫描邮件应生成 SMTP_PROXY 事件而非 AV 事件DLP 设备扫描网页上传应生成 HTTP_PROXY 事件而非 DLP 事件。EnrichmentStateL682-L691标记事件是否已被 Chronicle 富化ENRICHED / UNENRICHED。Metadata 其余关键字段包括idbytesUDM 事件 ID可用于原始/归一化事件检索、product_log_id厂商事件 GUID、event_timestamp/collected_timestamp/ingested_timestamp事件生成/采集/入站三个时间点、vendor_name/product_name/product_version、log_type、parser_version、ingestion_labels用户配置的摄取标签以及tagsChronicle 解析后添加的标签注释明确要求解析器不得填充该字段。Network网络事件的结构化细节Network消息backstory/udm.proto L799-L1246统一存放所有网络细节其中包含 4 个枚举与多类协议子消息DirectionUNKNOWN_DIRECTION / INBOUND / OUTBOUND / BROADCASTIpProtocol覆盖 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(KRB565)、TOR(57) 以及 OT/工控协议如 MODBUS(26)、DNP3(70)、IEC104(72)、GOOSE(71) 等取值有独立编号体系ConnectionStateLISTENING / ESTABLISHED / TIME_WAIT / CLOSE_WAIT / CLOSED / SYN_SENT 等 TCP 状态协议子消息ftp、email、dns、dhcp、http、tls、smtp其中SmtpL1749-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。ProxyInfoL1248-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应放入 NetworkExtensions 只存放事件特定的一等元数据共 10 个子扩展扩展用途auth认证扩展AuthTypeMACHINE/SSO/VPN/PHYSICAL/TACACS、MechanismUSERNAME_PASSWORD、HARDWARE_KEY、BIOMETRIC、WEARABLE、BADGE_READER、CACHED_INTERACTIVE 等 20 种、OutcomeSUCCESS/FAILUREvulns漏洞扩展Vulnerability 含 Severity(LOW/MEDIUM/HIGH/CRITICAL)、cvss_base_score、cvss_vector、cve_id、cve_description、vendor_vulnerability_id 等entity_risk实体风险变化扩展复用 entity_risk.proto 的 EntityRisklinux_utmpLinux Utmp 登录/登出会话记录RUN_LVL、BOOT_TIME、USER_PROCESS、DEAD_PROCESS 等windows_event_logWindows 事件日志SECURITY/SYSTEM/APPLICATION/SETUP 等 channel、event_id、activity_idresource_usage记录进程/用户对资源的占用used_entity、used_entity_idsystem_event_details系统级事件细节message_type、sender_image_id、subsystemoutlook_metadataOutlook 项元数据comment、template、title、security_flags_countsrumWindows SRUM 应用资源消耗背景读/写字节数、上下文切换、CPU cycle 等user_assistWindows User Assist 应用使用追踪聚焦次数/时长、执行次数认证扩展的 proto 注释还给出了 auth 事件的三角色建模指引认证来源客户端 IP/hostname放principal被登录/登出的机器放target若经第三方如公司 SSO 记录登录 Chronicle 云服务则 SSO 方案放intermediary。Entity为 UDM 事件补充实体上下文UDM 事件回答发生了什么而Entitybackstory/entity.proto L206-L227回答这个实体是谁、什么背景。proto 注释给出了典型场景PROCESS_LAUNCH 事件只描述用户abcexample.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实体类型与来源EntityMetadataL34-L148定义了两组关键枚举EntityTypeASSET(1)、USER(10000)、GROUP(10001)、RESOURCE(2)、IP_ADDRESS(3)、CIDR_BLOCK(9)、FILE(4)、DOMAIN_NAME(5)、URL(6)、MUTEX(7)、METRIC(8)SourceTypeENTITY_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威胁情报优先级因子AtiPrioritizationL152-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实体关系建模RelationL230-L316描述实体 a 与实体 b 之间的关系RelationshipOWNS、ADMINISTERS、MEMBER、EXECUTES、DOWNLOADED_FROM、CONTACTSDirectionalityBIDIRECTIONAL双向建模 a→b 与 b→a、UNIDIRECTIONAL单向 a→bEntityLabelPRINCIPAL、TARGET、OBSERVER、SRC、NETWORK、SECURITY_RESULT、INTERMEDIARY——把关系中的 b 端对应回 UDM 的名词角色实现事件角色与实体图谱的打通其余字段entityb 端 Noun、entity_type、uid关系 UID。Metric预计算聚合指标MetricL319-L629存放实体的预计算分析数据用于支撑实体画像类查询包含AggregateFunctionMIN、MAX、COUNT、SUM、AVG、STDDEVMetricName40 种预定义指标如 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 等Dimension39 种分组维度如 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_variablesFindingVariable 类型与time_range。EntityRisk实体风险评分模型backstory/entity_risk.proto 从 entity.proto 中拆出注释说明是为了避免 udm.proto 与 entity.proto 之间的循环依赖。EntityRiskL37-L89的核心字段字段语义risk_version风险评分算法版本risk_window/risk_window_size计算风险的时间窗口如 24 小时、7 天risk_score原始风险分数floatnormalized_risk_score归一化风险分数取值 0-1000risk_delta/raw_risk_delta归一化/原始分数较上一时间窗口的变化detections_count窗口内构成风险分数的检测数量first_detection_time/last_detection_time窗口内首个/最近检测时间无检测时为空last_reset_timeUEBA 风险分重置去重时间戳用于基于风险的元规则detail_uri指向 Google Security Operations UI 中实体风险详情页的链接多前端路径时为相对路径risk_window_has_new_detections窗口内是否有新检测RiskDeltaL92-L104描述两个时间点之间的分数差异previous_range_end_time、risk_score_delta归一化分数差、previous_risk_score、risk_score_numeric_delta数值差。Collection检测与调查工作流的容器Collectionbackstory/collection.proto L45-L199把事件、实体上下文元数据、检测发现元数据与调查状态装进一个容器覆盖从检测发现 → 调查的完整链路可扩展建模包含多个子发现/子事件的 incident 以及修复动作。关键字段与枚举CollectionType使用allow_aliasTELEMETRY_ALERT(1)、GCTI_FINDING(2)别名 UPPERCASE_ALERT、RULE_DETECTION(3)、MACHINE_INTELLIGENCE_ALERT(4)、SOAR_ALERT(5)DetectionTimingDetailsDETECTION_TIMING_DETAILS_REPROCESSING重处理运行、DETECTION_TIMING_DETAILS_RETROHUNT回溯狩猎RunFrequencyREALTIME / HOURLY / DAILYid类型相关规则检测时为 detection ID、id_namespace复用 Id.Namespace、created_time/last_updated_time、time_windowcollection_elementsrepeated Element构成集合的元素每个元素内的引用共享同一关联correlation associationdetectionrepeated SecurityResult检测元数据可含规则细节、ML 模型元数据与涉及指标用 .about 字段detection_time多事件规则取时间窗结束时刻单事件规则取事件时刻迟达事件触发新告警时取事件时间investigation调查详情分类、状态等tags、case_name关联的 Case 资源名格式projects/{project id}/locations/{region}/chronicle/cases/{internal_case_id}、data_access_scopeSOAR 相关soar_alert、soar_alert_metadata源 SIEM 的 alert_id、source_rule、vendor、source_system、product、source_system_ticket_id、source_system_uri、response_platform_infoSOAR 平台类型与告警 ID目前支持 Siemplify延迟度量detection_timing_details、latency_metricsLatencyMetricsoldest/newest_ingestion_time、oldest/newest_event_time、ingestion_latency由全部贡献事件计算而非仅采样模拟事件simulated_event_count与simulated_event_names通过 ingestion_labels 中 key 为 SIMULATED 的标签标记用于验证完整检测生命周期。ElementL299-L329含associationSecurityResult 关联、references共享关联的 UDM/Entity 引用单个元素内只含一种类型、label、references_sampled来自 detection 的 too_many_event_samples为真时引用数被截断到采样上限与latency_metrics。ReferenceL268-L297通过 one-of 引用eventUDM或entity并附带id、joined_data_table_rows关联的数据表行、graph_enrichment实体图谱富化APPEND 追加或 OVERRIDE 覆盖与log_batch_token。Data Access数据访问标签backstory/data_access.proto 定义安全运营场景下的数据访问控制标签DataAccessIngestionLabel摄取标签的 key/value 对DataAccessLabelslog_typesLogType 标签列表、namespaces、custom_labels基于 UDM 搜索语法的复杂标签、ingestion_kv_labelskey/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 使用的封装namespaceidbytes 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/timestampGo 产物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-namegoogle-backstory、transport 为grpcrest生成backstory-py发布包其余语言Javajava_gapic_assembly_gradle_pkg生成backstory-java、PHP、Ruby、C#package_name Backstory、C 均有对应 targetbackstory/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 与 Metadatacollection.proto 同时依赖 entity、id 与 udm并通过 Bazel 规则面向 7 种语言产出可用代码是理解 Google Security Operations 事件模型与检测数据结构的直接入口。【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Google Backstory 公共 Protos 深度解析：SecOps 的 UDM 统一数据模型、实体建模与数据访问规范
Google Backstory 公共 Protos 深度解析SecOps 的 UDM 统一数据模型、实体建模与数据访问规范【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapisbackstory/目录是 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 构建文件它们共同构成一个自洽的协议族文件职责backstory/udm.proto定义 UDMUnified Data Model统一数据模型事件、Metadata、Network、Extensions、Noun、File、User 等核心消息是整套协议的地基约 6600 行字段覆盖极广backstory/entity.proto定义 Entity 实体上下文、EntityMetadata、Relation 关系、Metric 预计算指标、AtiPrioritization 威胁情报优先级backstory/entity_risk.proto定义 EntityRisk 实体风险评分与 RiskDelta 风险变化量backstory/collection.proto定义 Collection 集合检测/告警/调查的容器、Element、Reference、LatencyMetrics 等backstory/data_access.proto定义 DataAccessLabels / DataAccessIngestionLabel 数据访问标签backstory/id.proto定义 Id 与 Id.Namespace 标识命名空间backstory/backstory.yaml服务配置name: backstory.googleapis.com标题 Malachite Common Protos声明文档摘要为 Common Universal Data Model (UDM) and Entity protos used by Chroniclebackstory/BUILD.bazelBazel 构建规则为 Java/Go/Python/PHP/Ruby/C#/C 生成多语言产物一个值得注意的细节README 中该协议服务于 Secops而 backstory/backstory.yaml 的文档摘要写作 used by Chroniclebackstory/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由以下部分组成字段类型语义metadataMetadata事件元数据时间戳、来源产品、事件类型等additionalgoogle.protobuf.Struct无法放入正式字段的厂商特有数据principalNoun发起活动的行为主体发起者srcNoun被参与者作用的对象及其所在的设备/进程上下文源targetNoun事件指向的目标实体或目标上的对象目标intermediaryrepeated Noun处理活动流经的中间实体如代理、SMTP 中继observerNoun观察并上报事件、但非直接中间方的实体如抓包器、扫描器aboutrepeated Noun事件提及但不属于上述角色的实体如邮件附件、正文内嵌域名/URL/IP、PROCESS_LAUNCH 中加载的 DLLsecurity_resultrepeated SecurityResult安全检测结果列表networkNetwork网络细节含各协议子消息extensionsExtensions其他一等事件元数据扩展extractedgoogle.protobuf.Struct从日志中提取的扁平化字段groupedoptional GroupedFields分组关联的 UDM 字段这六个名词角色是 UDM 事件叙事的骨架。proto 注释给出了非常具体的建模规则principal必须至少包含一个机器细节hostname、MAC、IP、端口、产品特定 ID 如 EDR asset ID或用户细节如 username可附带进程细节禁止包含 email、files、registry keys/values 字段src举例用户 U 在机器 X 上将文件 A 复制到机器 Y 上的文件 B则文件 A 与机器 X 都放进srctarget举例防火墙连接 A→B 中 A 是 principal、B 是 target进程 C 向进程 D 注入时 C 是 principal、D 是 targetintermediary的关键约束是无论中间方如何动作principal/target 与初始动作描述必须保持一致——A→B 的成功连接与被防火墙 C 阻断的连接都应表现为 principal: A、target: Bintermediary: C。Metadata时间戳、事件类型与富化状态Metadata消息backstory/udm.proto L113-L767承载事件级元信息包含三个重要的枚举EventTimestampAttributeL116-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 等新值。EventTypeL341-L679是 UDM 最重要的事件分类按类别组织且用数字段区分类别取值范围示例进程类PROCESS_UNCATEGORIZED(10000)、PROCESS_LAUNCH(10001)、PROCESS_INJECTION(10002)、PROCESS_PRIVILEGE_ESCALATION(10003)、PROCESS_MODULE_LOAD(10006)注册表类REGISTRY_CREATION(11001)、REGISTRY_MODIFICATION(11002)、REGISTRY_DELETION(11003)文件类FILE_CREATION(14001)、FILE_DELETION(14002)、FILE_COPY(14005)、FILE_MOVE(14007)、FILE_SYNC(14008)用户类USER_LOGIN(15001)、USER_LOGOUT(15002)、USER_CREATION(15003)、USER_BADGE_IN(15007)、USER_COMMUNICATION(15012)网络类NETWORK_FLOW(16001)、NETWORK_CONNECTION(16002)、NETWORK_FTP(16003)、NETWORK_DHCP(16004)、NETWORK_DNS(16005)、NETWORK_HTTP(16006)、NETWORK_SMTP(16007)状态类STATUS_HEARTBEAT(17001)、STATUS_STARTUP(17002)、STATUS_UPDATE(17004)扫描类SCAN_FILE(18001)、SCAN_PROCESS(18003)、SCAN_HOST(18004)、SCAN_VULN_HOST(18005)、SCAN_VULN_NETWORK(18006)邮件类EMAIL_TRANSACTION(19001)EMAIL_URL_CLICK 已废弃改用 NETWORK_HTTP计划任务类SCHEDULED_TASK_CREATION(20001)、SCHEDULED_TASK_ENABLE(20003)服务类SERVICE_CREATION(22001)、SERVICE_START(22003)、SERVICE_STOP(22004)群组类GROUP_CREATION(23001)分析人员类ANALYST_UPDATE_VERDICT(24000)、ANALYST_ADD_COMMENT(24008)、ANALYST_UPDATE_PRIORITY(24009)、ANALYST_UPDATE_RISK_SCORE(24012)资源类RESOURCE_CREATION(1)、RESOURCE_READ(4)、RESOURCE_WRITTEN(5)其他ENTITY_RISK_CHANGE(26000)、TRIAGE_AGENT_UPDATE_INVESTIGATION(27000)、GENERIC_EVENT(100000)proto 注释对 EventType 的使用给出了一条重要规则不要依据产生日志的产品来选择事件类型而要依据记录事件的组件来选择。例如杀毒软件在客户端扫描邮件应生成 SMTP_PROXY 事件而非 AV 事件DLP 设备扫描网页上传应生成 HTTP_PROXY 事件而非 DLP 事件。EnrichmentStateL682-L691标记事件是否已被 Chronicle 富化ENRICHED / UNENRICHED。Metadata 其余关键字段包括idbytesUDM 事件 ID可用于原始/归一化事件检索、product_log_id厂商事件 GUID、event_timestamp/collected_timestamp/ingested_timestamp事件生成/采集/入站三个时间点、vendor_name/product_name/product_version、log_type、parser_version、ingestion_labels用户配置的摄取标签以及tagsChronicle 解析后添加的标签注释明确要求解析器不得填充该字段。Network网络事件的结构化细节Network消息backstory/udm.proto L799-L1246统一存放所有网络细节其中包含 4 个枚举与多类协议子消息DirectionUNKNOWN_DIRECTION / INBOUND / OUTBOUND / BROADCASTIpProtocol覆盖 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(KRB565)、TOR(57) 以及 OT/工控协议如 MODBUS(26)、DNP3(70)、IEC104(72)、GOOSE(71) 等取值有独立编号体系ConnectionStateLISTENING / ESTABLISHED / TIME_WAIT / CLOSE_WAIT / CLOSED / SYN_SENT 等 TCP 状态协议子消息ftp、email、dns、dhcp、http、tls、smtp其中SmtpL1749-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。ProxyInfoL1248-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应放入 NetworkExtensions 只存放事件特定的一等元数据共 10 个子扩展扩展用途auth认证扩展AuthTypeMACHINE/SSO/VPN/PHYSICAL/TACACS、MechanismUSERNAME_PASSWORD、HARDWARE_KEY、BIOMETRIC、WEARABLE、BADGE_READER、CACHED_INTERACTIVE 等 20 种、OutcomeSUCCESS/FAILUREvulns漏洞扩展Vulnerability 含 Severity(LOW/MEDIUM/HIGH/CRITICAL)、cvss_base_score、cvss_vector、cve_id、cve_description、vendor_vulnerability_id 等entity_risk实体风险变化扩展复用 entity_risk.proto 的 EntityRisklinux_utmpLinux Utmp 登录/登出会话记录RUN_LVL、BOOT_TIME、USER_PROCESS、DEAD_PROCESS 等windows_event_logWindows 事件日志SECURITY/SYSTEM/APPLICATION/SETUP 等 channel、event_id、activity_idresource_usage记录进程/用户对资源的占用used_entity、used_entity_idsystem_event_details系统级事件细节message_type、sender_image_id、subsystemoutlook_metadataOutlook 项元数据comment、template、title、security_flags_countsrumWindows SRUM 应用资源消耗背景读/写字节数、上下文切换、CPU cycle 等user_assistWindows User Assist 应用使用追踪聚焦次数/时长、执行次数认证扩展的 proto 注释还给出了 auth 事件的三角色建模指引认证来源客户端 IP/hostname放principal被登录/登出的机器放target若经第三方如公司 SSO 记录登录 Chronicle 云服务则 SSO 方案放intermediary。Entity为 UDM 事件补充实体上下文UDM 事件回答发生了什么而Entitybackstory/entity.proto L206-L227回答这个实体是谁、什么背景。proto 注释给出了典型场景PROCESS_LAUNCH 事件只描述用户abcexample.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实体类型与来源EntityMetadataL34-L148定义了两组关键枚举EntityTypeASSET(1)、USER(10000)、GROUP(10001)、RESOURCE(2)、IP_ADDRESS(3)、CIDR_BLOCK(9)、FILE(4)、DOMAIN_NAME(5)、URL(6)、MUTEX(7)、METRIC(8)SourceTypeENTITY_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威胁情报优先级因子AtiPrioritizationL152-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实体关系建模RelationL230-L316描述实体 a 与实体 b 之间的关系RelationshipOWNS、ADMINISTERS、MEMBER、EXECUTES、DOWNLOADED_FROM、CONTACTSDirectionalityBIDIRECTIONAL双向建模 a→b 与 b→a、UNIDIRECTIONAL单向 a→bEntityLabelPRINCIPAL、TARGET、OBSERVER、SRC、NETWORK、SECURITY_RESULT、INTERMEDIARY——把关系中的 b 端对应回 UDM 的名词角色实现事件角色与实体图谱的打通其余字段entityb 端 Noun、entity_type、uid关系 UID。Metric预计算聚合指标MetricL319-L629存放实体的预计算分析数据用于支撑实体画像类查询包含AggregateFunctionMIN、MAX、COUNT、SUM、AVG、STDDEVMetricName40 种预定义指标如 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 等Dimension39 种分组维度如 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_variablesFindingVariable 类型与time_range。EntityRisk实体风险评分模型backstory/entity_risk.proto 从 entity.proto 中拆出注释说明是为了避免 udm.proto 与 entity.proto 之间的循环依赖。EntityRiskL37-L89的核心字段字段语义risk_version风险评分算法版本risk_window/risk_window_size计算风险的时间窗口如 24 小时、7 天risk_score原始风险分数floatnormalized_risk_score归一化风险分数取值 0-1000risk_delta/raw_risk_delta归一化/原始分数较上一时间窗口的变化detections_count窗口内构成风险分数的检测数量first_detection_time/last_detection_time窗口内首个/最近检测时间无检测时为空last_reset_timeUEBA 风险分重置去重时间戳用于基于风险的元规则detail_uri指向 Google Security Operations UI 中实体风险详情页的链接多前端路径时为相对路径risk_window_has_new_detections窗口内是否有新检测RiskDeltaL92-L104描述两个时间点之间的分数差异previous_range_end_time、risk_score_delta归一化分数差、previous_risk_score、risk_score_numeric_delta数值差。Collection检测与调查工作流的容器Collectionbackstory/collection.proto L45-L199把事件、实体上下文元数据、检测发现元数据与调查状态装进一个容器覆盖从检测发现 → 调查的完整链路可扩展建模包含多个子发现/子事件的 incident 以及修复动作。关键字段与枚举CollectionType使用allow_aliasTELEMETRY_ALERT(1)、GCTI_FINDING(2)别名 UPPERCASE_ALERT、RULE_DETECTION(3)、MACHINE_INTELLIGENCE_ALERT(4)、SOAR_ALERT(5)DetectionTimingDetailsDETECTION_TIMING_DETAILS_REPROCESSING重处理运行、DETECTION_TIMING_DETAILS_RETROHUNT回溯狩猎RunFrequencyREALTIME / HOURLY / DAILYid类型相关规则检测时为 detection ID、id_namespace复用 Id.Namespace、created_time/last_updated_time、time_windowcollection_elementsrepeated Element构成集合的元素每个元素内的引用共享同一关联correlation associationdetectionrepeated SecurityResult检测元数据可含规则细节、ML 模型元数据与涉及指标用 .about 字段detection_time多事件规则取时间窗结束时刻单事件规则取事件时刻迟达事件触发新告警时取事件时间investigation调查详情分类、状态等tags、case_name关联的 Case 资源名格式projects/{project id}/locations/{region}/chronicle/cases/{internal_case_id}、data_access_scopeSOAR 相关soar_alert、soar_alert_metadata源 SIEM 的 alert_id、source_rule、vendor、source_system、product、source_system_ticket_id、source_system_uri、response_platform_infoSOAR 平台类型与告警 ID目前支持 Siemplify延迟度量detection_timing_details、latency_metricsLatencyMetricsoldest/newest_ingestion_time、oldest/newest_event_time、ingestion_latency由全部贡献事件计算而非仅采样模拟事件simulated_event_count与simulated_event_names通过 ingestion_labels 中 key 为 SIMULATED 的标签标记用于验证完整检测生命周期。ElementL299-L329含associationSecurityResult 关联、references共享关联的 UDM/Entity 引用单个元素内只含一种类型、label、references_sampled来自 detection 的 too_many_event_samples为真时引用数被截断到采样上限与latency_metrics。ReferenceL268-L297通过 one-of 引用eventUDM或entity并附带id、joined_data_table_rows关联的数据表行、graph_enrichment实体图谱富化APPEND 追加或 OVERRIDE 覆盖与log_batch_token。Data Access数据访问标签backstory/data_access.proto 定义安全运营场景下的数据访问控制标签DataAccessIngestionLabel摄取标签的 key/value 对DataAccessLabelslog_typesLogType 标签列表、namespaces、custom_labels基于 UDM 搜索语法的复杂标签、ingestion_kv_labelskey/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 使用的封装namespaceidbytes 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/timestampGo 产物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-namegoogle-backstory、transport 为grpcrest生成backstory-py发布包其余语言Javajava_gapic_assembly_gradle_pkg生成backstory-java、PHP、Ruby、C#package_name Backstory、C 均有对应 targetbackstory/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 与 Metadatacollection.proto 同时依赖 entity、id 与 udm并通过 Bazel 规则面向 7 种语言产出可用代码是理解 Google Security Operations 事件模型与检测数据结构的直接入口。【免费下载链接】googleapisPublic interface definitions of Google APIs.项目地址: https://gitcode.com/GitHub_Trending/go/googleapis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考