文档首页/ 态势感知 SA/ API参考/ API/ 事件管理/ 上报安全产品数据
更新时间:2024-04-23 GMT+08:00
分享

上报安全产品数据

功能介绍

批量数据上报,每批次最多不超过50条。

此接口为继承态势感知 SA的接口。

调试

您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。

URI

POST /v2/{project_id}/events/import

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

租户项目ID。

最小长度:32

最大长度:36

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。 通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。

最小长度:1

最大长度:2097152

X-Language

String

语言。

最小长度:2

最大长度:6

表3 请求Body参数

参数

是否必选

参数类型

描述

events

Array of Event objects

event 批量导入

表4 Event

参数

是否必选

参数类型

描述

version

String

SA数据对象版本号,数据接入时需携带版本号。版本号由SA服务团队负责更新,数据源只可填写SA给定的版本号。目前版本为1.0.0。

最小长度:5

最大长度:5

environment

Environment object

环境坐标,DRP。

data_source

DataSource object

提供数据来源相关信息,必选对象。

first_observed_time

String

首次发现时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。

last_observed_time

String

最新发现时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。

create_time

String

记录时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。

arrive_time

String

数据接收时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。 是指事件数据被SA侧接收的时间,由SA接收时填写,产品上报数据时不用填写。

event_id

String

事件唯一标识,UUID格式。

最小长度:32

最大长度:36

title

String

事件标题,最大255字符。

最小长度:1

最大长度:255

description

String

事件描述信息,最大1024个字符

最小长度:1

最大长度:1024

source_url

String

事件URL链接,指向数据源产品中有关当前事件说明的页面。

最小长度:1

最大长度:4096

count

Integer

事件发生次数,默认为1,必填。

最小值:1

最大值:9223372036854775807

confidence

Integer

事件的置信度。置信度的定义旨在说明识别的行为或问题的可能性。 取值范围:0-100,0表示置信度为0%,100表示置信度为100%。

最小值:0

最大值:100

severity

Severity object

严重性对象。

criticality

Integer

关键性,是指事件涉及的资源的重要性级别。 取值范围:0-100,0表示资源不关键,100表示最关键资源。

最小值:0

最大值:100

type

Type object

事件分类。

compliance

Compliance object

扩展信息,用来提供合规检查信息。合规检查相关的数据上报时,必须填充此对象。

network

Network object

扩展信息,用来提供网络信息。

vulnerability_patch

VulnerabilityPatch object

扩展信息,用来提供漏洞信息。

malware

Malware object

恶意软件。

threat_intel

ThreatIntel object

威胁情报。

resource

Resource object

受影响资源。

remediation

Remediation object

补救措施。

data_source_fields

Object

数据源自定义信息,最多支持50个key/value对,约束条件: 1、该对象不能包含冗余数据,并且不能与已定义的SSA事件格式字段冲突。 2、字段名称可以包含字母数字字符、空格和以下符号:_ . / = + \ - @。 示例: "data_source_fields": { "key1": "value1", "key2", "value2", }

verification_state

String

事件验证状态,标识事件的准确性。 Unknown – 未知,默认 True_positive – 确认 False_positive – 误报。

最小长度:1

最大长度:512

handle_status

String

事件处理状态,New/Ignored/Resolved;默认New。

最小长度:1

最大长度:512

phase

String

阶段:Prepartion|Detection and Analysis|Containm,Eradication& Recovery| Post-Incident-Activity。

最小长度:1

最大长度:32

sla

Integer

约束闭环时间:单位:天。

最小值:1

最大值:90

表5 Environment

参数

是否必选

参数类型

描述

type

String

环境供应商,HWCP/HWC/AWS/Azure/GCP等。

最小长度:1

最大长度:36

domain_id

String

租户账号ID,用来标识事件所属租户。

最小长度:32

最大长度:36

project_id

String

租户项目ID,用来标识事件所属项目区域。

最小长度:32

最大长度:36

region_id

String

数据源产品所在区域,具体取值范围查看华为云地区和终端节点定义。

最小长度:1

最大长度:512

表6 DataSource

参数

是否必选

参数类型

描述

type

Integer

数据源类型,取值范围如下: 1 - 华为产品 2 - 第三方产品 3 - 租户私有产品

最小值:1

最大值:3

domain_id

String

数据源产品所属管理账号的ID,最大36个字符。

最小长度:32

最大长度:36

project_id

String

数据源产品所属项目的ID,最大36个字符。

最小长度:32

最大长度:36

region_id

String

数据源产品所在区域,具体取值范围查看华为云地区和终端节点定义。

最小长度:1

最大长度:512

company_name

