kestrel踩坑记——和stix数据格式对接探索

先看官方例子：

匹配 TTP 模式

编写一个模式来匹配战术、技术和程序 (TTP)。TTP 模式描述了一种 Web 服务漏洞利用，其中 Web 服务的工作进程（例如nginx或NodeJS）与不是 Web 服务的二进制文件相关联。==>在RCE场景会遇到。就是在做通过nodejs的进程产生了一个可疑非法进程。

 

从上面的数据看，进程里面需要parent_ref, binary_ref两个字段。我们看看stix里面是否有？

 

参考stix标准数据格式：http://docs.oasis-open.org/cti/stix/v2.0/stix-v2.0-part4-cyber-observable-objects.html

2.13​ ​Process Object

Type Name: process

 

The Process Object represents common properties of an instance of a computer program as executed on an operating system. A Process Object MUST contain at least one property (other than type) from this object (or one of its extensions).

​2.13.1​ ​Properties

Common Properties
type, extensions
Process Object Specific Properties
is_hidden, pid, name, created, cwd, arguments, command_line, environment_variables, opened_connection_refs, creator_user_ref, binary_ref, parent_ref, child_refs
Property Name	Type	Description
type (required)	string	The value of this property MUST be process.
extensions (optional)	dictionary	The Process Object defines the following extensions. In addition to these, producers MAY create their own.   windows-process-ext, windows-service-ext   Dictionary keys MUST identify the extension type by name.   The corresponding dictionary values MUST contain the contents of the extension instance.
is_hidden (optional)	boolean	Specifies whether the process is hidden.
pid (optional)	integer	Specifies the Process ID, or PID, of the process.
name (optional)	string	Specifies the name of the process.
created (optional)	timestamp	Specifies the date/time at which the process was created.
cwd (optional)	string	Specifies the current working directory of the process.
arguments (optional)	list of type string	Specifies the list of arguments used in executing the process. Each argument MUST be captured separately as a string.
command_line (optional)	string	Specifies the full command line used in executing the process, including the process name (depending on the operating system).
environment_variables (optional)	dictionary	Specifies the list of environment variables associated with the process as a dictionary. Each key in the dictionary MUST be a case preserved version of the name of the environment variable, and each corresponding value MUST be the environment variable value as a string.
opened_connection_refs (optional)	list of type object-ref	Specifies the list of network connections opened by the process, as a reference to one or more Network Traffic Objects.   The objects referenced in this list MUST be of type network-traffic.
creator_user_ref (optional)	object-ref	Specifies the user that created the process, as a reference to a User Account Object.   The object referenced in this property MUST be of type user-account.
binary_ref (optional)	object-ref	Specifies the executable binary that was executed as the process, as a reference to a File Object.   The object referenced in this property MUST be of type file.
parent_ref (optional)	object-ref	Specifies the other process that spawned (i.e. is the parent of) this one, as reference to a Process Object.   The object referenced in this property MUST be of type process.
child_refs (optional)	list of type object-ref	Specifies the other processes that were spawned by (i.e. children of) this process, as a reference to one or more other Process Objects.   The objects referenced in this list MUST be of type process.

 

google翻译：

 属性

共同属性
类型，扩展名
进程对象特定属性
is_hidden, pid, name, created, cwd, arguments, command_line, environment_variables, opens_connection_refs, creator_user_ref, binary_ref, parent_ref, child_refs
名称	类型	描述
类型 （必填）	细绳	这个属性的值必须是process。
扩展 （可选）	字典	Process Object 定义了以下扩展。除此之外，生产者可以创建自己的。   windows-process-ext , windows-service-ext   字典键必须按名称标识扩展类型。   相应的字典值必须包含扩展实例的内容。
is_hidden （可选）	布尔值	指定进程是否隐藏。
pid （可选）	整数	指定进程的进程 ID 或 PID。
名称 （可选）	细绳	指定进程的名称。
已创建 （可选）	时间戳	指定创建进程的日期/时间。
cwd （可选）	细绳	指定进程的当前工作目录。
参数 （可选）	字符串类型列表	指定在执行过程中使用的参数列表。每个参数必须作为字符串单独捕获。
命令行 （可选）	细绳	指定用于执行进程的完整命令行，包括进程名称（取决于操作系统）。
环境变量 （可选）	字典	将与进程关联的环境变量列表指定为字典。字典中的每个键必须是环境变量名称的大小写保留版本，每个对应的值必须是作为字符串的环境变量值。
opens_connection_refs （可选）	对象引用类型列表	指定进程打开的网络连接列表，作为对一个或多个网络流量对象的引用。   此列表中引用的对象必须是network-traffic类型 。
creator_user_ref （可选）	对象引用	指定创建进程的用户，作为对用户帐户对象的引用。   此属性中引用的对象必须是user-account类型。
binary_ref （可选）	对象引用	指定作为进程执行的可执行二进制文件，作为对文件对象的引用。   此属性中引用的对象必须是文件类型。
parent_ref （可选）	对象引用	指定产生这个进程的另一个进程（即它的父进程），作为对进程对象的引用。   此属性中引用的对象必须是process类型。
child_refs （可选）	对象引用类型列表	指定由该进程（即其子进程）产生的其他进程，作为对一个或多个其他进程对象的引用。   此列表中引用的对象必须是process类型 。

 

