Skip to content

Latest commit

 

History

History
334 lines (260 loc) · 13.8 KB

README.zh-CN.md

File metadata and controls

334 lines (260 loc) · 13.8 KB

KELLECT:a Kernel-based Efficient and Lossless Event Log Collector

简体中文 | English

KELLECT简介

KELLECT（a Kernel-based efficient and Lossless event log collector）是一款用于内核级事件日志处理的系统框架 ，包括采集、清洗、融合、存储和分析阶段，KELLCT根据功能的不同，我们分为KellectAgent和KellectService。

KellectAgent-Windows简介

KellectAgent-Windows（以下简称kellectAgent）作为首发版本，是一款基于ETW(Event Tracing for Windows)的多线程Windows内核日志采集器，基于C++语言开发，性能高效，系统开销低。 KellectAgent-Windows可以跟踪Windows系统的内核级事件信息，如FileIO、Process、Thread、ImageLoad、Registry等。也可以跟踪用户侧的事件信息，如Microsoft_Windows_DNS_Client。

该程序集成了事件收集、事件分析、事件语义校正、事件输出等功能。输出格式遵循JSON规范，有以下4种输出方式：

  1. 输出至控制台显示；
  2. 输出至指定文件路径；
  3. 输出至指定Socket通信端；
  4. 输出至指定Kafka服务器。

用户可直接通过"PowerShell.exe"或"cmd.exe"使用该工具，并根据需要进行命令参数的设定。我们还提供了一些配置文件，用户可以根据需求进行定制。

有关KELLECT的进一步发展，请参阅未来规划。

实现细节

KellectAgent使用一些第三方依赖库，如下所示，请查阅LICENSE-3RD-PARTY获取更多信息。

Module Name Module Version LicenseUrl
easyloggingpp v9.96.7 https://github.com/amraynonweb/easyloggingpp
moodycamel::ConcurrentQueue / https://github.com/cameron314/concurrentqueue
nlohmann::json v3.10.4 https://github.com/nlohmann/json
TinyXML-2 v2 https://github.com/leethomason/tinyxml2
librdkafka v1.6 https://github.com/edenhill/librdkafka

KellectAgent的开发主要依赖于Clion开发工具，编译主要依赖于MSVC编译器。开发使用的软件和版本如下表所示：

工具名称 版本
Visual Studio 16.11.13
MSVC 19.29.30143.0
Windows SDK 10.0.20348.0
Clion 2022.1

KELLECT项目的结构如下表所示：

目录名称 说明
include 头文件
lib 第三方库
source 源文件
source/config 配置文件
release 发布版本

KELLECT使用说明

通过命令行调用

经过测试，KellectAgent可以在Windows7（客户端版本）、Windows Server2008（服务器版本）及以上版本运行。

注意: Windows11版本目前暂不支持，将在后续版本支持。

采集功能必须以管理员身份运行。如下所示，可通过配置参数的形式进行功能的选择。

<<<<<<< Updated upstream image-20230407102213003

image-20230407102213003

Stashed changes

例如，可以通过以下命令全量采集系统日志并输出至文件"test.json"：

kellect.exe -e all -f test.json

注意: 对于用户侧日志，目前只输出到控制台，所以使用用户侧事件时，不用在末尾添加别的字符，例如 kellect.exe -u 0x01 注意: 参数"-e" 请指定16进制格式参数值。

配置文件的用法

filter.txt

​ 用户可以通过配置filter.txt实现不同功能。通常KellectAgent运行不需要进行修改，除非有定制化的需求。

filteredProcessID
0 4 128

filteredEventIdentifier
3740466758 32
1030727888 1
1030727888 2
1030727889 1
1030727889 2
1030727889 36
749821213 10
749821213 2
...

filteredImageFile
C:\Windows\SysWOW64\ntdll.dll

配置文件不同标签详情：

  1. [filteredProcessID]

    表示根据此标签中的 ID 列表过滤具体事件。 进程 ID 由空格分隔。

  2. [filteredEventIdentifier]

    表示通过Event ProviderID和opcode的组合过滤事件，我们称之为EventIdentifier。 具体的事件日志详情可以在微软文档中获取. ProviderID 是 Guid 类第一部分的十进制形式，opcode 是每个 BaseEvent Class Page 的 Remarks 下的 EventType 值。

    注意：该标签下的事件标识符为白名单列表，是我们需要采集的事件类型。

    image-20220503171251436

    image-20220503171255065

  3. [filteredImageFile]

    可以通过此标签中列出的Image文件路径过滤 加载Image 的事件。

initImages.txt

该文件存储的为一些系统DLL文件，我们在KellectAgent运行时会对这些文件进行预读取，以加快后续事件解析效率。用户可以添加需要预加载的DLL文件路径到文件中。

C:\Windows\System32\win32u.dll
C:\Windows\SysWOW64\win32u.dll
C:\Windows\System32\msvcp_win.dll
C:\Windows\SysWOW64\msvcp_win.dll
C:\Windows\System32\KernelBase.dll
C:\Windows\SysWOW64\KernelBase.dll
C:\Windows\SysWOW64\FWPUCLNT.DLL
C:\Windows\System32\wininet.dll
C:\Windows\System32\StateRepository.Core.dll
C:\Windows\System32\rilproxy.dll
C:\Windows\System32\fwpolicyiomgr.dll
C:\Windows\System32\dbghelp.dll
...

注意：有些DLL文件无法解析。

log.conf

配置日志输出格式与路径信息。

uuid

设置当前主机的UUID。若未指定，则KellectAgent会自动生成UUID并输出到该文件中。

输出格式

我们以 JSON 格式输出事件记录。 每个 BaseEvent 都有两部分属性：公共属性和私有属性。 各部分说明如下：

  • 公共属性