String

数据源产品所属公司的名称。

最小长度:1

最大长度:512

product_name

String

数据源产品的名称。

最小长度:1

最大长度:512

product_feature

String

产品功能特性名称,用来指明检测到当前事件的产品的功能特性。

最小长度:1

最大长度:512

表7 Severity

参数

是否必选

参数类型

描述

label

String

严重性等级取值范围:TIPS、LOW、MEDIUM、HIGH、FATAL。 TIPS:未发现任何问题。 LOW:无需针对问题执行任何操作。 MEDIUM:问题需要处理,但不紧急。 HIGH:问题必须优先处理。 FATAL:问题必须立即处理,以防止产生进一步的损害。

最小长度:1

最大长度:512

normalize_score

Integer

严重性评分取值范围:0-100; 与严重性等级的对应关系: TIPS 0; LOW 1-39; MEDIUM 40-69; HIGH 70-89; FATAL 90-100。

最小值:0

最大值:100

original_score

Integer

严重性原始评分,指在数据源产品中的评分。

最小值:0

最大值:9223372036854775807

表8 Type

参数

是否必选

参数类型

描述

business

String

事件所属业务领域标签,可选类别如下: attack – 攻击 vulnerability – 漏洞 compliance check – 合规检查 risk - 风险 public opinion - 舆情 illegal&violation - 违法违规 security bulletin - 公告

最小长度:1

最大长度:512

category

String

类别,推荐使用预定义的类型分类。

最小长度:1

最大长度:512

classifier

String

分类器,推荐使用预定义的分类器。 如果指定了分类器,则必须指定类别。

最小长度:1

最大长度:512

tech_domain

String

技术领域标签: OS:主机 APP:应用 NET:网络 OPS:运维 CS:云服务 CSP:平台云服务

最小长度:1

最大长度:512

properties

TypeProperties object

属性信息。

表9 TypeProperties

参数

是否必选

参数类型

描述

killchain

String

Kill chain事件分类,仅当business为attack有效

最小长度:1

最大长度:512

ttps

String

Mitre Array 事件分类,仅当business为attack有效

最小长度:1

最大长度:512

effects

String

影响,适用全部类型

最小长度:1

最大长度:512

表10 Compliance

参数

是否必选

参数类型

描述

checkitem_id

String

检查项(检查规则)编号

最小长度:1

最大长度:512

checkpoint_id

String

检查点(检查结果)编号,检查项对同一个资源的检查结果

最小长度:1

最大长度:512

spec_id

String

检查规范编号,默认选第一个

最小长度:1

最大长度:512

status

String

合规检查结果,取值定义:PASSED、WARNING、FAILED、NOT_AVAILABLE。 说明: PASSED - 接受评估的所有资源都已通过安全检查。 WARNING - 某些信息缺失或配置不支持此检查。 FAILED - 至少有一个接受评估的资源未能通过安全检查。 NOT_AVAILABLE - 由于服务中断或 API 错误,无法执行检查。

最小长度:1

最大长度:512

properties

String

属性信息

最小长度:1

最大长度:512

表11 Network

参数

是否必选

参数类型

描述

direction

String

方向,取值范围:IN、OUT。

最小长度:2

最大长度:3

protocol

String

协议。

最小长度:0

最大长度:512

src_ip

String

源IP地址。

最小长度:7

最大长度:15

src_port

Integer

源端口,0–65535。

最小值:0

最大值:65535

src_domain

String

源域名,最大128个字符。

最小长度:1

最大长度:128

src_geo

Geo object

源IP的地理位置信息。

dest_ip

String

目标IP地址。

最小长度:7

最大长度:15

dest_port

Integer

目标端口,0–65535。

最小值:0

最大值:65535

dest_domain

String

目标域名,最大128个字符。

最小长度:1

最大长度:128

dest_geo

Geo object

目标IP的地理位置信息。

表12 Geo

参数

是否必选

参数类型

描述

latitude

Number

纬度。

最小值:-90.0

最大值:90.0

longitude

Number

经度。

最小值:-180.0

最大值:180.0

city_code

String

城市编码。

最小长度:1

最大长度:128

country_code

String

国家简码ISO 3166-1 alpha-2,例如:CN、US、DE、IT、SG。

最小长度:1

最大长度:128

表13 VulnerabilityPatch

参数

是否必选

参数类型

描述

patch_id

String

补丁编号。

最小长度:1

最大长度:256

patch_name

String

补丁名称。

最小长度:1

最大长度:256

type

String

补丁类型(0:linux,1:windows,2:web-cms)。

最小长度:1

最大长度:32

major_level

String

重要等级。