​Examples

Basic Process

{

  "0": {

    "type": "file",

    "hashes": {

      "SHA-256": "35a01331e9ad96f751278b891b6ea09699806faedfa237d40513d92ad1b7100f"

    },

  },

  "1": {

    "type": "process",

    "pid": 1221,

    "name": "gedit-bin",

    "created": "2016-01-20T14:11:25.55Z",

    "arguments" :[

      "--new-window"

    ],

    "binary_ref": "0"

  }

}

在之前kestrel对接elasticsearch踩坑记里面提到，ES里数据格式是这样的，

{

    "process": {

        "name": "firefox.exe",

        "content": "I hava a friend who loves smile, gymbo is his name",

        "pid": "121321"},

    "@timestamp": "2021-11-02T14:44:23.453+0000"

}

对应的kestrel是：

browsers = GET process FROM stixshifter://host110 WHERE [process:name IN ('firefox.exe', 'chrome.exe')] START t'2021-01-01T00:00:00Z' STOP t'2021-12-31T00:00:00Z'

DISP browsers ATTR name, pid

 

那么匹配 TTP 模式的kestrel case要能正常运行的话，需要数据格式应该是：

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

{     "process": {         "name": "xxx_shell",         "content": "what ever...",         "pid": "9121321",         "parent_ref": {             "name": "node",             "pid": "88888"         },         "binary_ref": {             "name": "xxx_shell.exe",             "SHA-256": "35a01331xxxx"         }                  },     "@timestamp": "2021-11-02T14:44:23.453+0000" }

我们试试效果。。。实验发现不行！！！必须叫parent 而不是 parent_ref

 

追了下源码 并且实际实验了下 stix_shifter底层确实是转换了下 将parentf_ref.name 查询修改为 parent.name

 

数据格式必须是 parent: {xxx} 而不能是 parent_ref: {xxx}

 

 

在winlog和ES对接kestrel的例子中，可以工作的数据格式是酱紫：

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165

