From c1a92f48c3b1ea49e85f92f2f27ea3a95d1044ed Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Fri, 15 Aug 2025 17:06:34 +0800 Subject: [PATCH 1/3] docs: move documentation to SIG repo for master/2509 --- .../public_sys-resources/icon-note.gif | Bin 394 -> 0 bytes docs/en/2509/_toc.yaml | 14 +++ docs/en/2509/api_reference.md | 81 ++++++++++++++ docs/en/2509/install_secdetector.md | 103 +++++++++++++++++ docs/en/2509/introduction_to_secdetector.md | 97 ++++++++++++++++ docs/en/2509/secdetector.md | 5 + docs/en/2509/using_secdetector.md | 46 ++++++++ docs/en/master/_toc.yaml | 14 +++ docs/en/master/api_reference.md | 81 ++++++++++++++ docs/en/master/install_secdetector.md | 103 +++++++++++++++++ docs/en/master/introduction_to_secdetector.md | 97 ++++++++++++++++ docs/en/master/secdetector.md | 5 + docs/en/master/using_secdetector.md | 46 ++++++++ docs/zh/2403_LTS_SP2/api_reference.md | 9 +- .../public_sys-resources/icon-note.gif | Bin 394 -> 0 bytes docs/zh/2403_LTS_SP2/using_secdetector.md | 6 +- docs/zh/2509/_toc.yaml | 14 +++ docs/zh/2509/api_reference.md | 80 +++++++++++++ docs/zh/2509/install_secdetector.md | 105 ++++++++++++++++++ docs/zh/2509/introduction_to_secdetector.md | 97 ++++++++++++++++ docs/zh/2509/secdetector.md | 5 + docs/zh/2509/using_secdetector.md | 46 ++++++++ docs/zh/master/_toc.yaml | 14 +++ docs/zh/master/api_reference.md | 80 +++++++++++++ docs/zh/master/install_secdetector.md | 105 ++++++++++++++++++ docs/zh/master/introduction_to_secdetector.md | 97 ++++++++++++++++ docs/zh/master/secdetector.md | 5 + docs/zh/master/using_secdetector.md | 46 ++++++++ 28 files changed, 1393 insertions(+), 8 deletions(-) delete mode 100644 docs/en/2403_LTS_SP2/public_sys-resources/icon-note.gif create mode 100644 docs/en/2509/_toc.yaml create mode 100644 docs/en/2509/api_reference.md create mode 100644 docs/en/2509/install_secdetector.md create mode 100644 docs/en/2509/introduction_to_secdetector.md create mode 100644 docs/en/2509/secdetector.md create mode 100644 docs/en/2509/using_secdetector.md create mode 100644 docs/en/master/_toc.yaml create mode 100644 docs/en/master/api_reference.md create mode 100644 docs/en/master/install_secdetector.md create mode 100644 docs/en/master/introduction_to_secdetector.md create mode 100644 docs/en/master/secdetector.md create mode 100644 docs/en/master/using_secdetector.md delete mode 100644 docs/zh/2403_LTS_SP2/public_sys-resources/icon-note.gif create mode 100644 docs/zh/2509/_toc.yaml create mode 100644 docs/zh/2509/api_reference.md create mode 100644 docs/zh/2509/install_secdetector.md create mode 100644 docs/zh/2509/introduction_to_secdetector.md create mode 100644 docs/zh/2509/secdetector.md create mode 100644 docs/zh/2509/using_secdetector.md create mode 100644 docs/zh/master/_toc.yaml create mode 100644 docs/zh/master/api_reference.md create mode 100644 docs/zh/master/install_secdetector.md create mode 100644 docs/zh/master/introduction_to_secdetector.md create mode 100644 docs/zh/master/secdetector.md create mode 100644 docs/zh/master/using_secdetector.md 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 deleted file mode 100644 index 6314297e45c1de184204098efd4814d6dc8b1cda..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 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|> diff --git a/docs/en/2509/_toc.yaml b/docs/en/2509/_toc.yaml new file mode 100644 index 0000000..bc851fe --- /dev/null +++ b/docs/en/2509/_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/2509/api_reference.md b/docs/en/2509/api_reference.md new file mode 100644 index 0000000..8ad746b --- /dev/null +++ b/docs/en/2509/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/2509/install_secdetector.md b/docs/en/2509/install_secdetector.md new file mode 100644 index 0000000..fd76e76 --- /dev/null +++ b/docs/en/2509/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/2509/introduction_to_secdetector.md b/docs/en/2509/introduction_to_secdetector.md new file mode 100644 index 0000000..74a42b4 --- /dev/null +++ b/docs/en/2509/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/2509/secdetector.md b/docs/en/2509/secdetector.md new file mode 100644 index 0000000..733fb53 --- /dev/null +++ b/docs/en/2509/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/2509/using_secdetector.md b/docs/en/2509/using_secdetector.md new file mode 100644 index 0000000..4ac1dfb --- /dev/null +++ b/docs/en/2509/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/en/master/_toc.yaml b/docs/en/master/_toc.yaml new file mode 100644 index 0000000..bc851fe --- /dev/null +++ b/docs/en/master/_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/master/api_reference.md b/docs/en/master/api_reference.md new file mode 100644 index 0000000..8ad746b --- /dev/null +++ b/docs/en/master/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/master/install_secdetector.md b/docs/en/master/install_secdetector.md new file mode 100644 index 0000000..fd76e76 --- /dev/null +++ b/docs/en/master/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/master/introduction_to_secdetector.md b/docs/en/master/introduction_to_secdetector.md new file mode 100644 index 0000000..74a42b4 --- /dev/null +++ b/docs/en/master/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/master/secdetector.md b/docs/en/master/secdetector.md new file mode 100644 index 0000000..733fb53 --- /dev/null +++ b/docs/en/master/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/master/using_secdetector.md b/docs/en/master/using_secdetector.md new file mode 100644 index 0000000..4ac1dfb --- /dev/null +++ b/docs/en/master/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/api_reference.md b/docs/zh/2403_LTS_SP2/api_reference.md index e0daa27..d8d44a9 100644 --- a/docs/zh/2403_LTS_SP2/api_reference.md +++ b/docs/zh/2403_LTS_SP2/api_reference.md @@ -5,18 +5,17 @@ secDetector操作系统内构入侵检测系统对外提供SDK,这里给出用 头文件: - secDetector/secDetector_sdk.h:包含接口定义 - - secDetector/secDetector_topic.h:包含一些调用接口所需使用的预定义宏,如可选择性订阅的功能主题编号 ## secSub -订阅 topic 接口 +订阅 topic 接口。 **功能**: 订阅接口,应用程序通过输入不同 topic id,可以选择订阅不同的功能主题,比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题,多个探针的 topic id 可以以位图的形式进行组合。 -> [!NOTE]说明 +> [!NOTE]说明 > 由于一次订阅产生一个reader即信息读取器,所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容,可以退订之后再重新订阅。 **函数声明:** @@ -36,7 +35,7 @@ void *secSub(const int topic); ## secUnsub -退订 topic 接口 +退订 topic 接口。 **功能**: @@ -58,7 +57,7 @@ void secUnsub(void *reader); ## secReadFrom -已订阅主题的消息读取接口 +已订阅主题的消息读取接口。 **功能**: diff --git a/docs/zh/2403_LTS_SP2/public_sys-resources/icon-note.gif b/docs/zh/2403_LTS_SP2/public_sys-resources/icon-note.gif deleted file mode 100644 index 6314297e45c1de184204098efd4814d6dc8b1cda..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 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|> diff --git a/docs/zh/2403_LTS_SP2/using_secdetector.md b/docs/zh/2403_LTS_SP2/using_secdetector.md index 20bb411..57d08be 100644 --- a/docs/zh/2403_LTS_SP2/using_secdetector.md +++ b/docs/zh/2403_LTS_SP2/using_secdetector.md @@ -29,9 +29,9 @@ secDetector 提供了SDK,一个so库,用户可以在自己的应用程序中 2. 也可以下载后参考 -```shell -git clone https://gitee.com/openeuler/secDetector.git -``` + ```shell + git clone https://gitee.com/openeuler/secDetector.git + ``` ## 规格与约束 diff --git a/docs/zh/2509/_toc.yaml b/docs/zh/2509/_toc.yaml new file mode 100644 index 0000000..f64888c --- /dev/null +++ b/docs/zh/2509/_toc.yaml @@ -0,0 +1,14 @@ +label: secDetector使用指南 +isManual: true +description: secDetector 是 OS 内构入侵检测系统,为关键信息基础设施提供入侵检测及响应能力 +sections: + - label: 概述 + href: ./secdetector.md + - label: 认识secDetector + href: ./introduction_to_secdetector.md + - label: 安装与部署 + href: ./install_secdetector.md + - label: 接口参考 + href: ./api_reference.md + - label: 使用secDetector + href: ./using_secdetector.md diff --git a/docs/zh/2509/api_reference.md b/docs/zh/2509/api_reference.md new file mode 100644 index 0000000..d8d44a9 --- /dev/null +++ b/docs/zh/2509/api_reference.md @@ -0,0 +1,80 @@ +# 接口说明 + +secDetector操作系统内构入侵检测系统对外提供SDK,这里给出用户开发应用程序所需的接口。SDK的接口设计非常简单,一共只有三个接口,两个头文件。 + +头文件: + +- secDetector/secDetector_sdk.h:包含接口定义 +- secDetector/secDetector_topic.h:包含一些调用接口所需使用的预定义宏,如可选择性订阅的功能主题编号 + +## secSub + +订阅 topic 接口。 + +**功能**: + +订阅接口,应用程序通过输入不同 topic id,可以选择订阅不同的功能主题,比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题,多个探针的 topic id 可以以位图的形式进行组合。 + +> [!NOTE]说明 +> 由于一次订阅产生一个reader即信息读取器,所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容,可以退订之后再重新订阅。 + +**函数声明:** + +```c +void *secSub(const int topic); +``` + +**参数:** + +- topic:入参,需要订阅的主题集合 + +**返回值:** + +- NULL:订阅失败 +- NOT NULL:读取订阅主题相关信息的GRPC reader读取器 + +## secUnsub + +退订 topic 接口。 + +**功能**: + +退订接口,应用程序通过输入订阅成功后获得的reader,完成主题的退订。退订后应用程序便不会收到相应主题的信息。系统中某主题如果没有任何应用程序订阅,则不会被执行。 + +**函数声明:** + +```c +void secUnsub(void *reader); +``` + +**参数:** + +- reader:入参,需要退订的信息读取器 + +**返回值:** + +- 无 + +## secReadFrom + +已订阅主题的消息读取接口。 + +**功能**: + +使用订阅接口对某些主题的订阅成功后,执行退订操作之前,可使用本接口接受 secDetector 发送的已订阅主题的消息。本接口是阻塞式的。应用程序建议使用独立的线程循环调用。当已订阅主题有消息时候,本函数才会被恢复执行。 + +**函数声明:** + +```c +void secReadFrom(void *reader, char *data, int data_len); +``` + +**参数:** + +- reader:入参,主题订阅成功后得到的消息读取器 +- data:出参,消息缓冲区,由应用程序提供的一段内存 +- data_len:入参,消息缓冲区的尺寸 + +**返回值:** + +- 无 diff --git a/docs/zh/2509/install_secdetector.md b/docs/zh/2509/install_secdetector.md new file mode 100644 index 0000000..7172014 --- /dev/null +++ b/docs/zh/2509/install_secdetector.md @@ -0,0 +1,105 @@ +# 安装 secDetector + +## 软硬件要求 + +### 硬件要求 + +* 当前仅支持 x86_64、aarch64 架构处理器。 +* secDetector磁盘使用需求:配额1GB及以上。 +* secDetector内存使用需求:配额100MB及以上。 + +### 概述 + +### 环境准备 + +安装 openEuler 系统,安装方法参考《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 + +## 安装secDetector + +1. 配置openEuler yum源:openEuler 发布版本上已默认配置完成yum源,无需额外操作。特殊情况下请参考openEuler官方文档配置在线yum源或通过ISO挂载配置本地yum源。 + +2. 安装secDetector。 + + ```shell + #安装secDetector + sudo yum install secDetector + ``` + +> [!NOTE]说明 +> +> 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件: + +```shell +#secDetector的kerneldriver的核心框架 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko + +#secDetector的kerneldriver的功能组件 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko + +#secDetector的守护者进程文件 +/usr/bin/secDetectord + +#secDetector的SDK库文件 +/usr/lib64/secDetector/libsecDetectorsdk.so +/usr/include/secDetector/secDetector_sdk.h +/usr/include/secDetector/secDetector_topic.h +``` + +## 部署 secDetector + +secDetector的主体secDetectord是以系统服务的形式部署在系统中的,前台业务系统可以通过集成SDK来与之通信。由于secDetector的部分能力必须构建在内核之中,因此secDetectord的功能全集还依赖于其后台驱动的部署。 + +### 部署 kernel driver + +1. 插入 kernel driver 的基础框架:secDetector_core.ko 是 kernel driver 的基础框架,要优先于其他内核模块进行部署。找到安装后的 secDetector_core.ko 目录,将其插入内核。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko + ``` + + secDetector_core 支持一个命令行参数ringbuf_size。用户可以通过指定该参数的值来控制 kernel driver 与 用户态secDetectord之间数据通道的缓存空间尺寸。该参数可以被指定为4~1024中的一个整数,单位是MB。默认值是4,必须为2的幂。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko ringbuf_size=128 + ``` + +2. 插入 kernel driver 的功能模块:secDetector的 kernel driver 采用模块化部署方式。用户可以选择基于框架部署满足需要的功能模块,也可以选择部署全部模块。参考命令如下: + + ```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 提供了内核模块列表检测的能力,属于内存修改类探针; + - secDetector_memory_corruption.ko 提供了内存修改检测的能力,属于内存修改类探针; + - secDetector_program_action.ko 提供了程序行为检测的能力,属于程序行为类探针。 + +### 部署 usr driver 和 observer_agent + +当前用户态驱动 usr driver 和服务 observer_agent 已经都被集成到secDetectord中,参考命令如下: + +```shell +sudo ./secDetectord & +``` + +usr driver当前包含了文件操作类探针和进程管理类探针的能力。 + +secDetectord支持如下一些配置选项: + +```text +用法:secDetectord [选项] +secDetectord 默认会在后台运行,从探针中取得数据并转发给订阅者。 +选项: + -d 进入调试模式,进入前台运行,并且在控制台打印探针数据。 + -s 配置eBPF缓冲区大小,单位为Mb,默认为4; size可选范围为4~1024,且必须为2的幂次方。当前拥有2个独立的缓冲区。 + -t 支持配置订阅的事件,默认为所有事件。topic 是位图格式。例如 -t 0x60 同时订阅进程创建和进程退出事件。详细请查阅 include/secDetector_topic.h。 +``` + +### 部署SDK + +SDK的库文件默认已经被部署到系统库目录中,用户需要在自己的程序中引用SDK的头文件即可使用。 diff --git a/docs/zh/2509/introduction_to_secdetector.md b/docs/zh/2509/introduction_to_secdetector.md new file mode 100644 index 0000000..7f98262 --- /dev/null +++ b/docs/zh/2509/introduction_to_secdetector.md @@ -0,0 +1,97 @@ +# 认识secDetector + +## 简介 + +secDetector 是专为OS设计的内构入侵检测系统,旨在为关键信息基础设施提供入侵检测及响应能力,为第三方安全工具减少开发成本同时增强检测和响应能力。secDetector 基于ATT&CK攻击模式库建模提供更为丰富的安全事件原语,并且可以提供实时阻断和灵活调整的响应能力。 + +secDetector 作为一套灵活的OS内构入侵检测系统,有三种使用模式: + +1. 直接被系统用户开启用作一些基础异常事件的告警和处置。 +2. 被安全态势感知服务集成,补齐系统信息采集缺陷,用于APT等复杂的安全威胁分析和重点事件布控实时阻断。 +3. 由安全从业人员或安全感知服务提供商二次开发,基于可拓展框架构建精确、高效、及时的入侵检测与响应能力。 + +## 软件架构 + +```text +||==APP===================================================================|| +|| || +|| ---------------------------- || +|| | SDK | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | + | + | +||==OBSERVER========================|=====================================|| +|| | || +|| ---------------------------- || +|| | service | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | +||==DRIVER================================================================|| +|| || +|| ---------------------------- || +|| | 8 types of cases | || +|| ---------------------------- || +|| || +||------------------------------------------------------------------------|| +|| core || +|| ------------- ---------------- ---------------- ----------------- || +|| | hook unit | | collect unit | | analyze unit | | response unit | || +|| ------------- ---------------- ---------------- ----------------- || +|| || +||========================================================================|| +``` + +secDetector在架构上分为四个部分:SDK、service、检测特性集合cases、检测框架core。 + +- SDK + + SDK是以一个用户态动态链接库lib的形态承载,被部署到需要使用secDetector入侵检测系统的安全感知业务中。SDK用于和secDetector入侵检测系统的service通讯,完成所需的工作(例如订阅,去订阅,读取现有消息等功能)。secDetector提供的异常信息被定义成不同的case,安全感知业务可以根据自身需求订阅。 + +- service + + service是以一个用户态服务应用的形态承载,向上管理、维护安全感知业务的case订阅信息,向下维护case的运行情况。框架core和检测特性集合case采集到的信息由service统一收集,按需转发给不同的安全感知业务。安全感知业务对于底层检测特性集合case和框架core的配置、管理的需求也由service进行统一的管理和转发。不同的安全感知业务可能会需求同样的case,service会统计出所有安全感知业务需求case的并集,向下层注册。 + +- 特性集合cases + + 检测特性集合cases是一系列异常检测探针,根据异常信息的不同会有不同的形态,比如内核异常信息检测的每个探针会以内核模块ko的形态承载。一个case代表一个探针,一个探针往往是一类异常信息或者一类异常事件的信息。比如进程类探针会关注所有进程的创建、退出、属性修改等事件信息,内存修改类探针会收集内核模块列表和安全开关等信息。因此一个探针可能会包含对多个事件的监控,而这些对不同事件的监控逻辑可能无法部署在同一个执行流当中。我们使用工作流(workflow)的概念表示一个探针在同一个执行流中的工作,一个探针可以包含一个或者多个工作流。比如对于进程探针而言,进程创建检测和进程属性修改检测就是不同的工作流。 + +- 框架core + + 检测框架core是每一个case依赖的基础框架,提供case的管理和workflow所需的通用的基础功能单元。内核异常信息检测框架会以内核模块ko的形态承载。一个检测特性case可以将自己注册到框架中,或者从框架中去注册。框架还可以提供特定的交互接口以满足外部的动态请求。一个workflow被定义为有四类功能单元组成:事件发生器、信息采集器、事件分析器、响应单元。 + +特性集合cases和框架core合起来被称为driver。driver驱动提供了secDetector功能的最底层的系统级实现。 + +driver分为两类,kerneldriver 和 usrdriver。顾名思义,kerneldriver是部署在内核态中的,以内核模块的形式承载。usrdriver是部署在用户态中的,直接被部署为service中的一个模块。从逻辑上usrdriver是在service之下的,但是在运行中,为了降低通信成本,usrdriver被直接集成在service程序中。 + +## 能力特性 + +### 检测能力 + +| 特性 | 状态 | 发布版本 | +| ------------------------------ | ------ | ------------------------------------------------------------ | +| 检测框架 | 已实现 | 统一灵活可拓展高效的检测框架,支持不同类型的触发、收集、分析、响应单元。 | +| 进程管理类探针 | 已实现 | 监控进程创建、退出、元数据修改等事件。 | +| 文件操作类探针 | 已实现 | 监控文件创建、删除、读写、属性修改等事件。 | +| 程序行为类探针(API调用) | 已实现 | 监控匿名管道创建、命令执行、ptrace系统调用等关键程序行为。 | +| 内存修改类探针(内核关键数据) | 已实现 | 监控内核模块列表,硬件安全功能开关等内核关键数据。 | + +### 响应能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | -------------------------------------------------- | +| 响应框架 | 已实现 | 统一的灵活可拓展的响应框架,支持不同类型的响应单元。 | +| 告警上报 | 已实现 | 提供异常信息上报能力的响应单元。 | + +### 服务能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | ------------------------------------------------------------ | +| 通信框架 | 已实现 | 应用程序使用gRPC和service进行通信。功能被封装在SDK的动态库中。 | +| 订阅管理 | 已实现 | 应用程序可以一次订阅,长期使用secDetector获取信息。secDetector会对订阅的应用程序进行管理,分发对应的被订阅主题的信息。 | +| 配置下发 | 已实现 | 服务可以通过参数对于特定的检测、阻断特性进行配置,从而实现过滤、调整等功能。目前未对应用程序开放。 | +| 即时检测 | 已实现 | secDetector提供的信息是实时的,准确的,一手的。 | diff --git a/docs/zh/2509/secdetector.md b/docs/zh/2509/secdetector.md new file mode 100644 index 0000000..e20d3fc --- /dev/null +++ b/docs/zh/2509/secdetector.md @@ -0,0 +1,5 @@ +# secDetector 使用指南 + +本文档介绍 openEuler 操作系统内构入侵检测系统 secDetector 的架构、特性、安装、开发指导、落地应用场景等,帮助用户快速了解并使用 secDetector。 + +本文档适用于使用 openEuler 系统并希望了解和使用 secDetector 的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 diff --git a/docs/zh/2509/using_secdetector.md b/docs/zh/2509/using_secdetector.md new file mode 100644 index 0000000..95b8e66 --- /dev/null +++ b/docs/zh/2509/using_secdetector.md @@ -0,0 +1,46 @@ +# 使用 secDetector + +secDetector 提供了SDK,一个so库,用户可以在自己的应用程序中集成该动态链接库从而通过简单的接口使用secDetector。本章介绍其使用方法。 + +## 基本用法 + +用户按照指南《[安装secDetector](./install_secdetector.md)》安装完secDetector之后,libsecDetectorsdk.so、secDetector_sdk.h、secDetector_topic.h就已经被部署到系统用户库默认路径中。 + +1. 使用 C 或 C++ 开发的应用程序确保include路径包含后,可以首先在程序中引用这两个头文件。 + + ```c + #include + #include + ``` + +2. 参考指南《[接口参考](./api_reference.md)》调用SDK提供的接口访问secDetector。 + + 1. 首先调用订阅接口secSub,订阅所需的主题。 + 2. 然后在独立线程中调用消息读取接口secReadFrom阻塞式的读取被订阅主题产生的信息。 + 3. 最后当不需要使用secDetector时,调用退订接口secUnsub。退订时请严格使用订阅时的返回值。 + +## 代码示例 + +可以参考secDetector代码仓上的示例代码,由python语言编写。 + +1. 可以在如下链接中查看示例代码。 + + [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) + +2. 也可以下载后参考。 + + ```shell + git clone https://gitee.com/openeuler/secDetector.git + ``` + +## 规格与约束 + +1. 部分功能(如内存修改探针-安全开关)依赖硬件体系结构,因此在不同指令集架构上的表现并不相同。 +2. 从内核到用户态传输数据缓存空间为探针共享,缓冲区满会丢弃新采集的事件信息。缓存空间可配置范围为4~1024 MB, 必须为2的幂。 +3. 服务进程secDetectord支持root用户运行,不支持多实例,非第一个运行的程序会退出。 +4. 用户订阅连接数限制为5个。 +5. 用户订阅后,读取消息时需要为消息读取接口提供一块缓冲区,超过缓冲区长度的消息将被截断。建议缓冲区长度不低于4096。 +6. 对于文件名、节点名之类的描述字符串都有一定的长度限制,过长可能会被截断。 +7. 应用程序单进程内不支持并行多连接 secDetectord 接收消息。只能一次订阅,单连接接受消息。去订阅后才能重新订阅。 +8. secDetectord 进程应当等待所有应用程序的连接中断即完全退订所有主题后,才可以关闭退出。 +9. 部分功能(如内存修改探针-安全开关)基于当前CPU状态。因此检测的基本功能是可以检测到当前CPU上的状态变化,其他CPU上的状态变化如果未能及时同步到当前CPU,则不会被检测到。 diff --git a/docs/zh/master/_toc.yaml b/docs/zh/master/_toc.yaml new file mode 100644 index 0000000..f64888c --- /dev/null +++ b/docs/zh/master/_toc.yaml @@ -0,0 +1,14 @@ +label: secDetector使用指南 +isManual: true +description: secDetector 是 OS 内构入侵检测系统,为关键信息基础设施提供入侵检测及响应能力 +sections: + - label: 概述 + href: ./secdetector.md + - label: 认识secDetector + href: ./introduction_to_secdetector.md + - label: 安装与部署 + href: ./install_secdetector.md + - label: 接口参考 + href: ./api_reference.md + - label: 使用secDetector + href: ./using_secdetector.md diff --git a/docs/zh/master/api_reference.md b/docs/zh/master/api_reference.md new file mode 100644 index 0000000..d8d44a9 --- /dev/null +++ b/docs/zh/master/api_reference.md @@ -0,0 +1,80 @@ +# 接口说明 + +secDetector操作系统内构入侵检测系统对外提供SDK,这里给出用户开发应用程序所需的接口。SDK的接口设计非常简单,一共只有三个接口,两个头文件。 + +头文件: + +- secDetector/secDetector_sdk.h:包含接口定义 +- secDetector/secDetector_topic.h:包含一些调用接口所需使用的预定义宏,如可选择性订阅的功能主题编号 + +## secSub + +订阅 topic 接口。 + +**功能**: + +订阅接口,应用程序通过输入不同 topic id,可以选择订阅不同的功能主题,比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题,多个探针的 topic id 可以以位图的形式进行组合。 + +> [!NOTE]说明 +> 由于一次订阅产生一个reader即信息读取器,所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容,可以退订之后再重新订阅。 + +**函数声明:** + +```c +void *secSub(const int topic); +``` + +**参数:** + +- topic:入参,需要订阅的主题集合 + +**返回值:** + +- NULL:订阅失败 +- NOT NULL:读取订阅主题相关信息的GRPC reader读取器 + +## secUnsub + +退订 topic 接口。 + +**功能**: + +退订接口,应用程序通过输入订阅成功后获得的reader,完成主题的退订。退订后应用程序便不会收到相应主题的信息。系统中某主题如果没有任何应用程序订阅,则不会被执行。 + +**函数声明:** + +```c +void secUnsub(void *reader); +``` + +**参数:** + +- reader:入参,需要退订的信息读取器 + +**返回值:** + +- 无 + +## secReadFrom + +已订阅主题的消息读取接口。 + +**功能**: + +使用订阅接口对某些主题的订阅成功后,执行退订操作之前,可使用本接口接受 secDetector 发送的已订阅主题的消息。本接口是阻塞式的。应用程序建议使用独立的线程循环调用。当已订阅主题有消息时候,本函数才会被恢复执行。 + +**函数声明:** + +```c +void secReadFrom(void *reader, char *data, int data_len); +``` + +**参数:** + +- reader:入参,主题订阅成功后得到的消息读取器 +- data:出参,消息缓冲区,由应用程序提供的一段内存 +- data_len:入参,消息缓冲区的尺寸 + +**返回值:** + +- 无 diff --git a/docs/zh/master/install_secdetector.md b/docs/zh/master/install_secdetector.md new file mode 100644 index 0000000..7172014 --- /dev/null +++ b/docs/zh/master/install_secdetector.md @@ -0,0 +1,105 @@ +# 安装 secDetector + +## 软硬件要求 + +### 硬件要求 + +* 当前仅支持 x86_64、aarch64 架构处理器。 +* secDetector磁盘使用需求:配额1GB及以上。 +* secDetector内存使用需求:配额100MB及以上。 + +### 概述 + +### 环境准备 + +安装 openEuler 系统,安装方法参考《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 + +## 安装secDetector + +1. 配置openEuler yum源:openEuler 发布版本上已默认配置完成yum源,无需额外操作。特殊情况下请参考openEuler官方文档配置在线yum源或通过ISO挂载配置本地yum源。 + +2. 安装secDetector。 + + ```shell + #安装secDetector + sudo yum install secDetector + ``` + +> [!NOTE]说明 +> +> 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件: + +```shell +#secDetector的kerneldriver的核心框架 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko + +#secDetector的kerneldriver的功能组件 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko + +#secDetector的守护者进程文件 +/usr/bin/secDetectord + +#secDetector的SDK库文件 +/usr/lib64/secDetector/libsecDetectorsdk.so +/usr/include/secDetector/secDetector_sdk.h +/usr/include/secDetector/secDetector_topic.h +``` + +## 部署 secDetector + +secDetector的主体secDetectord是以系统服务的形式部署在系统中的,前台业务系统可以通过集成SDK来与之通信。由于secDetector的部分能力必须构建在内核之中,因此secDetectord的功能全集还依赖于其后台驱动的部署。 + +### 部署 kernel driver + +1. 插入 kernel driver 的基础框架:secDetector_core.ko 是 kernel driver 的基础框架,要优先于其他内核模块进行部署。找到安装后的 secDetector_core.ko 目录,将其插入内核。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko + ``` + + secDetector_core 支持一个命令行参数ringbuf_size。用户可以通过指定该参数的值来控制 kernel driver 与 用户态secDetectord之间数据通道的缓存空间尺寸。该参数可以被指定为4~1024中的一个整数,单位是MB。默认值是4,必须为2的幂。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko ringbuf_size=128 + ``` + +2. 插入 kernel driver 的功能模块:secDetector的 kernel driver 采用模块化部署方式。用户可以选择基于框架部署满足需要的功能模块,也可以选择部署全部模块。参考命令如下: + + ```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 提供了内核模块列表检测的能力,属于内存修改类探针; + - secDetector_memory_corruption.ko 提供了内存修改检测的能力,属于内存修改类探针; + - secDetector_program_action.ko 提供了程序行为检测的能力,属于程序行为类探针。 + +### 部署 usr driver 和 observer_agent + +当前用户态驱动 usr driver 和服务 observer_agent 已经都被集成到secDetectord中,参考命令如下: + +```shell +sudo ./secDetectord & +``` + +usr driver当前包含了文件操作类探针和进程管理类探针的能力。 + +secDetectord支持如下一些配置选项: + +```text +用法:secDetectord [选项] +secDetectord 默认会在后台运行,从探针中取得数据并转发给订阅者。 +选项: + -d 进入调试模式,进入前台运行,并且在控制台打印探针数据。 + -s 配置eBPF缓冲区大小,单位为Mb,默认为4; size可选范围为4~1024,且必须为2的幂次方。当前拥有2个独立的缓冲区。 + -t 支持配置订阅的事件,默认为所有事件。topic 是位图格式。例如 -t 0x60 同时订阅进程创建和进程退出事件。详细请查阅 include/secDetector_topic.h。 +``` + +### 部署SDK + +SDK的库文件默认已经被部署到系统库目录中,用户需要在自己的程序中引用SDK的头文件即可使用。 diff --git a/docs/zh/master/introduction_to_secdetector.md b/docs/zh/master/introduction_to_secdetector.md new file mode 100644 index 0000000..7f98262 --- /dev/null +++ b/docs/zh/master/introduction_to_secdetector.md @@ -0,0 +1,97 @@ +# 认识secDetector + +## 简介 + +secDetector 是专为OS设计的内构入侵检测系统,旨在为关键信息基础设施提供入侵检测及响应能力,为第三方安全工具减少开发成本同时增强检测和响应能力。secDetector 基于ATT&CK攻击模式库建模提供更为丰富的安全事件原语,并且可以提供实时阻断和灵活调整的响应能力。 + +secDetector 作为一套灵活的OS内构入侵检测系统,有三种使用模式: + +1. 直接被系统用户开启用作一些基础异常事件的告警和处置。 +2. 被安全态势感知服务集成,补齐系统信息采集缺陷,用于APT等复杂的安全威胁分析和重点事件布控实时阻断。 +3. 由安全从业人员或安全感知服务提供商二次开发,基于可拓展框架构建精确、高效、及时的入侵检测与响应能力。 + +## 软件架构 + +```text +||==APP===================================================================|| +|| || +|| ---------------------------- || +|| | SDK | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | + | + | +||==OBSERVER========================|=====================================|| +|| | || +|| ---------------------------- || +|| | service | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | +||==DRIVER================================================================|| +|| || +|| ---------------------------- || +|| | 8 types of cases | || +|| ---------------------------- || +|| || +||------------------------------------------------------------------------|| +|| core || +|| ------------- ---------------- ---------------- ----------------- || +|| | hook unit | | collect unit | | analyze unit | | response unit | || +|| ------------- ---------------- ---------------- ----------------- || +|| || +||========================================================================|| +``` + +secDetector在架构上分为四个部分:SDK、service、检测特性集合cases、检测框架core。 + +- SDK + + SDK是以一个用户态动态链接库lib的形态承载,被部署到需要使用secDetector入侵检测系统的安全感知业务中。SDK用于和secDetector入侵检测系统的service通讯,完成所需的工作(例如订阅,去订阅,读取现有消息等功能)。secDetector提供的异常信息被定义成不同的case,安全感知业务可以根据自身需求订阅。 + +- service + + service是以一个用户态服务应用的形态承载,向上管理、维护安全感知业务的case订阅信息,向下维护case的运行情况。框架core和检测特性集合case采集到的信息由service统一收集,按需转发给不同的安全感知业务。安全感知业务对于底层检测特性集合case和框架core的配置、管理的需求也由service进行统一的管理和转发。不同的安全感知业务可能会需求同样的case,service会统计出所有安全感知业务需求case的并集,向下层注册。 + +- 特性集合cases + + 检测特性集合cases是一系列异常检测探针,根据异常信息的不同会有不同的形态,比如内核异常信息检测的每个探针会以内核模块ko的形态承载。一个case代表一个探针,一个探针往往是一类异常信息或者一类异常事件的信息。比如进程类探针会关注所有进程的创建、退出、属性修改等事件信息,内存修改类探针会收集内核模块列表和安全开关等信息。因此一个探针可能会包含对多个事件的监控,而这些对不同事件的监控逻辑可能无法部署在同一个执行流当中。我们使用工作流(workflow)的概念表示一个探针在同一个执行流中的工作,一个探针可以包含一个或者多个工作流。比如对于进程探针而言,进程创建检测和进程属性修改检测就是不同的工作流。 + +- 框架core + + 检测框架core是每一个case依赖的基础框架,提供case的管理和workflow所需的通用的基础功能单元。内核异常信息检测框架会以内核模块ko的形态承载。一个检测特性case可以将自己注册到框架中,或者从框架中去注册。框架还可以提供特定的交互接口以满足外部的动态请求。一个workflow被定义为有四类功能单元组成:事件发生器、信息采集器、事件分析器、响应单元。 + +特性集合cases和框架core合起来被称为driver。driver驱动提供了secDetector功能的最底层的系统级实现。 + +driver分为两类,kerneldriver 和 usrdriver。顾名思义,kerneldriver是部署在内核态中的,以内核模块的形式承载。usrdriver是部署在用户态中的,直接被部署为service中的一个模块。从逻辑上usrdriver是在service之下的,但是在运行中,为了降低通信成本,usrdriver被直接集成在service程序中。 + +## 能力特性 + +### 检测能力 + +| 特性 | 状态 | 发布版本 | +| ------------------------------ | ------ | ------------------------------------------------------------ | +| 检测框架 | 已实现 | 统一灵活可拓展高效的检测框架,支持不同类型的触发、收集、分析、响应单元。 | +| 进程管理类探针 | 已实现 | 监控进程创建、退出、元数据修改等事件。 | +| 文件操作类探针 | 已实现 | 监控文件创建、删除、读写、属性修改等事件。 | +| 程序行为类探针(API调用) | 已实现 | 监控匿名管道创建、命令执行、ptrace系统调用等关键程序行为。 | +| 内存修改类探针(内核关键数据) | 已实现 | 监控内核模块列表,硬件安全功能开关等内核关键数据。 | + +### 响应能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | -------------------------------------------------- | +| 响应框架 | 已实现 | 统一的灵活可拓展的响应框架,支持不同类型的响应单元。 | +| 告警上报 | 已实现 | 提供异常信息上报能力的响应单元。 | + +### 服务能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | ------------------------------------------------------------ | +| 通信框架 | 已实现 | 应用程序使用gRPC和service进行通信。功能被封装在SDK的动态库中。 | +| 订阅管理 | 已实现 | 应用程序可以一次订阅,长期使用secDetector获取信息。secDetector会对订阅的应用程序进行管理,分发对应的被订阅主题的信息。 | +| 配置下发 | 已实现 | 服务可以通过参数对于特定的检测、阻断特性进行配置,从而实现过滤、调整等功能。目前未对应用程序开放。 | +| 即时检测 | 已实现 | secDetector提供的信息是实时的,准确的,一手的。 | diff --git a/docs/zh/master/secdetector.md b/docs/zh/master/secdetector.md new file mode 100644 index 0000000..e20d3fc --- /dev/null +++ b/docs/zh/master/secdetector.md @@ -0,0 +1,5 @@ +# secDetector 使用指南 + +本文档介绍 openEuler 操作系统内构入侵检测系统 secDetector 的架构、特性、安装、开发指导、落地应用场景等,帮助用户快速了解并使用 secDetector。 + +本文档适用于使用 openEuler 系统并希望了解和使用 secDetector 的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 diff --git a/docs/zh/master/using_secdetector.md b/docs/zh/master/using_secdetector.md new file mode 100644 index 0000000..95b8e66 --- /dev/null +++ b/docs/zh/master/using_secdetector.md @@ -0,0 +1,46 @@ +# 使用 secDetector + +secDetector 提供了SDK,一个so库,用户可以在自己的应用程序中集成该动态链接库从而通过简单的接口使用secDetector。本章介绍其使用方法。 + +## 基本用法 + +用户按照指南《[安装secDetector](./install_secdetector.md)》安装完secDetector之后,libsecDetectorsdk.so、secDetector_sdk.h、secDetector_topic.h就已经被部署到系统用户库默认路径中。 + +1. 使用 C 或 C++ 开发的应用程序确保include路径包含后,可以首先在程序中引用这两个头文件。 + + ```c + #include + #include + ``` + +2. 参考指南《[接口参考](./api_reference.md)》调用SDK提供的接口访问secDetector。 + + 1. 首先调用订阅接口secSub,订阅所需的主题。 + 2. 然后在独立线程中调用消息读取接口secReadFrom阻塞式的读取被订阅主题产生的信息。 + 3. 最后当不需要使用secDetector时,调用退订接口secUnsub。退订时请严格使用订阅时的返回值。 + +## 代码示例 + +可以参考secDetector代码仓上的示例代码,由python语言编写。 + +1. 可以在如下链接中查看示例代码。 + + [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) + +2. 也可以下载后参考。 + + ```shell + git clone https://gitee.com/openeuler/secDetector.git + ``` + +## 规格与约束 + +1. 部分功能(如内存修改探针-安全开关)依赖硬件体系结构,因此在不同指令集架构上的表现并不相同。 +2. 从内核到用户态传输数据缓存空间为探针共享,缓冲区满会丢弃新采集的事件信息。缓存空间可配置范围为4~1024 MB, 必须为2的幂。 +3. 服务进程secDetectord支持root用户运行,不支持多实例,非第一个运行的程序会退出。 +4. 用户订阅连接数限制为5个。 +5. 用户订阅后,读取消息时需要为消息读取接口提供一块缓冲区,超过缓冲区长度的消息将被截断。建议缓冲区长度不低于4096。 +6. 对于文件名、节点名之类的描述字符串都有一定的长度限制,过长可能会被截断。 +7. 应用程序单进程内不支持并行多连接 secDetectord 接收消息。只能一次订阅,单连接接受消息。去订阅后才能重新订阅。 +8. secDetectord 进程应当等待所有应用程序的连接中断即完全退订所有主题后,才可以关闭退出。 +9. 部分功能(如内存修改探针-安全开关)基于当前CPU状态。因此检测的基本功能是可以检测到当前CPU上的状态变化,其他CPU上的状态变化如果未能及时同步到当前CPU,则不会被检测到。 -- Gitee From ce14495c68b0609264bb5056072b66b490c0d7c7 Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Tue, 2 Sep 2025 17:40:26 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=E5=88=A0=E9=99=A4=E5=A4=A7=E5=86=99?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=A4=B9?= 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 ---------------- docs/en/2403_LTS_SP2/secdetector.md | 5 - docs/en/2403_LTS_SP2/using_secdetector.md | 46 -------- docs/zh/2403_LTS_SP2/_toc.yaml | 14 --- docs/zh/2403_LTS_SP2/api_reference.md | 80 ------------- docs/zh/2403_LTS_SP2/install_secdetector.md | 105 ------------------ .../introduction_to_secdetector.md | 97 ---------------- docs/zh/2403_LTS_SP2/secdetector.md | 5 - docs/zh/2403_LTS_SP2/using_secdetector.md | 46 -------- 12 files changed, 693 deletions(-) delete mode 100644 docs/en/2403_LTS_SP2/_toc.yaml delete mode 100644 docs/en/2403_LTS_SP2/api_reference.md delete mode 100644 docs/en/2403_LTS_SP2/install_secdetector.md delete mode 100644 docs/en/2403_LTS_SP2/introduction_to_secdetector.md delete mode 100644 docs/en/2403_LTS_SP2/secdetector.md delete mode 100644 docs/en/2403_LTS_SP2/using_secdetector.md delete mode 100644 docs/zh/2403_LTS_SP2/_toc.yaml delete mode 100644 docs/zh/2403_LTS_SP2/api_reference.md delete mode 100644 docs/zh/2403_LTS_SP2/install_secdetector.md delete mode 100644 docs/zh/2403_LTS_SP2/introduction_to_secdetector.md delete mode 100644 docs/zh/2403_LTS_SP2/secdetector.md delete mode 100644 docs/zh/2403_LTS_SP2/using_secdetector.md diff --git a/docs/en/2403_LTS_SP2/_toc.yaml b/docs/en/2403_LTS_SP2/_toc.yaml deleted file mode 100644 index bc851fe..0000000 --- a/docs/en/2403_LTS_SP2/_toc.yaml +++ /dev/null @@ -1,14 +0,0 @@ -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 deleted file mode 100644 index 8ad746b..0000000 --- a/docs/en/2403_LTS_SP2/api_reference.md +++ /dev/null @@ -1,81 +0,0 @@ -# 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 deleted file mode 100644 index fd76e76..0000000 --- a/docs/en/2403_LTS_SP2/install_secdetector.md +++ /dev/null @@ -1,103 +0,0 @@ -# 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 deleted file mode 100644 index 74a42b4..0000000 --- a/docs/en/2403_LTS_SP2/introduction_to_secdetector.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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/secdetector.md b/docs/en/2403_LTS_SP2/secdetector.md deleted file mode 100644 index 733fb53..0000000 --- a/docs/en/2403_LTS_SP2/secdetector.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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 deleted file mode 100644 index 4ac1dfb..0000000 --- a/docs/en/2403_LTS_SP2/using_secdetector.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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 deleted file mode 100644 index f64888c..0000000 --- a/docs/zh/2403_LTS_SP2/_toc.yaml +++ /dev/null @@ -1,14 +0,0 @@ -label: secDetector使用指南 -isManual: true -description: secDetector 是 OS 内构入侵检测系统,为关键信息基础设施提供入侵检测及响应能力 -sections: - - label: 概述 - href: ./secdetector.md - - label: 认识secDetector - href: ./introduction_to_secdetector.md - - label: 安装与部署 - href: ./install_secdetector.md - - label: 接口参考 - href: ./api_reference.md - - label: 使用secDetector - href: ./using_secdetector.md diff --git a/docs/zh/2403_LTS_SP2/api_reference.md b/docs/zh/2403_LTS_SP2/api_reference.md deleted file mode 100644 index d8d44a9..0000000 --- a/docs/zh/2403_LTS_SP2/api_reference.md +++ /dev/null @@ -1,80 +0,0 @@ -# 接口说明 - -secDetector操作系统内构入侵检测系统对外提供SDK,这里给出用户开发应用程序所需的接口。SDK的接口设计非常简单,一共只有三个接口,两个头文件。 - -头文件: - -- secDetector/secDetector_sdk.h:包含接口定义 -- secDetector/secDetector_topic.h:包含一些调用接口所需使用的预定义宏,如可选择性订阅的功能主题编号 - -## secSub - -订阅 topic 接口。 - -**功能**: - -订阅接口,应用程序通过输入不同 topic id,可以选择订阅不同的功能主题,比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题,多个探针的 topic id 可以以位图的形式进行组合。 - -> [!NOTE]说明 -> 由于一次订阅产生一个reader即信息读取器,所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容,可以退订之后再重新订阅。 - -**函数声明:** - -```c -void *secSub(const int topic); -``` - -**参数:** - -- topic:入参,需要订阅的主题集合 - -**返回值:** - -- NULL:订阅失败 -- NOT NULL:读取订阅主题相关信息的GRPC reader读取器 - -## secUnsub - -退订 topic 接口。 - -**功能**: - -退订接口,应用程序通过输入订阅成功后获得的reader,完成主题的退订。退订后应用程序便不会收到相应主题的信息。系统中某主题如果没有任何应用程序订阅,则不会被执行。 - -**函数声明:** - -```c -void secUnsub(void *reader); -``` - -**参数:** - -- reader:入参,需要退订的信息读取器 - -**返回值:** - -- 无 - -## secReadFrom - -已订阅主题的消息读取接口。 - -**功能**: - -使用订阅接口对某些主题的订阅成功后,执行退订操作之前,可使用本接口接受 secDetector 发送的已订阅主题的消息。本接口是阻塞式的。应用程序建议使用独立的线程循环调用。当已订阅主题有消息时候,本函数才会被恢复执行。 - -**函数声明:** - -```c -void secReadFrom(void *reader, char *data, int data_len); -``` - -**参数:** - -- reader:入参,主题订阅成功后得到的消息读取器 -- data:出参,消息缓冲区,由应用程序提供的一段内存 -- data_len:入参,消息缓冲区的尺寸 - -**返回值:** - -- 无 diff --git a/docs/zh/2403_LTS_SP2/install_secdetector.md b/docs/zh/2403_LTS_SP2/install_secdetector.md deleted file mode 100644 index 7172014..0000000 --- a/docs/zh/2403_LTS_SP2/install_secdetector.md +++ /dev/null @@ -1,105 +0,0 @@ -# 安装 secDetector - -## 软硬件要求 - -### 硬件要求 - -* 当前仅支持 x86_64、aarch64 架构处理器。 -* secDetector磁盘使用需求:配额1GB及以上。 -* secDetector内存使用需求:配额100MB及以上。 - -### 概述 - -### 环境准备 - -安装 openEuler 系统,安装方法参考《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 - -## 安装secDetector - -1. 配置openEuler yum源:openEuler 发布版本上已默认配置完成yum源,无需额外操作。特殊情况下请参考openEuler官方文档配置在线yum源或通过ISO挂载配置本地yum源。 - -2. 安装secDetector。 - - ```shell - #安装secDetector - sudo yum install secDetector - ``` - -> [!NOTE]说明 -> -> 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件: - -```shell -#secDetector的kerneldriver的核心框架 -/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko - -#secDetector的kerneldriver的功能组件 -/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko - -#secDetector的守护者进程文件 -/usr/bin/secDetectord - -#secDetector的SDK库文件 -/usr/lib64/secDetector/libsecDetectorsdk.so -/usr/include/secDetector/secDetector_sdk.h -/usr/include/secDetector/secDetector_topic.h -``` - -## 部署 secDetector - -secDetector的主体secDetectord是以系统服务的形式部署在系统中的,前台业务系统可以通过集成SDK来与之通信。由于secDetector的部分能力必须构建在内核之中,因此secDetectord的功能全集还依赖于其后台驱动的部署。 - -### 部署 kernel driver - -1. 插入 kernel driver 的基础框架:secDetector_core.ko 是 kernel driver 的基础框架,要优先于其他内核模块进行部署。找到安装后的 secDetector_core.ko 目录,将其插入内核。参考命令如下: - - ```shell - sudo insmod secDetector_core.ko - ``` - - secDetector_core 支持一个命令行参数ringbuf_size。用户可以通过指定该参数的值来控制 kernel driver 与 用户态secDetectord之间数据通道的缓存空间尺寸。该参数可以被指定为4~1024中的一个整数,单位是MB。默认值是4,必须为2的幂。参考命令如下: - - ```shell - sudo insmod secDetector_core.ko ringbuf_size=128 - ``` - -2. 插入 kernel driver 的功能模块:secDetector的 kernel driver 采用模块化部署方式。用户可以选择基于框架部署满足需要的功能模块,也可以选择部署全部模块。参考命令如下: - - ```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 提供了内核模块列表检测的能力,属于内存修改类探针; - - secDetector_memory_corruption.ko 提供了内存修改检测的能力,属于内存修改类探针; - - secDetector_program_action.ko 提供了程序行为检测的能力,属于程序行为类探针。 - -### 部署 usr driver 和 observer_agent - -当前用户态驱动 usr driver 和服务 observer_agent 已经都被集成到secDetectord中,参考命令如下: - -```shell -sudo ./secDetectord & -``` - -usr driver当前包含了文件操作类探针和进程管理类探针的能力。 - -secDetectord支持如下一些配置选项: - -```text -用法:secDetectord [选项] -secDetectord 默认会在后台运行,从探针中取得数据并转发给订阅者。 -选项: - -d 进入调试模式,进入前台运行,并且在控制台打印探针数据。 - -s 配置eBPF缓冲区大小,单位为Mb,默认为4; size可选范围为4~1024,且必须为2的幂次方。当前拥有2个独立的缓冲区。 - -t 支持配置订阅的事件,默认为所有事件。topic 是位图格式。例如 -t 0x60 同时订阅进程创建和进程退出事件。详细请查阅 include/secDetector_topic.h。 -``` - -### 部署SDK - -SDK的库文件默认已经被部署到系统库目录中,用户需要在自己的程序中引用SDK的头文件即可使用。 diff --git a/docs/zh/2403_LTS_SP2/introduction_to_secdetector.md b/docs/zh/2403_LTS_SP2/introduction_to_secdetector.md deleted file mode 100644 index 1e5dee9..0000000 --- a/docs/zh/2403_LTS_SP2/introduction_to_secdetector.md +++ /dev/null @@ -1,97 +0,0 @@ -# 认识secDetector - -## 简介 - -secDetector 是专为OS设计的内构入侵检测系统,旨在为关键信息基础设施提供入侵检测及响应能力,为第三方安全工具减少开发成本同时增强检测和响应能力。secDetector 基于ATT&CK攻击模式库建模提供更为丰富的安全事件原语,并且可以提供实时阻断和灵活调整的响应能力。 - -secDetector 作为一套灵活的OS内构入侵检测系统,有三种使用模式: - -1. 直接被系统用户开启用作一些基础异常事件的告警和处置。 -2. 被安全态势感知服务集成,补齐系统信息采集缺陷,用于APT等复杂的安全威胁分析和重点事件布控实时阻断。 -3. 由安全从业人员或安全感知服务提供商二次开发,基于可拓展框架构建精确、高效、及时的入侵检测与响应能力。 - -## 软件架构 - -```text -||==APP===================================================================|| -|| || -|| ---------------------------- || -|| | SDK | || -|| ---------------------------- || -|| /^\ || -||==================================|=====================================|| - | - | - | -||==OBSERVER========================|=====================================|| -|| | || -|| ---------------------------- || -|| | service | || -|| ---------------------------- || -|| /^\ || -||==================================|=====================================|| - | -||==DRIVER================================================================|| -|| || -|| ---------------------------- || -|| | 8 types of cases | || -|| ---------------------------- || -|| || -||------------------------------------------------------------------------|| -|| core || -|| ------------- ---------------- ---------------- ----------------- || -|| | hook unit | | collect unit | | analyze unit | | response unit | || -|| ------------- ---------------- ---------------- ----------------- || -|| || -||========================================================================|| -``` - -secDetector在架构上分为四个部分:SDK、service、检测特性集合cases、检测框架core。 - -- SDK - - SDK是以一个用户态动态链接库lib的形态承载,被部署到需要使用secDetector入侵检测系统的安全感知业务中。SDK用于和secDetector入侵检测系统的service通讯,完成所需的工作(例如订阅,去订阅,读取现有消息等功能)。secDetector提供的异常信息被定义成不同的case,安全感知业务可以根据自身需求订阅。 - -- service - - service是以一个用户态服务应用的形态承载,向上管理、维护安全感知业务的case订阅信息,向下维护case的运行情况。框架core和检测特性集合case采集到的信息由service统一收集,按需转发给不同的安全感知业务。安全感知业务对于底层检测特性集合case和框架core的配置、管理的需求也由service进行统一的管理和转发。不同的安全感知业务可能会需求同样的case,service会统计出所有安全感知业务需求case的并集,向下层注册。 - -- 特性集合cases - - 检测特性集合cases是一系列异常检测探针,根据异常信息的不同会有不同的形态,比如内核异常信息检测的每个探针会以内核模块ko的形态承载。一个case代表一个探针,一个探针往往是一类异常信息或者一类异常事件的信息。比如进程类探针会关注所有进程的创建、退出、属性修改等事件信息,内存修改类探针会收集内核模块列表和安全开关等信息。因此一个探针可能会包含对多个事件的监控,而这些对不同事件的监控逻辑可能无法部署在同一个执行流当中。我们使用工作流(workflow)的概念表示一个探针在同一个执行流中的工作,一个探针可以包含一个或者多个工作流。比如对于进程探针而言,进程创建检测和进程属性修改检测就是不同的工作流。 - -- 框架core - - 检测框架core是每一个case依赖的基础框架,提供case的管理和workflow所需的通用的基础功能单元。内核异常信息检测框架会以内核模块ko的形态承载。一个检测特性case可以将自己注册到框架中,或者从框架中去注册。框架还可以提供特定的交互接口以满足外部的动态请求。一个workflow被定义为有四类功能单元组成:事件发生器、信息采集器、事件分析器、响应单元。 - -特性集合cases和框架core合起来被称为driver。driver驱动提供了secDetector功能的最底层的系统级实现。 - -driver分为两类,kerneldriver 和 usrdriver。顾名思义,kerneldriver是部署在内核态中的,以内核模块的形式承载。usrdriver是部署在用户态中的,直接被部署为service中的一个模块。从逻辑上usrdriver是在service之下的,但是在运行中,为了降低通信成本,usrdriver被直接集成在service程序中。 - -## 能力特性 - -### 检测能力 - -| 特性 | 状态 | 发布版本 | -| ------------------------------ | ------ | ------------------------------------------------------------ | -| 检测框架 | 已实现 | 统一灵活可拓展高效的检测框架,支持不同类型的触发、收集、分析、响应单元 | -| 进程管理类探针 | 已实现 | 监控进程创建、退出、元数据修改等事件 | -| 文件操作类探针 | 已实现 | 监控文件创建、删除、读写、属性修改等事件 | -| 程序行为类探针(API调用) | 已实现 | 监控匿名管道创建、命令执行、ptrace系统调用等关键程序行为 | -| 内存修改类探针(内核关键数据) | 已实现 | 监控内核模块列表,硬件安全功能开关等内核关键数据 | - -### 响应能力 - -| 特性 | 状态 | 说明 | -| -------- | ------ | -------------------------------------------------- | -| 响应框架 | 已实现 | 统一的灵活可拓展的响应框架,支持不同类型的响应单元 | -| 告警上报 | 已实现 | 提供异常信息上报能力的响应单元 | - -### 服务能力 - -| 特性 | 状态 | 说明 | -| -------- | ------ | ------------------------------------------------------------ | -| 通信框架 | 已实现 | 应用程序使用gRPC和service进行通信。功能被封装在SDK的动态库中。 | -| 订阅管理 | 已实现 | 应用程序可以一次订阅,长期使用secDetector获取信息。secDetector会对订阅的应用程序进行管理,分发对应的被订阅主题的信息。 | -| 配置下发 | 已实现 | 服务可以通过参数对于特定的检测、阻断特性进行配置,从而实现过滤、调整等功能。目前未对应用程序开放。 | -| 即时检测 | 已实现 | secDetector提供的信息是实时的,准确的,一手的。 | diff --git a/docs/zh/2403_LTS_SP2/secdetector.md b/docs/zh/2403_LTS_SP2/secdetector.md deleted file mode 100644 index e20d3fc..0000000 --- a/docs/zh/2403_LTS_SP2/secdetector.md +++ /dev/null @@ -1,5 +0,0 @@ -# secDetector 使用指南 - -本文档介绍 openEuler 操作系统内构入侵检测系统 secDetector 的架构、特性、安装、开发指导、落地应用场景等,帮助用户快速了解并使用 secDetector。 - -本文档适用于使用 openEuler 系统并希望了解和使用 secDetector 的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 diff --git a/docs/zh/2403_LTS_SP2/using_secdetector.md b/docs/zh/2403_LTS_SP2/using_secdetector.md deleted file mode 100644 index 57d08be..0000000 --- a/docs/zh/2403_LTS_SP2/using_secdetector.md +++ /dev/null @@ -1,46 +0,0 @@ -# 使用 secDetector - -secDetector 提供了SDK,一个so库,用户可以在自己的应用程序中集成该动态链接库从而通过简单的接口使用secDetector。本章介绍其使用方法。 - -## 基本用法 - -用户按照指南《[安装secDetector](./install_secdetector.md)》安装完secDetector之后,libsecDetectorsdk.so、secDetector_sdk.h、secDetector_topic.h就已经被部署到系统用户库默认路径中。 - -1. 使用 C 或 C++ 开发的应用程序确保include路径包含后,可以首先在程序中引用这两个头文件。 - - ```c - #include - #include - ``` - -2. 参考指南《[接口参考](./api_reference.md)》调用SDK提供的接口访问secDetector。 - - 1. 首先调用订阅接口secSub,订阅所需的主题。 - 2. 然后在独立线程中调用消息读取接口secReadFrom阻塞式的读取被订阅主题产生的信息。 - 3. 最后当不需要使用secDetector时,调用退订接口secUnsub。退订时请严格使用订阅时的返回值。 - -## 代码示例 - -可以参考secDetector代码仓上的示例代码,由python语言编写。 - -1. 可以在如下链接中查看示例代码 - - [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) - -2. 也可以下载后参考 - - ```shell - git clone https://gitee.com/openeuler/secDetector.git - ``` - -## 规格与约束 - -1. 部分功能(如内存修改探针-安全开关)依赖硬件体系结构,因此在不同指令集架构上的表现并不相同。 -2. 从内核到用户态传输数据缓存空间为探针共享,缓冲区满会丢弃新采集的事件信息。缓存空间可配置范围为4~1024 MB, 必须为2的幂。 -3. 服务进程secDetectord支持root用户运行,不支持多实例,非第一个运行的程序会退出。 -4. 用户订阅连接数限制为5个。 -5. 用户订阅后,读取消息时需要为消息读取接口提供一块缓冲区,超过缓冲区长度的消息将被截断。建议缓冲区长度不低于4096。 -6. 对于文件名、节点名之类的描述字符串都有一定的长度限制,过长可能会被截断。 -7. 应用程序单进程内不支持并行多连接 secDetectord 接收消息。只能一次订阅,单连接接受消息。去订阅后才能重新订阅。 -8. secDetectord 进程应当等待所有应用程序的连接中断即完全退订所有主题后,才可以关闭退出。 -9. 部分功能(如内存修改探针-安全开关)基于当前CPU状态。因此检测的基本功能是可以检测到当前CPU上的状态变化,其他CPU上的状态变化如果未能及时同步到当前CPU,则不会被检测到。 -- Gitee From 70f37feaed718030be643f99b5287c4d0d35bcb0 Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Tue, 2 Sep 2025 17:58:31 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=B0=8F=E5=86=99?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=A4=B9?= 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 ++++++++++++++++ docs/en/2403_lts_sp2/secdetector.md | 5 + docs/en/2403_lts_sp2/using_secdetector.md | 46 ++++++++ docs/zh/2403_lts_sp2/_toc.yaml | 14 +++ docs/zh/2403_lts_sp2/api_reference.md | 80 +++++++++++++ docs/zh/2403_lts_sp2/install_secdetector.md | 105 ++++++++++++++++++ .../introduction_to_secdetector.md | 97 ++++++++++++++++ docs/zh/2403_lts_sp2/secdetector.md | 5 + docs/zh/2403_lts_sp2/using_secdetector.md | 46 ++++++++ 12 files changed, 693 insertions(+) create mode 100644 docs/en/2403_lts_sp2/_toc.yaml 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/secdetector.md create mode 100644 docs/en/2403_lts_sp2/using_secdetector.md create mode 100644 docs/zh/2403_lts_sp2/_toc.yaml create mode 100644 docs/zh/2403_lts_sp2/api_reference.md create mode 100644 docs/zh/2403_lts_sp2/install_secdetector.md create mode 100644 docs/zh/2403_lts_sp2/introduction_to_secdetector.md create mode 100644 docs/zh/2403_lts_sp2/secdetector.md create mode 100644 docs/zh/2403_lts_sp2/using_secdetector.md diff --git a/docs/en/2403_lts_sp2/_toc.yaml b/docs/en/2403_lts_sp2/_toc.yaml new file mode 100644 index 0000000..bc851fe --- /dev/null +++ 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/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 new file mode 100644 index 0000000..f64888c --- /dev/null +++ b/docs/zh/2403_lts_sp2/_toc.yaml @@ -0,0 +1,14 @@ +label: secDetector使用指南 +isManual: true +description: secDetector 是 OS 内构入侵检测系统,为关键信息基础设施提供入侵检测及响应能力 +sections: + - label: 概述 + href: ./secdetector.md + - label: 认识secDetector + href: ./introduction_to_secdetector.md + - label: 安装与部署 + href: ./install_secdetector.md + - label: 接口参考 + href: ./api_reference.md + - label: 使用secDetector + href: ./using_secdetector.md diff --git a/docs/zh/2403_lts_sp2/api_reference.md b/docs/zh/2403_lts_sp2/api_reference.md new file mode 100644 index 0000000..d8d44a9 --- /dev/null +++ b/docs/zh/2403_lts_sp2/api_reference.md @@ -0,0 +1,80 @@ +# 接口说明 + +secDetector操作系统内构入侵检测系统对外提供SDK,这里给出用户开发应用程序所需的接口。SDK的接口设计非常简单,一共只有三个接口,两个头文件。 + +头文件: + +- secDetector/secDetector_sdk.h:包含接口定义 +- secDetector/secDetector_topic.h:包含一些调用接口所需使用的预定义宏,如可选择性订阅的功能主题编号 + +## secSub + +订阅 topic 接口。 + +**功能**: + +订阅接口,应用程序通过输入不同 topic id,可以选择订阅不同的功能主题,比如文件打开类异常探针。secDetector 提供的诸功能主题对应的 topic id 的定义在 secDetector_topic.h 中可以查看。本订阅接口支持一次订阅多个主题,多个探针的 topic id 可以以位图的形式进行组合。 + +> [!NOTE]说明 +> 由于一次订阅产生一个reader即信息读取器,所以应用程序应当在一次订阅接口调用中订阅所需的所有主题。这样就可以使用一个reader进行信息的采集。如果需要调整订阅的内容,可以退订之后再重新订阅。 + +**函数声明:** + +```c +void *secSub(const int topic); +``` + +**参数:** + +- topic:入参,需要订阅的主题集合 + +**返回值:** + +- NULL:订阅失败 +- NOT NULL:读取订阅主题相关信息的GRPC reader读取器 + +## secUnsub + +退订 topic 接口。 + +**功能**: + +退订接口,应用程序通过输入订阅成功后获得的reader,完成主题的退订。退订后应用程序便不会收到相应主题的信息。系统中某主题如果没有任何应用程序订阅,则不会被执行。 + +**函数声明:** + +```c +void secUnsub(void *reader); +``` + +**参数:** + +- reader:入参,需要退订的信息读取器 + +**返回值:** + +- 无 + +## secReadFrom + +已订阅主题的消息读取接口。 + +**功能**: + +使用订阅接口对某些主题的订阅成功后,执行退订操作之前,可使用本接口接受 secDetector 发送的已订阅主题的消息。本接口是阻塞式的。应用程序建议使用独立的线程循环调用。当已订阅主题有消息时候,本函数才会被恢复执行。 + +**函数声明:** + +```c +void secReadFrom(void *reader, char *data, int data_len); +``` + +**参数:** + +- reader:入参,主题订阅成功后得到的消息读取器 +- data:出参,消息缓冲区,由应用程序提供的一段内存 +- data_len:入参,消息缓冲区的尺寸 + +**返回值:** + +- 无 diff --git a/docs/zh/2403_lts_sp2/install_secdetector.md b/docs/zh/2403_lts_sp2/install_secdetector.md new file mode 100644 index 0000000..7172014 --- /dev/null +++ b/docs/zh/2403_lts_sp2/install_secdetector.md @@ -0,0 +1,105 @@ +# 安装 secDetector + +## 软硬件要求 + +### 硬件要求 + +* 当前仅支持 x86_64、aarch64 架构处理器。 +* secDetector磁盘使用需求:配额1GB及以上。 +* secDetector内存使用需求:配额100MB及以上。 + +### 概述 + +### 环境准备 + +安装 openEuler 系统,安装方法参考《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 + +## 安装secDetector + +1. 配置openEuler yum源:openEuler 发布版本上已默认配置完成yum源,无需额外操作。特殊情况下请参考openEuler官方文档配置在线yum源或通过ISO挂载配置本地yum源。 + +2. 安装secDetector。 + + ```shell + #安装secDetector + sudo yum install secDetector + ``` + +> [!NOTE]说明 +> +> 安装secDetector后在指定目录下可获得部署secDetector所需的相关文件: + +```shell +#secDetector的kerneldriver的核心框架 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_core.ko + +#secDetector的kerneldriver的功能组件 +/lib/modules/%{kernel_version}/extra/secDetector/secDetector_xxx.ko + +#secDetector的守护者进程文件 +/usr/bin/secDetectord + +#secDetector的SDK库文件 +/usr/lib64/secDetector/libsecDetectorsdk.so +/usr/include/secDetector/secDetector_sdk.h +/usr/include/secDetector/secDetector_topic.h +``` + +## 部署 secDetector + +secDetector的主体secDetectord是以系统服务的形式部署在系统中的,前台业务系统可以通过集成SDK来与之通信。由于secDetector的部分能力必须构建在内核之中,因此secDetectord的功能全集还依赖于其后台驱动的部署。 + +### 部署 kernel driver + +1. 插入 kernel driver 的基础框架:secDetector_core.ko 是 kernel driver 的基础框架,要优先于其他内核模块进行部署。找到安装后的 secDetector_core.ko 目录,将其插入内核。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko + ``` + + secDetector_core 支持一个命令行参数ringbuf_size。用户可以通过指定该参数的值来控制 kernel driver 与 用户态secDetectord之间数据通道的缓存空间尺寸。该参数可以被指定为4~1024中的一个整数,单位是MB。默认值是4,必须为2的幂。参考命令如下: + + ```shell + sudo insmod secDetector_core.ko ringbuf_size=128 + ``` + +2. 插入 kernel driver 的功能模块:secDetector的 kernel driver 采用模块化部署方式。用户可以选择基于框架部署满足需要的功能模块,也可以选择部署全部模块。参考命令如下: + + ```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 提供了内核模块列表检测的能力,属于内存修改类探针; + - secDetector_memory_corruption.ko 提供了内存修改检测的能力,属于内存修改类探针; + - secDetector_program_action.ko 提供了程序行为检测的能力,属于程序行为类探针。 + +### 部署 usr driver 和 observer_agent + +当前用户态驱动 usr driver 和服务 observer_agent 已经都被集成到secDetectord中,参考命令如下: + +```shell +sudo ./secDetectord & +``` + +usr driver当前包含了文件操作类探针和进程管理类探针的能力。 + +secDetectord支持如下一些配置选项: + +```text +用法:secDetectord [选项] +secDetectord 默认会在后台运行,从探针中取得数据并转发给订阅者。 +选项: + -d 进入调试模式,进入前台运行,并且在控制台打印探针数据。 + -s 配置eBPF缓冲区大小,单位为Mb,默认为4; size可选范围为4~1024,且必须为2的幂次方。当前拥有2个独立的缓冲区。 + -t 支持配置订阅的事件,默认为所有事件。topic 是位图格式。例如 -t 0x60 同时订阅进程创建和进程退出事件。详细请查阅 include/secDetector_topic.h。 +``` + +### 部署SDK + +SDK的库文件默认已经被部署到系统库目录中,用户需要在自己的程序中引用SDK的头文件即可使用。 diff --git a/docs/zh/2403_lts_sp2/introduction_to_secdetector.md b/docs/zh/2403_lts_sp2/introduction_to_secdetector.md new file mode 100644 index 0000000..1e5dee9 --- /dev/null +++ b/docs/zh/2403_lts_sp2/introduction_to_secdetector.md @@ -0,0 +1,97 @@ +# 认识secDetector + +## 简介 + +secDetector 是专为OS设计的内构入侵检测系统,旨在为关键信息基础设施提供入侵检测及响应能力,为第三方安全工具减少开发成本同时增强检测和响应能力。secDetector 基于ATT&CK攻击模式库建模提供更为丰富的安全事件原语,并且可以提供实时阻断和灵活调整的响应能力。 + +secDetector 作为一套灵活的OS内构入侵检测系统,有三种使用模式: + +1. 直接被系统用户开启用作一些基础异常事件的告警和处置。 +2. 被安全态势感知服务集成,补齐系统信息采集缺陷,用于APT等复杂的安全威胁分析和重点事件布控实时阻断。 +3. 由安全从业人员或安全感知服务提供商二次开发,基于可拓展框架构建精确、高效、及时的入侵检测与响应能力。 + +## 软件架构 + +```text +||==APP===================================================================|| +|| || +|| ---------------------------- || +|| | SDK | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | + | + | +||==OBSERVER========================|=====================================|| +|| | || +|| ---------------------------- || +|| | service | || +|| ---------------------------- || +|| /^\ || +||==================================|=====================================|| + | +||==DRIVER================================================================|| +|| || +|| ---------------------------- || +|| | 8 types of cases | || +|| ---------------------------- || +|| || +||------------------------------------------------------------------------|| +|| core || +|| ------------- ---------------- ---------------- ----------------- || +|| | hook unit | | collect unit | | analyze unit | | response unit | || +|| ------------- ---------------- ---------------- ----------------- || +|| || +||========================================================================|| +``` + +secDetector在架构上分为四个部分:SDK、service、检测特性集合cases、检测框架core。 + +- SDK + + SDK是以一个用户态动态链接库lib的形态承载,被部署到需要使用secDetector入侵检测系统的安全感知业务中。SDK用于和secDetector入侵检测系统的service通讯,完成所需的工作(例如订阅,去订阅,读取现有消息等功能)。secDetector提供的异常信息被定义成不同的case,安全感知业务可以根据自身需求订阅。 + +- service + + service是以一个用户态服务应用的形态承载,向上管理、维护安全感知业务的case订阅信息,向下维护case的运行情况。框架core和检测特性集合case采集到的信息由service统一收集,按需转发给不同的安全感知业务。安全感知业务对于底层检测特性集合case和框架core的配置、管理的需求也由service进行统一的管理和转发。不同的安全感知业务可能会需求同样的case,service会统计出所有安全感知业务需求case的并集,向下层注册。 + +- 特性集合cases + + 检测特性集合cases是一系列异常检测探针,根据异常信息的不同会有不同的形态,比如内核异常信息检测的每个探针会以内核模块ko的形态承载。一个case代表一个探针,一个探针往往是一类异常信息或者一类异常事件的信息。比如进程类探针会关注所有进程的创建、退出、属性修改等事件信息,内存修改类探针会收集内核模块列表和安全开关等信息。因此一个探针可能会包含对多个事件的监控,而这些对不同事件的监控逻辑可能无法部署在同一个执行流当中。我们使用工作流(workflow)的概念表示一个探针在同一个执行流中的工作,一个探针可以包含一个或者多个工作流。比如对于进程探针而言,进程创建检测和进程属性修改检测就是不同的工作流。 + +- 框架core + + 检测框架core是每一个case依赖的基础框架,提供case的管理和workflow所需的通用的基础功能单元。内核异常信息检测框架会以内核模块ko的形态承载。一个检测特性case可以将自己注册到框架中,或者从框架中去注册。框架还可以提供特定的交互接口以满足外部的动态请求。一个workflow被定义为有四类功能单元组成:事件发生器、信息采集器、事件分析器、响应单元。 + +特性集合cases和框架core合起来被称为driver。driver驱动提供了secDetector功能的最底层的系统级实现。 + +driver分为两类,kerneldriver 和 usrdriver。顾名思义,kerneldriver是部署在内核态中的,以内核模块的形式承载。usrdriver是部署在用户态中的,直接被部署为service中的一个模块。从逻辑上usrdriver是在service之下的,但是在运行中,为了降低通信成本,usrdriver被直接集成在service程序中。 + +## 能力特性 + +### 检测能力 + +| 特性 | 状态 | 发布版本 | +| ------------------------------ | ------ | ------------------------------------------------------------ | +| 检测框架 | 已实现 | 统一灵活可拓展高效的检测框架,支持不同类型的触发、收集、分析、响应单元 | +| 进程管理类探针 | 已实现 | 监控进程创建、退出、元数据修改等事件 | +| 文件操作类探针 | 已实现 | 监控文件创建、删除、读写、属性修改等事件 | +| 程序行为类探针(API调用) | 已实现 | 监控匿名管道创建、命令执行、ptrace系统调用等关键程序行为 | +| 内存修改类探针(内核关键数据) | 已实现 | 监控内核模块列表,硬件安全功能开关等内核关键数据 | + +### 响应能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | -------------------------------------------------- | +| 响应框架 | 已实现 | 统一的灵活可拓展的响应框架,支持不同类型的响应单元 | +| 告警上报 | 已实现 | 提供异常信息上报能力的响应单元 | + +### 服务能力 + +| 特性 | 状态 | 说明 | +| -------- | ------ | ------------------------------------------------------------ | +| 通信框架 | 已实现 | 应用程序使用gRPC和service进行通信。功能被封装在SDK的动态库中。 | +| 订阅管理 | 已实现 | 应用程序可以一次订阅,长期使用secDetector获取信息。secDetector会对订阅的应用程序进行管理,分发对应的被订阅主题的信息。 | +| 配置下发 | 已实现 | 服务可以通过参数对于特定的检测、阻断特性进行配置,从而实现过滤、调整等功能。目前未对应用程序开放。 | +| 即时检测 | 已实现 | secDetector提供的信息是实时的,准确的,一手的。 | diff --git a/docs/zh/2403_lts_sp2/secdetector.md b/docs/zh/2403_lts_sp2/secdetector.md new file mode 100644 index 0000000..e20d3fc --- /dev/null +++ b/docs/zh/2403_lts_sp2/secdetector.md @@ -0,0 +1,5 @@ +# secDetector 使用指南 + +本文档介绍 openEuler 操作系统内构入侵检测系统 secDetector 的架构、特性、安装、开发指导、落地应用场景等,帮助用户快速了解并使用 secDetector。 + +本文档适用于使用 openEuler 系统并希望了解和使用 secDetector 的社区开发者、开源爱好者以及相关合作伙伴。使用人员需要具备基本的Linux操作系统知识。 diff --git a/docs/zh/2403_lts_sp2/using_secdetector.md b/docs/zh/2403_lts_sp2/using_secdetector.md new file mode 100644 index 0000000..57d08be --- /dev/null +++ b/docs/zh/2403_lts_sp2/using_secdetector.md @@ -0,0 +1,46 @@ +# 使用 secDetector + +secDetector 提供了SDK,一个so库,用户可以在自己的应用程序中集成该动态链接库从而通过简单的接口使用secDetector。本章介绍其使用方法。 + +## 基本用法 + +用户按照指南《[安装secDetector](./install_secdetector.md)》安装完secDetector之后,libsecDetectorsdk.so、secDetector_sdk.h、secDetector_topic.h就已经被部署到系统用户库默认路径中。 + +1. 使用 C 或 C++ 开发的应用程序确保include路径包含后,可以首先在程序中引用这两个头文件。 + + ```c + #include + #include + ``` + +2. 参考指南《[接口参考](./api_reference.md)》调用SDK提供的接口访问secDetector。 + + 1. 首先调用订阅接口secSub,订阅所需的主题。 + 2. 然后在独立线程中调用消息读取接口secReadFrom阻塞式的读取被订阅主题产生的信息。 + 3. 最后当不需要使用secDetector时,调用退订接口secUnsub。退订时请严格使用订阅时的返回值。 + +## 代码示例 + +可以参考secDetector代码仓上的示例代码,由python语言编写。 + +1. 可以在如下链接中查看示例代码 + + [examples/python · openEuler/secDetector (gitee.com)](https://gitee.com/openeuler/secDetector/tree/master/examples/python) + +2. 也可以下载后参考 + + ```shell + git clone https://gitee.com/openeuler/secDetector.git + ``` + +## 规格与约束 + +1. 部分功能(如内存修改探针-安全开关)依赖硬件体系结构,因此在不同指令集架构上的表现并不相同。 +2. 从内核到用户态传输数据缓存空间为探针共享,缓冲区满会丢弃新采集的事件信息。缓存空间可配置范围为4~1024 MB, 必须为2的幂。 +3. 服务进程secDetectord支持root用户运行,不支持多实例,非第一个运行的程序会退出。 +4. 用户订阅连接数限制为5个。 +5. 用户订阅后,读取消息时需要为消息读取接口提供一块缓冲区,超过缓冲区长度的消息将被截断。建议缓冲区长度不低于4096。 +6. 对于文件名、节点名之类的描述字符串都有一定的长度限制,过长可能会被截断。 +7. 应用程序单进程内不支持并行多连接 secDetectord 接收消息。只能一次订阅,单连接接受消息。去订阅后才能重新订阅。 +8. secDetectord 进程应当等待所有应用程序的连接中断即完全退订所有主题后,才可以关闭退出。 +9. 部分功能(如内存修改探针-安全开关)基于当前CPU状态。因此检测的基本功能是可以检测到当前CPU上的状态变化,其他CPU上的状态变化如果未能及时同步到当前CPU,则不会被检测到。 -- Gitee