From 1cf7b7d4a52316ae917c3996317673fab6e44bbc Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Thu, 12 Jun 2025 15:15:19 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/2403_LTS_SP2/_toc.yaml | 14 +++ docs/en/2403_LTS_SP2/api_reference.md | 81 ++++++++++++++ docs/en/2403_LTS_SP2/install_secdetector.md | 103 ++++++++++++++++++ .../introduction_to_secdetector.md | 97 +++++++++++++++++ .../public_sys-resources/icon-note.gif | Bin 0 -> 394 bytes docs/en/2403_LTS_SP2/secdetector.md | 5 + docs/en/2403_LTS_SP2/using_secdetector.md | 46 ++++++++ docs/zh/2403_LTS_SP2/_toc.yaml | 5 +- docs/zh/2403_LTS_SP2/api_reference.md | 6 +- docs/zh/2403_LTS_SP2/install_secdetector.md | 6 +- 10 files changed, 355 insertions(+), 8 deletions(-) create mode 100644 docs/en/2403_LTS_SP2/api_reference.md create mode 100644 docs/en/2403_LTS_SP2/install_secdetector.md create mode 100644 docs/en/2403_LTS_SP2/introduction_to_secdetector.md create mode 100644 docs/en/2403_LTS_SP2/public_sys-resources/icon-note.gif create mode 100644 docs/en/2403_LTS_SP2/secdetector.md create mode 100644 docs/en/2403_LTS_SP2/using_secdetector.md diff --git a/docs/en/2403_LTS_SP2/_toc.yaml b/docs/en/2403_LTS_SP2/_toc.yaml index e69de29..bc851fe 100644 --- a/docs/en/2403_LTS_SP2/_toc.yaml +++ b/docs/en/2403_LTS_SP2/_toc.yaml @@ -0,0 +1,14 @@ +label: secDetector User Guide +isManual: true +description: secDetector is an OS-native intrusion detection system that protects critical infrastructure through robust detection and response. +sections: + - label: Overview + href: ./secdetector.md + - label: Introduction to secDetector + href: ./introduction_to_secdetector.md + - label: Installation and Deployment + href: ./install_secdetector.md + - label: API Reference + href: ./api_reference.md + - label: Using secDetector + href: ./using_secdetector.md diff --git a/docs/en/2403_LTS_SP2/api_reference.md b/docs/en/2403_LTS_SP2/api_reference.md new file mode 100644 index 0000000..8ad746b --- /dev/null +++ b/docs/en/2403_LTS_SP2/api_reference.md @@ -0,0 +1,81 @@ +# Interface Description + +secDetector provides an external SDK. This document outlines the interfaces required for users to develop applications. The SDK interface design is straightforward, comprising a total of three interfaces and two header files. + +Header files: + +- **secDetector/secDetector_sdk.h**: contains interface definitions + +- **secDetector/secDetector_topic.h**: includes predefined macros necessary for calling interfaces, such as the topic numbers for optional subscription features + +## secSub + +Topic subscription interface + +**Function**: + +This is the subscription interface. Applications can subscribe to different functional topics by providing different topic IDs, for instance, abnormal probe events related to file opening. The definitions of the topic IDs for the various functional topics offered by secDetector are available in secDetector_topic.h. This interface supports subscribing to multiple topics simultaneously. The topic IDs of multiple probes can be combined using a bitmap. + +> ![NOTE]NOTE +> Since each subscription creates a reader (an information reader), applications should subscribe to all necessary topics in a single call to the subscription interface. This allows for collecting information using a single reader. If you need to modify the subscribed content, you can unsubscribe and then resubscribe. + +**Function declaration:** + +```c +void *secSub(const int topic); +``` + +**Parameters:** + +- `topic`: Input parameter, the set of topics to subscribe to + +**Return Value:** + +- Null: Subscription failed +- Not null: The GRPC reader for reading information related to the subscribed topics + +## secUnsub + +Topic unsubscription interface + +**Function**: + +This is the unsubscription interface. Applications can unsubscribe from topics by providing the reader obtained after a successful subscription. After unsubscribing, the application will no longer receive information on the corresponding topics. If no application is subscribed to a particular topic in the system, that topic will not be processed. + +**Function Declaration:** + +```c +void secUnsub(void *reader); +``` + +**Parameters:** + +- `reader`: Input parameter, the information reader to unsubscribe + +**Return Value:** + +- None + +## secReadFrom + +Message reading interface for subscribed topics + +**Function**: + +After successfully subscribing to certain topics using the subscription interface, and before performing the unsubscription operation, this interface can be used to receive messages on the subscribed topics sent by secDetector. This interface is blocking. It is recommended that applications use a separate thread to call this function in a loop. This function will only resume execution when there is a message available for the subscribed topic. + +**Function Declaration:** + +```c +void secReadFrom(void *reader, char *data, int data_len); +``` + +**Parameters:** + +- `reader`: Input parameter, the message reader obtained after successful topic subscription +- `data`: Output parameter, the message buffer, a block of memory provided by the application +- `data_len`: Input parameter, the size of the message buffer + +**Return Value:** + +- None diff --git a/docs/en/2403_LTS_SP2/install_secdetector.md b/docs/en/2403_LTS_SP2/install_secdetector.md new file mode 100644 index 0000000..fd76e76 --- /dev/null +++ b/docs/en/2403_LTS_SP2/install_secdetector.md @@ -0,0 +1,103 @@ +# Installing secDetector + +## Hardware and Software Requirements + +### Hardware Requirements + +- Currently supports only x86_64 and aarch64 architecture processors. +- secDetector disk usage requirement: 1GB or more quota. +- secDetector memory usage requirement: 100MB or more quota. + +### Environment Preparation + +Install openEuler by referring to [Installation Guide](https://docs.openeuler.openatom.cn/en/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html). + +## Installing secDetector + +1. Configure the openEuler Yum repository: The Yum repository is configured by default in openEuler, so no additional operations are required. In special cases, refer to the official openEuler documentation to configure an online Yum repository or configure a local Yum repository by mounting the ISO. + +2. Install secDetector. + + ```shell + #Install secDetector + sudo yum install secDetector + ``` + +> ![NOTE]NOTE +> +> After installing secDetector, the relevant files required for deploying secDetector can be found in the specified directories: + +```shell +# Core framework of secDetector kernel driver +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko + +# Functional components of secDetector kernel driver +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko + +# Daemon process file of secDetector +/usr/bin/secDetectord + +# SDK library files of secDetector +/usr/lib64/secDetector/libsecDetectorsdk.so +/usr/include/secDetector/secDetector_sdk.h +/usr/include/secDetector/secDetector_topic.h +``` + +## Deploying secDetector + +The main component of secDetector, secDetectord, is deployed in the system as a system service. The foreground service system can communicate with it by integrating the SDK. Since some capabilities of secDetector must be built within the kernel, the full set of secDetectord functions also depends on the deployment of its backend driver. + +### Deploying the Kernel Driver + +1. Insert the basic framework of the kernel driver. **secDetector_core.ko** is the basic framework of the kernel driver and should be deployed before other kernel modules. Find the directory of the installed secDetector_core.ko and insert it into the kernel. Refer to the following command: + + ```shell + sudo insmod secDetector_core.ko + ``` + + `secDetector_core` supports one parameter, `ringbuf_size`. You can control the size of the cache space for the data channel between the kernel driver and the user-space secDetectord by specifying the value of this parameter. This parameter can be specified as an integer between 4 and 1024, in units of MB. The default value is 4 and must be a power of 2. Refer to the following command: + + ```shell + sudo insmod secDetector_core.ko ringbuf_size=128 + ``` + +2. Insert the functional modules of the kernel driver. The kernel driver of secDetector adopts a modular deployment method. You can choose to deploy functional modules that meet their needs based on the framework, or they can choose to deploy all modules. Refer to the following commands: + + ```shell + sudo insmod secDetector_kmodule_baseline.ko + + sudo insmod secDetector_memory_corruption.ko + + sudo insmod secDetector_program_action.ko + + sudo insmod secDetector_xxx.ko + ``` + + - **secDetector_kmodule_baseline.ko** provides the ability to detect kernel module lists and belongs to the memory modification probe category. + - **secDetector_memory_corruption.ko** provides the ability to detect memory corruption and belongs to the memory modification probe category. + - **secDetector_program_action.ko** provides the ability to detect program behavior and belongs to the program behavior probe category. + +### Deploying the User-Space Driver and observer_agent + +Currently, the user-space driver and the service observer_agent have been integrated into secDetectord. Refer to the following command: + +```shell +sudo ./secDetectord & +``` + +The usr-space driver includes the capabilities of file operation probes and process management probes. + +secDetectord supports the following configuration options: + +```text +Usage: secDetectord [options] +secDetectord runs in the background by default, obtaining data from probes and forwarding it to subscribers. +Options: + -d Enter debug mode, run in the foreground, and print probe data to the console. + -s Configure the eBPF buffer size in Mb, default is 4; the size range is 4~1024, and it must be a power of 2. Currently, there are 2 independent buffers. + -t Supports configuring subscribed events, default is all events. topic is in bitmap format. For example, -t 0x60 subscribes to both process creation and process exit events. For details, please refer to include/secDetector_topic.h. +``` + +### Deploying the SDK + +The SDK library files are deployed in the system library directory by default. Users only need to include the SDK header files in their programs to use it. diff --git a/docs/en/2403_LTS_SP2/introduction_to_secdetector.md b/docs/en/2403_LTS_SP2/introduction_to_secdetector.md new file mode 100644 index 0000000..74a42b4 --- /dev/null +++ b/docs/en/2403_LTS_SP2/introduction_to_secdetector.md @@ -0,0 +1,97 @@ +# Introduction to secDetector + +## Introduction + +secDetector is an OS-native intrusion detection system designed to protect critical information infrastructure with robust detection and response capabilities. It aims to reduce development costs for third-party security tools while enhancing their detection and response capabilities. secDetector models security event primitives based on the ATT&CK attack pattern library, offering richer primitives and providing real-time blocking and flexible response capabilities. + +As a flexible OS-native intrusion detection system, secDetector can be used in three modes: + +1. Enabled directly by system users for basic anomaly event alerting and handling. +2. Integrated by security posture awareness services to compensate for system information collection deficiencies, used for complex security threat analysis like APT and real-time blocking for key event control. +3. Secondarily developed by security professionals or security awareness service providers to build accurate, efficient, and timely intrusion detection and response capabilities based on an extensible framework. + +## Software Architecture + +```text +||==APP===================================================================|| +|| || +|| ---------------------------- || +|| | SDK | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | + | + | +||==OBSERVER========================|=====================================|| +|| | || +|| ---------------------------- || +|| | service | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | +||==DRIVER================================================================|| +|| || +|| ---------------------------- || +|| | 8 types of cases | || +|| ---------------------------- || +|| || +||------------------------------------------------------------------------|| +|| core || +|| ------------- ---------------- ---------------- ----------------- || +|| | hook unit | | collect unit | | analyze unit | | response unit | || +|| ------------- ---------------- ---------------- ----------------- || +|| || +||========================================================================|| +``` + +secDetector is architecturally divided into four parts: SDK, service, detection feature set cases, and detection framework core. + +- SDK + + The SDK is implemented as a user-space dynamic link library and is deployed in security awareness services that need to use secDetector. The SDK is used to communicate with the service of secDetector to perform required tasks (such as subscribing, unsubscribing, reading existing messages, etc.). The exception information provided by secDetector is defined as different cases, which security awareness services can subscribe to based on their needs. + +- Service + + The service is implemented as a user-space service application. It manages and maintains the case subscription information for security awareness services and maintains the running status of cases. Information collected by the framework core and the detection feature set cases is uniformly collected by the service and forwarded to different security awareness services as needed. The configuration and management requirements of security awareness services for the underlying detection feature set cases and the framework core are also uniformly managed and forwarded by the service. Different security awareness services may require the same case. The service will calculate the union of cases required by all security awareness services and register it with the lower layer. + +- Feature set cases + + The detection feature set cases are a series of exception detection probes. They take different forms depending on the exception information; for example, each probe for kernel exception information detection is implemented as a kernel module. A case represents a probe, and a probe often provides information about a type of exception or a type of exception event. For instance, a process probe focuses on event information such as process creation, termination, and attribute modification, while a memory modification probe collects information like kernel module lists and security switch statuses. Therefore, a probe may include monitoring multiple events, and the logic for monitoring these different events might not be deployable within the same execution flow. We use the concept of a workflow to represent the work of a probe within the same execution flow; a probe can contain one or more workflows. For example, for a process probe, process creation detection and process attribute modification detection are different workflows. + +- Framework core + + The detection framework core is the basic framework that every case relies on, providing management for cases and common basic functional units required by workflows. The kernel exception information detection framework is implemented as a kernel module. A detection feature case can register itself with the framework or unregister from the framework. The framework can also provide specific interaction interfaces to meet external dynamic requests. A workflow is defined as being composed of four types of functional units: event generator, information collector, event analyzer, and response unit. + +The feature set cases and the framework core together are referred to as the driver. The driver provides the lowest-level system-wide implementation of secDetector functions. + +Drivers are divided into two categories: kerneldriver and usrdriver. As the names suggest, the kerneldriver is deployed in kernel space and implemented as a kernel module. The usrdriver is deployed in user space and is directly deployed as a module within the service. Logically, the usrdriver is below the service, but in operation, to reduce communication costs, the usrdriver is directly integrated into the service program. + +## Capabilities and Features + +### Detection Capabilities + +| Feature | Status | Description | +| ---------------------------------- | ---------- | --------------------------------------------------------------------------- | +| Detection Framework | Implemented | A unified, flexible, extensible, and efficient detection framework supporting different types of trigger, collection, analysis, and response units. | +| Process Management Probes | Implemented | Monitors events such as process creation, termination, and metadata modification. | +| File Operation Probes | Implemented | Monitors events such as file creation, deletion, read/write, and attribute modification. | +| Program Behavior Probes (API Calls) | Implemented | Monitors key program behaviors such as anonymous pipe creation, command execution, and ptrace system calls. | +| Memory Modification Probes (Key Kernel Data) | Implemented | Monitors key kernel data such as kernel module lists and hardware security feature switches. | + +### Response Capabilities + +| Feature | Status | Description | +| -------------- | ---------- | ----------------------------------------------- | +| Response Framework | Implemented | A unified, flexible, and extensible response framework supporting different types of response units. | +| Alert Reporting | Implemented | A response unit providing the capability to report exception information. | + +### Service Capabilities + +| Feature | Status | Description | +| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| Communication Framework | Implemented | Applications communicate with the service using gRPC. Functionality is encapsulated in the SDK dynamic library. | +| Subscription Management | Implemented | Applications can subscribe once and use secDetector to obtain information long term. secDetector manages the subscribed applications and distributes information for the corresponding subscribed topics. | +| Configuration Delivery | Implemented | The service can configure specific detection and blocking features via parameters to achieve filtering, adjustment, and other functions. Currently not open to applications. | +| Real-time Detection | Implemented | The information provided by secDetector is real-time, accurate, and firsthand. | diff --git a/docs/en/2403_LTS_SP2/public_sys-resources/icon-note.gif b/docs/en/2403_LTS_SP2/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda GIT binary patch literal 394 zcmZ?wbhEHblx7fPSjxcg=ii?@_wH=jwxy=7CMGH-B`L+l$wfv=#>UF#$gv|VY%C^b zCQFtrnKN(Bo_%|sJbO}7RAORe!otL&qo<>yq_Sq+8Xqqo5h0P3w3Lvb5E(g{p01vl zxR@)KuDH0l^z`+-dH3eaw=XqSH7aTIx{kzVBN;X&hha0dQSgWuiw0NWUvMRmkD|> literal 0 HcmV?d00001 diff --git a/docs/en/2403_LTS_SP2/secdetector.md b/docs/en/2403_LTS_SP2/secdetector.md new file mode 100644 index 0000000..733fb53 --- /dev/null +++ b/docs/en/2403_LTS_SP2/secdetector.md @@ -0,0 +1,5 @@ +# secDetector User Guide + +This document introduces the architecture, features, installation, development, and application scenarios of secDetector, an OS-native intrusion detection system within openEuler. + +This document is intended for developers, open source enthusiasts, and partners who use the openEuler OS and want to learn and use secDetector. Users must have basic knowledge of Linux. diff --git a/docs/en/2403_LTS_SP2/using_secdetector.md b/docs/en/2403_LTS_SP2/using_secdetector.md new file mode 100644 index 0000000..4ac1dfb --- /dev/null +++ b/docs/en/2403_LTS_SP2/using_secdetector.md @@ -0,0 +1,46 @@ +# Using secDetector + +secDetector provides an SDK, a shared object library, which can be integrated into applications to allow simple utilization of secDetector through simple interfaces. This document describes how to use secDetector. + +## Basic Usage + +After secDetector is installed according to [Installing secDetector](./install_secdetector.md), **libsecDetectorsdk.so**, **secDetector_sdk.h**, and **secDetector_topic.h** will be deployed to the system user library default path. + +1. Ensure the include path is configured for applications developed in C or C++. Then, include these two header files in the program. + + ```c + #include + #include + ``` + +2. Refer to [API Reference](./api_reference.md) to call the interfaces provided by the SDK to access secDetector. + + 1. First, call the subscription interface `secSub` to subscribe to the required topics. + 2. Then, call the message reading interface `secReadFrom` in a separate thread to block and read the information generated by the subscribed topics. + 3. Finally, when secDetector is no longer needed, call the unsubscription interface `secUnsub`. When unsubscribing, strictly use the return value from the subscription. + +## Code Example + +Refer to the example code in the secDetector repository, which is written in Python. + +1. View the example code at the following link: + + [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) + +2. Alternatively, download the repository for reference: + +```shell +git clone https://gitee.com/openeuler/secDetector.git +``` + +## Specifications and Constraints + +1. Some functions (such as the memory modification probe - security switch) depend on the hardware architecture, so their behavior differs across different instruction set architectures. +2. The data buffer space for transferring data from the kernel to user space is shared among probes. If the buffer is full, newly collected event information will be discarded. The configurable range for the buffer space is 4-1024 MB and must be a power of 2. +3. The service process secDetectord supports running as the root user but does not support multiple instances; any program run after the first will exit. +4. The number of user subscription connections is limited to 5. +5. After a user subscribes, when reading messages, a buffer must be provided for the message reading interface. Messages exceeding the buffer length will be truncated. A buffer length of at least 4,096 is recommended. +6. Descriptive strings like filenames and node names have length limits, and excessively long ones may be truncated. +7. A single application process does not support parallel multi-connections to secDetectord for receiving messages. Only one subscription and one connection for receiving messages are allowed at a time. Resubscription is only possible after unsubscribing. +8. The secDetectord process should wait for all application connections to be disconnected, meaning all topics are fully unsubscribed, before shutting down and exiting. +9. Some functions (such as the memory modification probe - security switch) are based on the current CPU state. Therefore, the basic function can detect state changes on the current CPU. State changes on other CPUs will not be detected if they are not synchronized to the current CPU in a timely manner. diff --git a/docs/zh/2403_LTS_SP2/_toc.yaml b/docs/zh/2403_LTS_SP2/_toc.yaml index aabf341..f64888c 100644 --- a/docs/zh/2403_LTS_SP2/_toc.yaml +++ b/docs/zh/2403_LTS_SP2/_toc.yaml @@ -1,8 +1,9 @@ label: secDetector使用指南 isManual: true -href: ./secdetector.md -description: secDetector是OS内构入侵检测系统，为关键信息基础设施提供入侵检测及响应能力 +description: secDetector 是 OS 内构入侵检测系统，为关键信息基础设施提供入侵检测及响应能力 sections: + - label: 概述 + href: ./secdetector.md - label: 认识secDetector href: ./introduction_to_secdetector.md - label: 安装与部署 diff --git a/docs/zh/2403_LTS_SP2/api_reference.md b/docs/zh/2403_LTS_SP2/api_reference.md index 1235f7b..e0daa27 100644 --- a/docs/zh/2403_LTS_SP2/api_reference.md +++ b/docs/zh/2403_LTS_SP2/api_reference.md @@ -8,7 +8,6 @@ secDetector操作系统内构入侵检测系统对外提供SDK，这里给出用 - secDetector/secDetector_topic.h：包含一些调用接口所需使用的预定义宏，如可选择性订阅的功能主题编号 - ## secSub 订阅 topic 接口 @@ -17,8 +16,8 @@ secDetector操作系统内构入侵检测系统对外提供SDK，这里给出用 订阅接口，应用程序通过输入不同 topic id，可以选择订阅不同的功能主题，比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题，多个探针的 topic id 可以以位图的形式进行组合。 ->![](./public_sys-resources/icon-note.gif) **说明：** ->由于一次订阅产生一个reader即信息读取器，所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容，可以退订之后再重新订阅。 +> [!NOTE]说明 +> 由于一次订阅产生一个reader即信息读取器，所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容，可以退订之后再重新订阅。 **函数声明：** @@ -57,7 +56,6 @@ void secUnsub(void *reader); - 无 - ## secReadFrom 已订阅主题的消息读取接口 diff --git a/docs/zh/2403_LTS_SP2/install_secdetector.md b/docs/zh/2403_LTS_SP2/install_secdetector.md index 84c792c..7172014 100644 --- a/docs/zh/2403_LTS_SP2/install_secdetector.md +++ b/docs/zh/2403_LTS_SP2/install_secdetector.md @@ -8,9 +8,11 @@ * secDetector磁盘使用需求：配额1GB及以上。 * secDetector内存使用需求：配额100MB及以上。 +### 概述 + ### 环境准备 -安装 openEuler 系统，安装方法参考《[安装指南](https://docs.openeuler.org/zh/docs/24.03_LTS/docs/Installation/installation.html)》。 +安装 openEuler 系统，安装方法参考《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 ## 安装secDetector @@ -23,7 +25,7 @@ sudo yum install secDetector ``` -> ![](./public_sys-resources/icon-note.gif)说明： +> [!NOTE]说明 > > 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件： -- Gitee