{   "_index" : "winlogbeat-2022.01.04",   "_type" : "_doc",   "_id" : "ATzUJH4BoCGQFoHeNtwz",   "_score" : 1.0,   "_ignored" : [     "message.keyword"   ],   "_source" : {     "event" : {       "code" : "1",       "action" : "Process Create (rule: ProcessCreate)",       "type" : [         "start",         "process_start"       ],       "category" : [         "process"       ],       "kind" : "event",       "module" : "sysmon",       "provider" : "Microsoft-Windows-Sysmon",       "created" : "2022-01-04T11:23:12.982Z"     },     "rule" : {       "name" : "technique_id=T1047,technique_name=Windows Management Instrumentation"     },     "message" : "Process Create:\nRuleName: technique_id=T1047,technique_name=Windows Management Instrumentation\nUtcTime: 2022-01-04 11:23:11.028\nProcessGuid: {e872c6f0-2e1f-61d4-0932-000000001600}\nProcessId: 9656\nImage: C:\\Windows\\System32\\wbem\\WmiPrvSE.exe\nFileVersion: 10.0.19041.546 (WinBuild.160101.0800)\nDescription: WMI Provider Host\nProduct: Microsoft® Windows® Operating System\nCompany: Microsoft Corporation\nOriginalFileName: Wmiprvse.exe\nCommandLine: C:\\Windows\\system32\\wbem\\wmiprvse.exe -secured -Embedding\nCurrentDirectory: C:\\Windows\\system32\\\nUser: NT AUTHORITY\\NETWORK SERVICE\nLogonGuid: {e872c6f0-bced-61c6-e403-000000000000}\nLogonId: 0x3E4\nTerminalSessionId: 0\nIntegrityLevel: System\nHashes: SHA1=3EA7CC066317AC45F963C2227C4C7C50AA16EB7C,MD5=60FF40CFD7FB8FE41EE4FE9AE5FE1C51,SHA256=2198A7B58BCCB758036B969DDAE6CC2ECE07565E2659A7C541A313A0492231A3,IMPHASH=B71CB3AC5C352BEC857C940CBC95F0F3\nParentProcessGuid: {e872c6f0-bced-61c6-0f00-000000001600}\nParentProcessId: 764\nParentImage: C:\\Windows\\System32\\svchost.exe\nParentCommandLine: C:\\Windows\\system32\\svchost.exe -k DcomLaunch -p",     "related" : {       "user" : "NETWORK SERVICE",       "hash" : [         "3ea7cc066317ac45f963c2227c4c7c50aa16eb7c",         "60ff40cfd7fb8fe41ee4fe9ae5fe1c51",         "2198a7b58bccb758036b969ddae6cc2ece07565e2659a7c541a313a0492231a3",         "b71cb3ac5c352bec857c940cbc95f0f3"       ]     },     "@version" : "1",     "user" : {       "domain" : "NT AUTHORITY",       "id" : "S-1-5-18",       "name" : "NETWORK SERVICE"     },     "log" : {       "level" : "信息"     },     "host" : {       "mac" : [         "08:00:27:4d:a3:94"       ],       "id" : "e872c6f0-6576-4e6e-bc11-a931e4237e24",       "name" : "DESKTOP-6EH10UO",       "architecture" : "x86_64",       "ip" : [         "fe80::f44d:78ea:8886:8277",         "10.0.2.15"       ],       "hostname" : "DESKTOP-6EH10UO",       "os" : {         "family" : "windows",         "platform" : "windows",         "name" : "Windows 10 Pro",         "build" : "19043.928",         "type" : "windows",         "version" : "10.0",         "kernel" : "10.0.19041.928 (WinBuild.160101.0800)"       }     },     "winlog" : {       "event_data" : {         "Description" : "WMI Provider Host",         "FileVersion" : "10.0.19041.546 (WinBuild.160101.0800)",         "Product" : "Microsoft® Windows® Operating System",         "LogonId" : "0x3e4",         "LogonGuid" : "{e872c6f0-bced-61c6-e403-000000000000}",         "Company" : "Microsoft Corporation",         "IntegrityLevel" : "System",         "TerminalSessionId" : "0"       },       "record_id" : 70687,       "api" : "wineventlog",       "version" : 5,       "user" : {         "type" : "Well Known Group",         "identifier" : "S-1-5-18",         "domain" : "NT AUTHORITY",         "name" : "SYSTEM"       },       "event_id" : "1",       "opcode" : "信息",       "channel" : "Microsoft-Windows-Sysmon/Operational",       "provider_guid" : "{5770385f-c22a-43e0-bf4c-06f5698ffbd9}",       "process" : {         "thread" : {           "id" : 4168         },         "pid" : 8180       },       "provider_name" : "Microsoft-Windows-Sysmon",       "computer_name" : "DESKTOP-6EH10UO",       "task" : "Process Create (rule: ProcessCreate)"     },     "hash" : {       "sha1" : "3ea7cc066317ac45f963c2227c4c7c50aa16eb7c",       "md5" : "60ff40cfd7fb8fe41ee4fe9ae5fe1c51",       "imphash" : "b71cb3ac5c352bec857c940cbc95f0f3",       "sha256" : "2198a7b58bccb758036b969ddae6cc2ece07565e2659a7c541a313a0492231a3"     },     "ecs" : {       "version" : "1.12.0"     },     "agent" : {       "id" : "2f9cffc4-20fe-4e08-a04b-f7868bf483bb",       "name" : "DESKTOP-6EH10UO",       "version" : "7.16.2",       "type" : "winlogbeat",       "hostname" : "DESKTOP-6EH10UO",       "ephemeral_id" : "c1104c08-9ec4-4d7b-9c88-edc09ec6bd5c"     },     "type" : "wineventlog",     "process" : {       "args" : [         "C:\\Windows\\system32\\wbem\\wmiprvse.exe",         "-secured",         "-Embedding"       ],       "entity_id" : "{e872c6f0-2e1f-61d4-0932-000000001600}",       "name" : "WmiPrvSE.exe",       "command_line" : "C:\\Windows\\system32\\wbem\\wmiprvse.exe -secured -Embedding",       "working_directory" : "C:\\Windows\\system32\\",       "pe" : {         "product" : "Microsoft® Windows® Operating System",         "imphash" : "b71cb3ac5c352bec857c940cbc95f0f3",         "description" : "WMI Provider Host",         "company" : "Microsoft Corporation",         "file_version" : "10.0.19041.546 (WinBuild.160101.0800)",         "original_file_name" : "Wmiprvse.exe"       },       "executable" : "C:\\Windows\\System32\\wbem\\WmiPrvSE.exe",       "parent" : {         "args" : [           "C:\\Windows\\system32\\svchost.exe",           "-k",           "DcomLaunch",           "-p"         ],         "entity_id" : "{e872c6f0-bced-61c6-0f00-000000001600}",         "name" : "svchost.exe",         "command_line" : "C:\\Windows\\system32\\svchost.exe -k DcomLaunch -p",         "executable" : "C:\\Windows\\System32\\svchost.exe",         "pid" : 764       },       "hash" : {         "md5" : "60ff40cfd7fb8fe41ee4fe9ae5fe1c51",         "sha1" : "3ea7cc066317ac45f963c2227c4c7c50aa16eb7c",         "sha256" : "2198a7b58bccb758036b969ddae6cc2ece07565e2659a7c541a313a0492231a3"       },       "pid" : 9656     },     "@timestamp" : "2022-01-04T11:23:11.028Z",     "tags" : [       "beats_input_codec_plain_applied"     ]   } }

　