最小长度:1

最大长度:32

status

String

补丁状态。

最小长度:1

最大长度:32

repair_cmd

String

修复命令。

最小长度:0

最大长度:512

repair_necessity

String

修复必要程度(1:需立刻修复,2:可延后修复,3:暂可以不修复)。

最小长度:0

最大长度:512

release_time

String

发布时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息 为事件发生时区,无法解析时区的时间,默认时区填东八区。

reference_url

String

参考链接。

最小长度:0

最大长度:512

vendor_name

String

漏洞报告提供者信息。

最小长度:1

最大长度:32

vulnerable_package

String

受影响软件版本。

最小长度:1

最大长度:32

cve_ids

String

CVE编号列表。

最小长度:1

最大长度:256

表14 Malware

参数

是否必选

参数类型

描述

name

String

恶意软件名称,最大64个字符。

最小长度:1

最大长度:64

sha256

String

恶意软件sha256

最小长度:1

最大长度:1024

type

String

恶意软件类型,遵循STIX规范: adware、backdoor、bot、bootkit、ddos、downloader、dropper、exploit-kit、keylogger、ransomware、remote-access-trojan、resource-exploitation、rogue-security-software、rootkit、screen-capture、spyware、trojan、unknown、virus、webshell、wiper、worm

最小长度:1

最大长度:512

path

String

恶意软件在系统中的路径,最大512个字符。

最小长度:0

最大长度:512

state

String

恶意软件状态,取值范围:OBSERVED、REMOVAL_FAILED、REMOVED。

最小长度:0

最大长度:512

properties

MalwareProperties object

属性信息。

表15 MalwareProperties

参数

是否必选

参数类型

描述

pid

String

进程ID。

最小长度:1

最大长度:64

user

String

系统角色(例如:root,service)。

最小长度:1

最大长度:64

mod

String

系统权限(例如:777,755)。

最小长度:1

最大长度:64

start_time

String

进程启动时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。

表16 ThreatIntel

参数

是否必选

参数类型

描述

id

String

情报Id。

最小长度:0

最大长度:32

indicator_type

String

威胁情报类型,Domain、Email_Address、Hash_MD5、Hash_SHA1、Hash_SHA256、 Hash_SHA512、IPv4_Address、IPv6_Address、URL。

最小长度:0

最大长度:64

labels

String

标签,如'矿池','外联'等,"Directory Scan|Directory Traversal"。

最小长度:0

最大长度:512

confidence

Integer

置信度,不同来源目前置信度分值定义不一样(分数)。

最小值:0

最大值:9223372036854775807

information_source

String

威胁情报源,最大64个字符。

最小长度:0

最大长度:64

severity

Integer

严重程度,不同渠道定义值不一样(分数)。

最小值:0

最大值:9223372036854775807

description

String

威胁情报描述。

最小长度:0

最大长度:4096

modified

String

威胁情报的更新时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。

valid_from

String

有效期开始(可读字符串)。

最小长度:0

最大长度:32

valid_until

String

有效期结束(可读字符串)。

最小长度:0

最大长度:32

properties

ThreatIntelProperties object

威胁情报属性信息。

表17 ThreatIntelProperties

参数

是否必选

参数类型

描述

file_md5

String

恶意软件Md5。

最小长度:1

最大长度:64

file_sha1

String

恶意软件Sha1。

最小长度:1

最大长度:255

file_sha256

String

恶意软件Sha256值。

最小长度:1

最大长度:255

file_name

String

文件名称。

最小长度:1

最大长度:255

create_time

String

编译时间,格式ISO8601:YYYY-MM-DDTHH:mm:ss.ms+timezone。时区信息为事件发生时区,无法解析时区的时间,默认时区填东八区。

file_class

String

文件类别,TEXT|XCODE。

最小长度:1

最大长度:255

file_family

String

家族,例如:wannacry(勒索软件)。

最小长度:1

最大长度:255

file_maltype

String

类别,例如:trojan(特洛伊)。

最小长度:1

最大长度:255

ip_resolves_to_refs

String

mac地址。

最小长度:1

最大长度:255

belongs_to_refs

String

IP AS 自治系统。

最小长度:1

最大长度:255

ip_location

String

地区 格式:country/provice/city/lngwgs/latwgs。

最小长度:1

最大长度:255

domain_family

String

例如:banjori|iodine。

最小长度:1

最大长度:255

domain_resolves_to_refs

String

解析的IP地址。

最小长度:1

最大长度:255

domain_dns_type

String

DNS类别。A|NS|CNAME|TXT。

最小长度:1

最大长度:255

url_host

String

例:3ms.huawei.com。

