NetEye Security Layer

NetEye Security Layer

概述

NetEye Security Layer，简称NS Layer，是nginx中新增加的一个框架，用于组织和安排模块。
NS Layer在nginx中增加了一个phase用于处理request包，一个header filter和一个body filter用于处理response包。各个模块可以根据需要在NS Layer上注册自己的回调函数。
NS Layer提供了一种控制模块建流程的机制，可以实现在不同的模块之间任意跳转。
NS Layer提供了统一处理动作的方法，即基于NS Layer的安全模块，在检测出攻击需要执行动作时，由NS Layer统一处理。

基于NS Layer开发安全模块

接口说明

#include 
 
 
ngx_int_t ngx_http_neteye_security_request_register(ngx_int_t id, ngx_http_neteye_security_request_pt handler);
 
说明：  此函数用于向NS Layer注册一个request回调函数，注册的函数会在neteye security layer phase被调用
参数：  id: 当前模块在NS Layer中的模块id
       handler: 当前模块的request回调函数
返回值： 成功返回NGX_OK，失败返回NGX_ERROR
 
 
ngx_int_t ngx_http_neteye_security_header_register(ngx_int_t id, ngx_http_neteye_security_response_header_pt handler);
 
说明：  此函数用于向NS Layer注册一个header filter回调函数，注册的函数会在header filter链上被调用
参数：  id: 当前模块在NS Layer中的模块id
       handler: 当前模块的header filter回调函数
返回值： 成功返回NGX_OK，失败返回NGX_ERROR
 
 
ngx_int_t ngx_http_neteye_security_body_register(ngx_int_t id, ngx_http_neteye_security_response_body_pt handler);
 
说明：  此函数用于向NS Layer注册一个body filter回调函数，注册的函数会在body filter链上被调用
参数：  id: 当前模块在NS Layer中的模块id
       handler: 当前模块的body filter回调函数
返回值： 成功返回NGX_OK，失败返回NGX_ERROR
 
 
ngx_int_t ngx_http_ns_do_action(ngx_http_request_t *r, ngx_http_ns_action_t *action);
 
说明：  此函数处理基于NS Layer的模块实现动作的需求，填写正确的action结构体后，NS Layer会按照模块的要求来执行特定的动作。
参数：  r: 需要处理的http request
       action: 当前模块填写的action结构体
返回值： 放行返回NGX_OK，阻断返回NGX_ERROR
 
 
ngx_int_t ngx_http_neteye_security_ctx_register(ngx_int_t id, ngx_http_neteye_security_ctx_pt handler);
 
说明：  此函数用于注册创建ctx的回调函数，NS Layer的ctx用于存储共享数据以便被处理流畅上的多个不同的环节使用
参数：  id: 当前模块在NS Layer中的模块id
       handler: 当前模块的创建ctx的回调函数
返回值： 成功返回NGX_OK，失败返回NGX_ERROR
 
 
void ngx_http_ns_jump_bit_set(ngx_http_request_t *r, ngx_uint_t mod);
void ngx_http_ns_jump_bit_clr(ngx_http_request_t *r, ngx_uint_t mod);
void ngx_http_ns_jump_bit_clr_all(ngx_http_request_t *r);
ngx_uint_t ngx_http_ns_jump_bit_is_set(ngx_http_request_t *r, ngx_uint_t mod);
void ngx_http_ns_jump_bit_set_all(ngx_http_request_t *r);
ngx_uint_t ngx_http_ns_jump_bit_is_set_any(ngx_http_request_t *r);
void ngx_http_ns_set_bypass_all(ngx_http_request_t *r);
void ngx_http_ns_clr_bypass_all(ngx_http_request_t *r);
ngx_uint_t ngx_http_ns_test_bypass_all(ngx_http_request_t *r);
 
说明：  以上几个函数用于设置基于NS Layer的模块的执行流程，例如可以设置哪些模块被跳过
参数：  r: 需要处理的http request
       mod: 需要设置的模块id
返回值： 成功返回NGX_OK，失败返回NGX_ERROR

使用方法

以robot mitigation模块举例说明如果编写基于NS Layer的模块

1) 向NS Layer增加模块信息

首先，先向3rd_party/ngx_http_neteye_security/ngx_http_neteye_security.h中增加模块ID，需要修改如下枚举变量：

enum ngx_http_neteye_security_module_ids {
    NGX_HTTP_NETEYE_SECURITY_MODULE_START = 0,
 
    NGX_HTTP_NETEYE_WHITELIST,
    NGX_HTTP_NETEYE_FRIENDLY_BOTSLIST,
    NGX_HTTP_NETEYE_SESSION,
    NGX_HTTP_NETEYE_DYNWHITELIST,
    NGX_HTTP_NETEYE_ROBOT_MITIGATION,
    NGX_HTTP_NETEYE_GOOGLE_RECAPTCHA,
    NGX_HTTP_NETEYE_LOCAL_CAPTCHA,
    NGX_HTTP_NETEYE_COOKIE_POISON,
    NGX_HTTP_NETEYE_PAGE_ACL,
    NGX_HTTP_NETEYE_NAXSI,
    NGX_HTTP_NETEYE_IPS,
    NGX_HTTP_NETEYE_STATUS_PAGE,
    NGX_HTTP_NETEYE_LOG_MODULE,
 
    NGX_HTTP_NETEYE_SECURITY_MODULE_MAX
};