然后看了stix-shifter这个模块的文档，才恍然大悟：

https://developer.ibm.com/tutorials/exchange-cyber-threat-intelligence-with-stix-shifter/

为数据源开发 STIX-shifter 适配器：

1. IBM/stix-shifter从https://github.com/openencybersecurityalliance/stix-shifter分叉存储库，以处理您自己的库副本。
2. 创建翻译模块。
3. 创建一个传输模块。
4. 创建拉取请求以合并stix-shifter存储库中的更改。

创建翻译模块

1. 创建翻译模块文件夹
2. 重命名 dummy_translator.py 文件
3. 编辑 from_stix_map.json 文件
4. 编辑 query_constructor.py 文件
5. 编辑 to_stix_map.json 文件
6. 如果您的数据源需要，请更新 transformers.py 文件
7. 更新 MANIFEST.in 文件以包含 json 映射文件夹的路径
8. 验证翻译模块是否创建成功

步骤 1. 创建翻译模块文件夹

1. 去stix_shifter/stix_translation/src/modules/。

2. 复制dummy翻译模块文件夹。它是帮助您快速入门的模板。它包含翻译模块所需的必要文件。您需要根据您的数据源对其进行自定义。

   

3. 重命名dummy翻译模块文件夹以匹配数据源的名称。例如，abc。

   当调用翻译或传输时，数据源名称用作参数。此参数在整个项目中使用，以便 STIX-shifter 知道要使用哪些模块。

   注意：翻译模块和传输模块必须同名。

4. 验证您的翻译模块文件夹是否包含以下文件夹和文件。

文件夹/文件	它为什么如此重要？它在哪里使用？
json/from_stix_map.json	此映射文件用于将 STIX 模式转换为数据源查询结果。
json/to_stix_map.json	此映射文件用于将数据源查询结果转换为 STIX 对象。
初始化.py	Python 需要此文件才能正确处理库目录。
数据映射.py	此文件使用 from_stix_map.json 文件中定义的映射将 STIX 对象及其属性映射到数据源中的字段名称。
dummy_translator.py	此文件包含 Translator 类。它继承了 BaseTranslator 抽象基类，并且是其余翻译逻辑的接口。
query_constructor.py	该文件包含 QueryStringPatternTranslator 类，它将 STIX 模式的 ANTLR 解析转换为本地数据源查询。
stix_to_query.py	此文件包含继承 BaseQueryTranslator 类的 StixToQuery 类。 StixToQuery 调用 ANTLR 解析器，它返回 STIX 模式的解析。然后将解析传递到 query_constructor.py 并在其中将其转换为本地数据源查询。
变压器.py	此文件用于根据 STIX 和本机数据源查询语言的要求转换数据格式。
清单文件	Python 在打包库时使用此文件。

回到顶部

步骤 2. 重命名虚拟转换器文件

• 在您的abc翻译模块文件夹中，将dummy_translator.py文件重命名为 [module_name]_translator.py。

• [module_name] 必须与您在步骤 1 中分配给模块文件夹的名称匹配。例如，abc_translator.py.

  当 STIX-shifter 用于转换到 STIX 或从 STIX 转换时，数据源名称作为参数传入。此参数用于确定要使用的模块和文件。如果翻译器的名称与模块的名称不匹配，则在使用新的翻译模块时会出错。

  

回到顶部

步骤 3. 编辑 from_stix_map JSON 文件

该from_stix_map.json文件是您定义如何将 STIX 模式转换为数据源查询结果的地方。STIX 模式是表示 Cyber​​ Observable 对象的表达式。STIX 对象及其属性到数据源字段的映射决定了如何将 STIX 模式转换为数据源查询。只有具有映射的 STIX 对象和属性才能在 STIX 模式中使用。

如果 STIX 模式包含未映射的属性，则 STIX-shifter 在调用转换时会产生错误。发生错误是因为 QueryStringPatternTranslator 类（在 query_constructor.py 中）不知道 STIX 对象属性必须转换为哪个数据源字段。

1. 识别您的数据源字段。
2. 请参阅以下文档STIX 版本 2.0。第 4 部分：您可以映射数据源字段的 STIX 对象列表的Cyber​​ Observable Objects。
3. 在您的abc翻译模块文件夹中，转到您的 json/ 子文件夹并编辑from_stix_map.json文件。该from_stix_map.json文件包含 STIX 对象和属性到数据源字段的示例映射，格式如下：

    {
        "stix-object": {
            "fields": {
                "stix_object_property": ["DataSourceField", "DataSourceField"],
                "stix_object_property": ["DataSourceField"]
            }
        }
    }
   

   显示更多