最小长度:1

最大长度:255

url_resolves_to_refs

String

IP地址。

最小长度:1

最大长度:255

display_name

String

显示名称。

最小长度:1

最大长度:128

url_belongs_to_ref

String

邮箱账户,@之前部分。

最小长度:1

最大长度:128

表18 Resource

参数

是否必选

参数类型

描述

id

String

资源ID。

最小长度:32

最大长度:36

name

String

资源名称;最大长度255个字符。

最小长度:1

最大长度:255

type

String

资源类型。

最小长度:1

最大长度:128

provider

String

云服务名称。

最小长度:1

最大长度:128

region_id

String

区域。

最小长度:1

最大长度:128

domain_id

String

资源所属租户账号ID。

最小长度:32

最大长度:36

project_id

String

资源所属项目ID。

最小长度:32

最大长度:36

ep_id

String

企业项目ID。

最小长度:32

最大长度:36

ep_name

String

企业项目名称。

最小长度:32

最大长度:36

tags

Object

资源标签 1、最多50个key/values对。 2、values:最大255字符。 3、取值范围:字母数字、空格、“+”、“-”、“=”、“.”、“_”、“:”、“/”、“@”。

表19 Remediation

参数

是否必选

参数类型

描述

recommendation

String

处理建议,最长512个字符。

最小长度:1

最大长度:512

url

String

链接,指向该事件的一般修复信息。该URL必须可以从公网访问,不需要提供凭证。

最小长度:1

最大长度:128

响应参数

状态码: 400

表20 响应Body参数

参数

参数类型

描述

error_msg

String

无效请求提示信息

最小长度:1

最大长度:128

error_code

String

错误码

最小长度:1

最大长度:128

状态码: 401

表21 响应Body参数

参数

参数类型

描述

error_msg

String

权限错误

最小长度:1

最大长度:128

error_code

String

错误码

最小长度:1

最大长度:128

状态码: 500

表22 响应Body参数

参数

参数类型

描述

error_msg

String

系统内部错误

最小长度:1

最大长度:128

error_code

String

错误码

最小长度:1

最大长度:128

请求示例

POST https://{endpoint}/v2/{project_id}/events/import

{
  "events" : [ {
    "version" : "1.1.0",
    "environment" : {
      "type" : "xxx",
      "domain_id" : "dfaf9864b95c448797b5dc0f0xxxxxxx",
      "project_id" : "2b31ed520xxxxxxebedb6e57xxxxxxxx",
      "region_id" : "xx-xx-1"
    },
    "data_source" : {
      "type" : 1,
      "domain_id" : "dfaf9864b95c448797b5dc0f0xxxxxxx",
      "project_id" : "2b31ed520xxxxxxebedb6e57xxxxxxxx",
      "region_id" : "xx-xx-1",
      "company_name" : "xxx",
      "product_name" : "xxx",
      "product_feature" : "xxx"
    },
    "first_observed_time" : "2020-10-10T13:10:40.436+0800",
    "last_observed_time" : "2020-10-10T13:10:40.436+0800",
    "create_time" : "2020-10-10T13:10:40.436+0800",
    "arrive_time" : "2020-10-21T01:20:31.343+0800",
    "event_id" : "1683fbf6-01fd-49f4-8222-0fe33d3f2d2e",
    "title" : "TCP Malformed",
    "description" : "TCP Malformed",
    "count" : 1,
    "severity" : {
      "original_score" : 1,
      "label" : "TIPS"
    },
    "type" : [ {
      "business" : "attack",
      "category" : "Brute Force",
      "classifier" : "ssh"
    } ],
    "network" : {
      "direction" : "IN",
      "dest_ip" : "xxx.xxx.xxx.xxx",
      "dest_port" : 80,
      "dest_geo" : {
        "latitude" : 1.352083,
        "longitude" : 103.81984
      }
    },
    "resource" : [ {
      "id" : "f1f4076a-9d12-497f-aac4-a9dcb5462fcc",
      "name" : "ecs-s3_large_2_win-20200828214727",
      "type" : "cloudservers",
      "provider" : "ecs",
      "region_id" : "xx-xx-1",
      "domain_id" : "dfaf9864b95c448797b5dc0f00709a55",
      "project_id" : "2b31ed520xxxxxxebedb6e57xxxxxxxx",
      "ep_id" : "7e998f85-xxxx-xxxx-xxxx-xxxxxxxx",
      "ep_name" : "test001"
    } ],
    "verification_state" : "Unknown",
    "handle_status" : "New"
  } ]
}

响应示例

状态码

状态码

描述

201

Succeeded

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

错误码

请参见错误码

相关文档