例如在此枚举变量中加上NGX_HTTP_NETEYE_ROBOT_MITIGATION

然后在3rd_party/ngx_http_neteye_security/ngx_http_neteye_security.c中增加对模块的定义：

/*XXX: do not insert gap among the rank values */
static ngx_http_neteye_security_module_t ngx_http_neteye_security_modules[] = {
    {NGX_HTTP_NETEYE_WHITELIST,
        "Permanent IP Whitelist", NULL, NULL, NULL, 1, 0, 0, NULL},
    {NGX_HTTP_NETEYE_SESSION,
        "Session Mechanism", NULL, NULL, NULL,      2, 1, 0, NULL},
    {NGX_HTTP_NETEYE_DYNWHITELIST,
        "Dynamic White list", NULL, NULL,NULL,      3, 0, 0, NULL},
    {NGX_HTTP_NETEYE_FRIENDLY_BOTSLIST,
        "Friendly Bots list", NULL, NULL, NULL,     4, 0, 0, NULL},
    {NGX_HTTP_NETEYE_ROBOT_MITIGATION,
        "Active/Challenge", NULL, NULL, NULL,       5, 0, 0, NULL},
    {NGX_HTTP_NETEYE_GOOGLE_RECAPTCHA,
        "Google Recaptcha", NULL, NULL, NULL,       6, 0, 0, NULL},
    {NGX_HTTP_NETEYE_LOCAL_CAPTCHA,
        "Local Captcha", NULL, NULL, NULL,          7, 0, 0, NULL},
    {NGX_HTTP_NETEYE_COOKIE_POISON,
        "Cookie Poison", NULL, NULL, NULL,          8, 3, 0, NULL},
    {NGX_HTTP_NETEYE_PAGE_ACL,
        "Page Access Control", NULL, NULL, NULL,    9, 0, 0, NULL},
    {NGX_HTTP_NETEYE_NAXSI,
        "NetEye modified NAXSI", NULL, NULL, NULL,    10, 0, 0, NULL},
    {NGX_HTTP_NETEYE_IPS,
        "NetEye IPS Module", NULL, NULL, NULL,      0, 2, 1, NULL},
    {NGX_HTTP_NETEYE_STATUS_PAGE,
        "Status Page", NULL, NULL, NULL,            0, 4, 0, NULL},
    {NGX_HTTP_NETEYE_LOG_MODULE,
        "NetEye Log", NULL, NULL, NULL,             0, 0, 0, NULL},
};

在此数组中添加新的一行，此行由如下部分组成：

1. 模块名称，就是上一步在枚举变量中定义的值
2. 模块的字符串名称
3. 三个回调函数，此处留空即可，因为这些函数需要在模块初始化时进行注册
4. 接下来3列是此模块在request, header filter和body filter阶段的调用顺序，如果此模块不需要出现在某个环节，则设置为0
5. 最后一列是ctx的初始化函数，留空，这个函数也需要在模块初始化时进行注册

例如robot mitigation模块的定义为：

{NGX_HTTP_NETEYE_ROBOT_MITIGATION, "Active/Challenge", NULL, NULL, NULL, 5, 0, 0, NULL},

意思就是此模块只需要提供一个request handler，排位第五

2) 在上述文件中增加模块的定义信息之后，就可以在新模块的代码中注册回调函数：

在模块的结构体中定义postconfiguration函数：

static ngx_http_module_t                                                                                                
ngx_http_robot_mitigation_module_ctx = {                                                                                
    NULL,                                    /* preconfiguration */                                                    
    ngx_http_rm_init,                        /* postconfiguration */                                                   
                                                                                                                         
    NULL,                                    /* create main configuration */                                           
    NULL,                                    /* init main configuration */                                             
                                                                                                                         
    NULL,                                    /* create server configuration */                                         
    NULL,                                    /* merge server configuration */                                          
                                                                                                                         
    ngx_http_rm_create_loc_conf,             /* create location configuration */                                       
    ngx_http_rm_merge_loc_conf,              /* merge location configuration */                                        
};

然后在此postconfiguration函数中初始化相关的NS Layer回调函数：

static ngx_int_t ngx_http_rm_init(ngx_conf_t *cf)
{
    ngx_int_t ret;
    ret = ngx_http_neteye_security_ctx_register(NGX_HTTP_NETEYE_ROBOT_MITIGATION,
            ngx_http_rm_request_ctx_init);
    if (ret != NGX_OK) {
        return ret;
    }
    /* we only need a request handler for this feature */
    return ngx_http_neteye_security_request_register(
            NGX_HTTP_NETEYE_ROBOT_MITIGATION,
            ngx_http_rm_request_handler);
}

3) 实现模块的各种函数，模板本身的编写需要符合nginx模块的要求，但不需要注册成nginx的filter模块，而是应当注册成普通的http模块，下面是robot mitigation模块的config文件：

ngx_addon_name=ngx_http_robot_mitigation_module
CORE_INCS="$CORE_INCS $ngx_addon_dir"
CORE_DEPS="$CORE_DEPS $ngx_addon_dir/ngx_http_robot_mitigation.h"
HTTP_MODULES="$HTTP_MODULES ngx_http_robot_mitigation_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_robot_mitigation.c $ngx_addon_dir/ngx_http_robot_mitigation_tpl.c"
have=NGX_HTTP_ROBOT_MITIGATION_MODULE . auto/have