4. 将您的数据源字段映射到 STIX 对象和属性。根据指定的格式定义映射。您可以将多个数据源字段映射到同一个 STIX 对象属性。

   • “stix-object”指的是 STIX 网络可观察对象类型名称
   • “stix_object_property”指的是 STIX 网络可观察对象属性名称

示例映射

以下示例说明了 STIX 对象（network-traffic、ipv4-addr 和 url）到具有以下字段的数据源的映射：SourcePort、DestinationPort、StartTime、EndTime、NetworkProtocol、SourceIpV4、DestinationIpV4 和 URL。

{
    "network-traffic": {
        "fields": {
          "src_port": ["SourcePort"], ==》表示stix的src_port就是对应XXX（如ES等）数据源的SourcePort字段！！！
          "dst_port": ["DestinationPort"],
          "start": ["StartTime"],
          "end": ["EndTime"],
          "protocols[*]": ["NetworkProtocol"]
        }
      },
      "ipv4-addr": {
        "fields": {
          "value": ["SourceIpV4", "DestinationIpV4"]
        }
      },
      "url": {
          "fields": {
              "value": ["Url"]
          }
      }
}

显示更多

示例映射支持以下 STIX 模式，因为 STIX 对象（network-traffic 和 ipv4-addr）及其属性在文件中定义并映射到数据源字段。

"[network-traffic:src_port = 12345 AND ipv4-addr:value = '00-00-5E-00-53-00']"

显示更多

回到顶部

步骤 4. 编辑查询构造函数文件

当 STIX 模式被 STIX-shifter 翻译时，它首先用 ANTLR 4 解析成嵌套表达式对象。本机数据源查询由这些嵌套对象构成。

以下 STIX 模式：

"[network-traffic:src_port = 37020 AND network-traffic:dst_port = 635] START '2016-06-01T00:00:00Z' STOP '2016-06-01T01:11:11Z'"

显示更多

转化为以下 ANTLR 解析：

Pattern[
    ObservationExpression(
        CombinedComparisonExpression(
            ComparisonExpression(
                network-traffic:dst_port ComparisonComparators.Equal 635
            )
            ComparisonExpressionOperators.And
            ComparisonExpression(
                network-traffic:src_port ComparisonComparators.Equal 37020
            )
        )
    )
    Qualifier(
        STARTt'2016-06-01T00:00:00Z'STOPt'2016-06-01T01:11:11Z'
    )
]

显示更多

解析通过 QueryStringPatternTranslator._parse_expression 递归运行，该表达式位于query_constructor.py.

该query_constructor.py文件是根据 ANTLR 解析构建本机查询的位置。

在您的abc翻译模块文件夹中，编辑该query_constructor.py文件。根据数据源的要求更新以下部分。

1.定义comparator_lookup映射

compare_lookup 将 STIX 模式运算符映射到数据源查询运算符。更改比较器值以匹配数据源中支持的运算符。

翻译模块中定义的默认运算符是 SQL 查询中使用的运算符。

STIX 模式运算符	数据源查询运算符
比较表达式运算符。与	和
比较表达式运算符。或	或者
比较表达式运算符.GreaterThan	>
比较表达式运算符.GreaterThanOrEqual	>=
比较表达式运算符.LessThan	<
比较比较器.LessThanOrEqual	<=
比较比较器.相等	=
比较比较器.NotEqual	!=
比较比较器.Like	喜欢
比较比较器.In	在
比较比较器.匹配	喜欢

2.定义_parse_expression方法

ANTLR 解析通过 _parse_expression 方法递归运行。表达式的类型在每次迭代中确定。当表达式是一个比较表达式时，一个查询字符串被添加到最终的数据源查询中。

此图像说明了为数据源查询构造查询字符串的位置。

以下来自 ANTLR 解析的比较表达式：

ComparisonExpression(
   network-traffic:src_port ComparisonComparators.Equal 37020
)

显示更多

将以下字符串添加到本机查询： "SourcePort = 37020"

3. 定义在 translate_pattern 方法中返回的最终查询

根据您的数据源，将此部分编辑为：

• 添加查询字段选择器。
• 附加结果限制和时间窗口。
• 返回查询数组或单个查询字符串。默认情况下返回单个查询字符串，但如果需要，可以将查询拆分为查询字符串数组。

回到顶部

步骤 5. 编辑 to_stix_map JSON 文件

该to_stix_map.json文件是您定义如何将数据源查询结果转换为 STIX 对象包的地方。查询结果必须为JSON格式；否则，无法支持数据源。

来自未映射数据源字段的结果在翻译过程中会被忽略，并且不包含在包中。

1. 识别您的数据源字段。
2. 请参阅以下文档STIX 版本 2.0。第 4 部分：您可以映射数据源字段的 STIX 对象列表的Cyber​​ Observable Objects。