属性 描述
Event 对应的事件名称
TID 产生事件的线程ID
PID 产生事件的进程ID
PName 产生事件的进程名称
PPID 产生事件父进程ID
PPName 产生事件的父进程名
TimeStamp 事件发生的时间
Host-UUID 产生事件的主机标识，
用于在多主机日志联合分析时区别具体日志来源
Args 具体事件类型的私有属性对

  • 私有属性

    此类型属性因事件类型而异。 例如：

  1. FileIOFileCreate事件

    属性 描述
    IrpPtr I/O请求包
    TTID 正在创建文件的线程标识符
    FileObject 可用于在文件创建和关闭事件之间将操作与同一打开的文件对象实例相关联的标识符
    CreateOptions 在 CreateOptions 和 CreateDispositions 参数中传递给 NtCreateFile 函数的值
    FileAttributes 在 FileAttributes 参数中传递给 NtCreateFile 函数的值
    ShareAccess 在 ShareAccess 参数中传递给 NtCreateFile 函数的值
    OpenPath 文件路径

  2. FileIOName 事件

    属性 描述
    FileObject 将此指针的值与 DiskIo_TypeGroup1 事件中的 FileObject 指针值匹配以确定 I/O 操作的类型
    FileName 文件的完整路径，不包括驱动器号

  3. CallStack 事件（目前对CallStack的解析不完全支持）

    属性 描述
    stackInfo 进程操作的调用栈. (每个调用的格式如下所示 : ModulePath:APIName, 如: C:\Windows\System32\ntdll.dll:LdrSystemDllInitBlock)

  4. ...... 其他事件属性描述可参考微软的文档。

需要注意的是，我们已经修改或填充了大部分事件的属性，所以Windows提供的原生事件和我们的会有一些差异。

#FileIO的create 事件
{
	"Event": "FileIOCreate",
	"PID": 956,
	"PName": "QQPCTray.exe",
	"PPID": 2832,
	"PPName": "QQPCRTP.exe",
	"TID": 9516,
	"TimeStamp": 133253085392394264,
	"Host-UUID": "FBFFA15C-FEDE-4f96-9AF8-398294758A2A",
	"Args": {
		"CreateOptions": 18890752,
		"FileAttributes": 0,
		"FileObject": 2590015792,
		"IrpPtr": 2812860872,
		"OpenPath": "C:\Program Files\WindowsApps\Microsoft.LanguageExperiencePackzh-CN_19041.57.180.0_neutral__8wekyb3d8bbwe\Windows\System32\DriverStore\zh-CN\uaspstor.inf_loc",
		"ShareAccess": 7,
		"TTID": 9516
	}
}

#callstack事件
{
	"Event": "CallStack",
	"PID": 21576,
	"PName": "GoogleUpdate.exe",
	"PPID": 1808,
	"PPName": "svchost.exe",
	"TID": 44940,
	"TimeStamp": 133253092340669753,
	"Host-UUID": "FBFFA15C-FEDE-4f96-9AF8-398294758A2A",
	"Args": {
		"stackInfo": "C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Windows\SysWOW64\sechost.dll:RegisterTraceGuidsA,
        C:\Windows\SysWOW64\sechost.dll:RegisterTraceGuidsA,
        C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Program Files (x86)\Google\Update\1.3.36.152\goopdate.dll:DllEntry,
        C:\Windows\System32\ntdll.dll:RtlCaptureStackContext,
        C:\Windows\System32\ntdll.dll:RtlpCleanupRegistryKeys,
        C:\Windows\System32\ntdll.dll:RtlValidProcessProtection,
        C:\Windows\System32\ntdll.dll:_CIcos,
        C:\Windows\System32\ntdll.dll:cos,
        C:\Windows\SysWOW64\ntdll.dll:NtQueryAttributesFile,
        C:\Windows\SysWOW64\ntdll.dll:RtlMultiByteToUnicodeN,
        C:\Windows\SysWOW64\ntdll.dll:RtlMultiByteToUnicodeN,
        ...
	}
}

WDM（windows common data model）输出格式

目前WDM格式转化只对，注册表（Registry），进程（Process），线程（Thread），文件（File），网络（Tcp）进行格式转化。 其中每个事件都会产出边，每个边的格式为：

{
     "data": {
          "Event": {
             "uuid": ,
             "Type": "", 
             "subject": "",
             "object": "",
             "object2": "",
             "CommandLine": "",
             "TimeStamp": 
         },
         "args": ,
         "weights": 1
     },
     "WDMVersion": "1.0",
     "source": ""
}

而对于每个点来说，不同事件的产出会有些不一样。

例如

#进程事件
{
         "data": {
             "Subject": {
                 "uuid": ,
                 "Type": 
                 "PID" ,
                 "PName": ,
                 "NodeType": ,
                 "ParentSubject": ,   
                 "TimeStamp": 
             },
             "args": ,
             "weights": 1
         },
         "WDMVersion": "1.0",
         "source": ""
     }

#文件事件
{
         "data": {
             "Object": {
                 "uuid": ,
                 "Type": ,
                 "Path": ,
                 "NodeType": ,
                 "TimeStamp": 
             },
             "args": ,
             "weights": 1
         },
         "WDMVersion": "1.0",
         "source": ""
     }

数据集

我们使用kellectAgent作为采集工具，并基于redcanaryco提出的脚本Automic Red Team进行数据采集。该脚本基于ATT&CK中的战术，我们采集到的数据共享在谷歌云盘中

未来计划

  1. 基于ETW的Windows内核日志采集工具（V1.0，已发布）
  2. 基于pBPF的Linux内核日志采集工具（V1.1，研发中）
  3. 提供Common Data Model数据统一接口