开发插件

本节介绍如何开发并发布一个 JavaScript 检测插件。

开发环境准备

1. 下载并安装 NodeJS，Ubuntu 系统可使用 sudo apt-get install -y nodejs 命令进行安装

2. 安装插件开发工具 openraspjs:

npm install -g openrasp

编写第一个插件

检测插件针对应用的行为进行检测，当应用执行数据库查询、文件读写等操作，OpenRASP 引擎就会调用检测插件，并将相关参数一并传递过来。一个最小的SQL检测插件如下所示:

const plugin_version = '2018-1000-1000'
const plugin_name    = 'test-plugin'

'use strict'
var plugin  = new RASP(plugin_name)

const clean = {
    action:     'ignore',
    message:    'Looks fine to me',
    confidence: 0
}

// BEGIN ALGORITHM CONFIG //

var algorithmConfig = {}

// END ALGORITHM CONFIG //

plugin.register('sql', function (params, context) {
    plugin.log('SQL query: ' + params.query)
    return clean
})

plugin.log('plugin-demo: plugin loaded')

首先，我们调用 plugin.register 注册了SQL查询的检测函数，并将SQL语句打印到插件日志。其中，

• params 为检查点提供的参数，如SQL语句、要读取的文件等等

• context 为请求信息，如请求参数，服务器信息等等

然后，我们在回调函数里，调用 plugin.log 打印了SQL查询语句

最后，我们在回调函数里，返回检测结果，即 "放行"

目前我们支持14个检测点，具体请看 参数说明 文档。

调用插件接口

我们在 RASP 类里提供了一些接口，可以直接在插件里调用。比如，你可以调用 RASP.sql_tokenize 将SQL语句转化为 token:

plugin.register('sql', function (params, context) {
    plugin.log('SQL tokens ', RASP.sql_tokenize(params.query, params.server))
    return clean
})

详细 JS API 说明请看 接口说明 文档。

测试检测插件

现在，我们已经完成了检测插件，下一步是进行测试。测试有两种方法:

1. 参考 单元测试，编写JSON测试用例并使用 openraspjs 进行测试
2. 参考 安装插件，将插件放到安装了 OpenRASP 的应用服务器进行测试

若你是初次接触插件开发，我们推荐使用第二种方式，即使用 OpenRASP 单机版调试。具体调试方法请参考上述文档，这里不再赘述。

拦截危险操作

现在，我们已经能够编写检测插件，并在客户端运行。接下来就是拦截攻击了，在回调函数里，将返回的 action 字段改为 block 即可拦截请求。比如，当SQL语句包含union注入特征，我们想拦截整个请求的话，可以这样写:

plugin.register('sql', function (params, context) {
    plugin.log('SQL tokens ', RASP.sql_tokenize(params.query, params.server))
    
    if (/union.*select.*from.*information_schema/.test(params.query)) {
        return {
            action:     'block',
            message:    '拦截SQL查询，因为XXX',
            confidence: 90
        }
    }
    
    return clean
})

在官方插件里，实际的检测算法要复杂的很多，有兴趣可以参考 official.js 的实现。如果不想拦截攻击，只是想记录攻击日志，可将 action 字段设置为 log。

最后， confidence 字段用来标记报警的可信度，官方插件的范围是 90~100，越高报警的可靠性越高。

注意: 当某个插件拦截了攻击，其他插件将不在被调用。

FAQ

1. 插件支持 ES6 语法吗？{#faq-1}

• 插件环境可能不支持某些最新的 JavaScript 语法，请使用 openrasjs 进行语法检查

• 插件不能使用与平台相关的全局对象，只能使用 JavaScript 标准内建对象
• 插件可以像编写 Node.js 程序一样引入其他模块，然后通过 webpack 或 browserify 等工具打包成一个文件，但是注意不能引入与平台相关的模块，例如: Node.js 的 http 模块

2. 如果检测点没有返回对象，或者返回的对象不合法，会怎么样？{#faq-2}

• 若检查点没有返回对象，等于 ignore

• 若检查点返回了对象，但 action 值不存在或者不为 block/log/ignore 之一，等价于 log