3. 在您的abc翻译模块文件夹中，转到您的 json/ 子文件夹并编辑to_stix_map.json文件。该to_stix_map.json文件包含数据源字段到 STIX 对象和属性的示例映射，格式如下：

    {
        "DataSourceField": {
            "key": "stix-object.stix_object_property"
        },
        "DataSourceField": {
            "key": "x_custom_object.property",
            "cybox": false
        }
    }
   

   显示更多

4. 映射中的每个 JSON 对象都有一个“key”元素，其值表示 STIX 对象及其属性。根据指定的格式定义映射。

   • stix-object 引用 STIX 网络可观察对象类型名称
   • stix_object_property 指 STIX 网络可观察对象属性名称
   • x_custom_object.property 指一个自定义对象及其属性，您可以将其用于不映射到任何 STIX 对象的字段
   • 自定义属性的映射必须将cybox键设置为 false。此设置在翻译过程中识别自定义对象。

示例映射 使用与步骤 3 中相同的数据源，以下示例显示了到 STIX 的映射：

{
    "Url": {
        "key": "url.value"
    },
    "SourcePort": {
        "key": "network-traffic.src_port",
        "object": "nt",
        "transformer": "ToInteger"
    },
    "DestinationPort": {
        "key": "network-traffic.dst_port",
        "object": "nt",
        "transformer": "ToInteger"
    },
    "SourceIpV4": [
        {
          "key": "ipv4-addr.value",
          "object": "src_ip"
        },
        {
          "key": "network-traffic.src_ref",
          "object": "nt",
          "references": "src_ip"
        }
      ],
    "DestinationIpV4": [
        {
            "key": "ipv4-addr.value",
            "object": "dst_ip"
        },
        {
            "key": "network-traffic.dst_ref",
            "object": "nt",
            "references": "dst_ip"
        }
    ],
    "NetworkProtocol": {
        "key": "network-traffic.protocols",
        "object": "nt",
        "transformer": "ToLowercaseArray"
    },
    "LogSourceId": {
        "key": "x_my_data_source.log_source",
        "cybox": false
    }
}

显示更多

关于示例映射

• Url 是一个简单的映射。
• 源端口和目标端口
  • 具有匹配的“对象”值，这会导致将 src_port 和 dst_port 添加到同一对象（在本例中为网络流量）。
  • 使用 ToInteger 转换器。转换器是可选的映射属性，在将数据写入 STIX 对象之前将转换方法应用于数据。现有的变换方法在stix_shifter/stix_translation/src/transformers.py. 任何新的转换器都必须添加到此文件中。
• SourceIpV4 和 DestinationIpV4 包含两个对象。
  • 第一个对象为每个值创建一个 ipv4-addr 对象。给定该字段，“object”属性设置为 src_ip 或 dst_ip。
  • 映射中的第二个对象将网络流量对象中的引用添加到 ipv4-addr 对象。由于映射的第二部分将对象设置为“nt”，因此将引用添加到包含源端口和目标端口的同一网络流量对象。
• 网络协议
  • 映射到源端口和目标端口。
  • 注意 ToLowercaseArray 转换器的使用。示例数据源在 NetworkProtocol 字段中返回单个字符串。然而，在 STIX 中，网络流量协议以小写格式存储协议数组。
• 日志源 ID
  • 自定义 STIX 属性的示例。
  • 自定义属性允许将不适合任何现有 STIX 对象类型的数据添加到观察数据对象。自定义属性必须以 x_ 开头。在此示例中，数据源名称用作自定义对象名称，log_source 是自定义属性。

示例观察数据 STIX 对象

这是输入数据

网址	源端口	目的端口	来源IpV4	目的地IpV4	网络协议	日志源 ID
www.example.com	3000	1000	192.0.2.0	198.51.100.0	TCP	678

这是输出

下面说明了从前面的示例映射和示例输入数据派生的观察数据 STIX 对象。

{
      "id": "observed-data--6ecb744f-37d2-4950-a7bb-9dc821679c52",
      "type": "observed-data",
      "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
      "objects": {
        "0": {
          "type": "ipv4-addr",
          "value": "192.0.2.0"
        },
        "1": {
          "type": "network-traffic",
          "src_ref": "0",
          "src_port": 3000,
          "dst_ref": "2",
          "dst_port": 1000
        },
        "2": {
          "type": "ipv4-addr",
          "value": "198.51.100.0"
        },
        "3": {
          "type": "url",
          "value": "www.example.com"
        }
      },
      "x_my_data_source": {
        "log_source": 678
      }
    }

显示更多

将数据源结果转换为 STIX 的代码位于stix_shifter/stix_translation/src/json_to_stix/json_to_stix_translator.py. 通常，无需编辑此文件。

回到顶部

步骤 6. 如果您的数据源需要，请更新转换器文件

该transformers.py文件包含转换数据格式的类。每个类都有一个接收数据并将其转换为首选格式的方法。例如，将整数值转换为字符串。您可以在以下情况下使用这些类：

• 从 STIX 转换时，数据源查询语言需要特定的数据格式。例如，时间戳。在这种情况下，如果 STIX 和查询语言数据格式不同，则必须在模式转换期间转换 STIX 模式中值的格式。
• 转换为 STIX 时，STIX 对象需要特定的数据格式。在这种情况下，数据源结果中返回的值的格式必须在转换为 STIX 对象包的过程中进行转换。请参阅STIX 版本 2.0。第 4 部分： STIX 数据格式的网络可观察对象。

回到顶部

步骤 7. 更新 MANIFEST 文件以包含 json 映射文件夹的路径

MANIFEST.inPython 需要该文件，以便在打包 STIX-shifter 时可以找到新的映​​射文件。

回到顶部

步骤 8. 验证翻译模块是否已成功创建

您必须能够通过 UI 或 CLI 访问数据源，以便您可以运行翻译后的查询并确认它是否有效。可以通过main.py file从命令行调用并传入所需的参数来测试翻译模块。参数的顺序如下：

python main.py translate <data source (module) name> <"query" or "result"> <STIX identity object> <pattern or JSON results to
be translated> <options>

显示更多

测试 STIX 模式到数据源查询的转换

1. 从命令行运行翻译模块。例如，使用 abc 作为数据源：

    python main.py translate abc query '{}' "[network-traffic:src_port = 37020 and network-traffic:dst_port = 635] OR [ipv4-  addr:value = '333.333.333.0'] AND [url:value = 'www.example.com'] START t'2019-01-28T12:24:01.009Z' STOP t'2019-01-28T12:54:01.009Z'"
   

   显示更多

2. 通过针对数据源运行返回的查询，直观地验证返回的查询。

测试 JSON 数据源结果到 STIX 转换

1. 从命令行运行翻译模块。例如，使用 abc 作为数据源：

    python main.py translate abc results '{"type": "identity","id": "identity--f431f809-377b-45e0-aa1c-
   6a4751cae5ff","name": "abc","identity_class": "events"}' '[{"Url": "www.example.com", "SourcePort": 3000, "DestinationPort": 1000, "SourceIpV4": "192.0.2.0", "DestinationIpV4": "198.51.100.0", "NetworkProtocol": "TCP"}]'
   

   显示更多

2. 直观地验证所有预期数据是否在返回的 STIX 包中。如果样本结果中的数据源字段映射到 中to_stix_map.json，则该值必须位于映射 STIX 属性下的 STIX 包中。

笔记：

• 的<STIX identity object>表示一个数据源，并且是得到的结果的翻译过程中加入到STIX束中的第一观测数据对象。
• 每个被添加到包中的观察数据对象都引用<STIX identity object>以指示结果来自哪个数据源。
• 的<STIX identity object>翻译数据源结果STIX时才使用。因此，在将 STIX 模式转换为数据源查询时，可以传入一个空的 JSON 对象。
• 有关身份对象的更多信息，请参阅STIX 2 文档。

回到顶部

创建传输模块

1. 创建传输模块文件夹
2. 编辑 apiclient.py 文件
3. 编辑 dummy_connector.py 文件
4. 验证传输模块创建成功

Step 1. 创建传输模块文件夹

1. 去stix_shifter/stix_transmission/src/modules/。

2. 根据数据源 API复制适用于您的数据源的async_dummyorsynchronous_dummy文件夹。

   这些虚拟文件夹是帮助您快速入门的模板。它们包含传输模块所需的必要文件。您需要根据您的数据源对其进行自定义。

3. 重命名您的async_dummy或synchronous_dummy传输模块文件夹以匹配您的数据源的名称。它必须与您为翻译模块分配的名称相同。例如，ABC。

   当调用翻译或传输时，数据源名称用作参数。此参数在整个项目中使用，以便 STIX-shifter 知道要使用哪些模块。

   注意：翻译模块和传输模块必须同名。

4. 验证您的传输模块文件夹是否包含以下文件夹和文件。

   对于异步传输模块，您必须具有以下文件：

   | 文件夹/文件 | 它为什么如此重要？它在哪里使用？| ————————- |—————————– | init .py |Python 需要此文件来正确处理库目录。| apiclient.py | | async_dummy_connector.py |

   对于同步传输模块，您必须具有以下文件：

   | 文件夹/文件 | 它为什么如此重要？它在哪里使用？| —————————— |—————————– | init .py |Python 需要此文件来正确处理库目录。| synchronous_dummy_connector.py |

回到顶部

步骤 2. 编辑 apiclient 文件

您可以为异步或同步数据源实现 API 客户端。如果您的数据源有更简单的 API 调用方式，则不需要 API 客户端，可以跳过此步骤。

编辑apiclient.py文件的 APIClient 类以包含调用数据源 API 的方法。每个方法都调用相关的 API。

• 至少，必须实施以下方法：
  • ping 数据源
  • 创建搜索；向数据源发送查询
  • 检查搜索状态（仅用于异步数据源）
  • 检索搜索结果（仅用于异步数据源）
• 如果您的数据源支持，您可以为以下和其他添加方法：
  • 更新搜索
  • 删除搜索

回到顶部

步骤 3. 编辑虚拟连接器文件

1. 在您的 abc 传输模块文件夹中，将async_dummy_connector.py文件或synchronous_dummy_connector.py文件重命名为<module_name>_connector.py。

   该dummy_connector.py文件包含连接器类，该类在调用传输模块时被实例化。Connector 类包含通过 API 客户端调用数据源 API 的所有方法。

   这 <module_name>必须与您在步骤 1 中分配给模块文件夹的名称相匹配。例如，abc_connector.py。

   当 STIX-shifter 使用传输模块连接数据源时，数据源名称作为参数传入。此参数用于确定要使用的模块和文件。如果参数名称与模块名称不匹配，则使用新的传输模块时会出错。

2. 编辑abc_connector.py文件的 Connector(BaseConnector) 类以包含运行每个 API 客户端方法的方法。

   • 根据需要更改每个方法的实现。保持方法名称和签名不变。
   • 您可以在同一个文件中添加方法或为每个方法创建单独的文件。

   • 至少，必须实施以下方法：

     • 平
     • create_query_connection（仅用于异步数据源）
     • create_status_connection（仅用于异步数据源）

     • create_results_connection

       注意：数据源结果在转换为 STIX 之前需要为 JSON 格式。如果结果未以 JSON 形式返回，则 create_results_connection 是可能发生任何所需 JSON 转换的地方。

   • 如果您的数据源支持，您可以添加其他方法。例如，delete_query_connection。

同步数据源注意事项

对于同步数据源，查询从 create_results_connection 方法发送到 API。发送查询，并在同一步骤中接收结果。虽然 create_query_connection 和 create_status_connection 在技术上没有用到，但在传输执行过程中仍然会被调用，必须按如下方式实现：

创建查询连接

def create_query_connection(self, query):
      return { "success": True, "search_id": query }

显示更多

创建状态连接

def create_status_connection(self, search_id):
      return {"success": True, "status": "COMPLETED", "progress": 100}

显示更多

回到顶部

Step 4. 验证传输模块是否创建成功

1. 你必须有：

   • 用于连接到数据源的身份验证凭据。

   • 证书的私钥和证书。

     身份验证取决于数据源，可以是：

     '{"auth": {"username": "<username>","password": "<password>"}}' or
     '{"auth": {"SEC":"<SEC TOKEN>"}}'
     

     显示更多

2. 测试传输ping方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth": <authentication object>}' ping
      

      显示更多

   2. 目视确认结果返回

       {'success': True}
      

      显示更多

3. 测试传输 is_async 方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth{"auth": <authentication object>}' is_async
      

      显示更多

   2. 如果数据源是异步的，则直观地确认它返回 true。否则，它必须返回 false。

4. 测试传输查询方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth": <authentication object>}' query "<Native data source Query String>"
      

      显示更多

   2. 目视确认结果返回

       {'success': True, 'search_id': '<some query UUID>'}
      

      显示更多

   3. 记下返回的 UUID。它是在其余测试中使用的 ID。

5. 测试传输状态方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth{"auth": <authentication object>}' status "<Query UUID from test 4>"
      

      显示更多

   2. 目视确认结果返回

       {'success': True, 'status': 'COMPLETED', 'progress': 100}
      

      显示更多

6. 测试传输结果方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth{"auth": <authentication object>}' results "<Query UUID from test 4>" <Offset Integer> <Length Integer>
      

      显示更多

   2. 您可以将偏移量和长度命令行参数设置为 1。

   3. 直观地确认查询结果作为 JSON 对象返回。这些结果可以与通过 UI 或 CLI 直接在数据源 API 上运行测试 C 中使用的查询字符串时返回的结果进行比较。

7. 如果数据源支持，则测试传输删除方法。

   1. 使用以下 CLI 命令：

       python main.py transmit abc '{"host":"<IP address or URL to data source>", "port":"<port number>", "cert":
       "-----BEGIN PRIVATE KEY-----<private key>-----END PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----<certificate>-----END CERTIFICATE-----\n"}' '{"auth": <authentication object>}' delete "<Query UUID from test 4>"
      

      显示更多

   2. 目视确认结果返回

       {'success': True}
      

      显示更多

      概括

      在本教程中，您了解了如何为 STIX-Shifter 项目实现一个新的适配器，该适配器可以支持特定的安全产品。希望通过这些步骤使最终用户能够完成这些步骤，让您了解如何执行此操作。我们希望您能为STIX-Shifter 项目做出贡献，并成为我们安全社区的一员。