1 of 67

OpenRASP Documents (Old)

简介

OpenRASP 抛弃了传统防火墙依赖请求特征检测攻击的模式，创造性的使用RASP技术（应用运行时自我保护），直接注入到被保护应用的服务中提供函数级别的实时防护，可以在不更新策略以及不升级被保护应用代码的情况下检测/防护未知漏洞，尤其适合大量使用开源组件的互联网应用以及使用第三方集成商开发的金融类应用。

另外，OpenRASP 提供的IAST解决方案，相比于与传统的DAST方案有着革命性提升。漏洞检测无需动态爬虫或者旁路代理，扫描更全面；结合应用探针准确的识别漏洞类型，通过针对性扫描大幅度提升检测效率；商业版新增的动态污点追踪能力，还可以在不扫描的情况下，预判接口是否存在漏洞。

OpenRASP 是经过开源社区大规模验证过的产品，目前客户数量已经过百，QQ群人数超过1800人。如果你在使用过程中遇到任何问题，请加入我们的技术讨论QQ群，联系我们处理。

常用链接

安装部署

检测能力

安装部署

目前，OpenRASP 支持 Java 和 PHP 两种开发语言。更多语言支持计划，请查看 baidu/openrasp - 里程碑。具体开发排期和版本内容，请关注我们置顶的 baidu/openrasp - ISSUE 页面。

兼容性说明

Java Agent

操作系统

MacOS 10.10+
Windows x64
Linux
- RHEL/CentOS 6 以及更高版本
- Ubuntu 14 以及更高版本
- Debian 6 以及更高版本

Web 服务器 - 支持 docker 部署

Tomcat 5 ~ 10
Jetty 7 ~ 9
JBoss 4 ~ 8
Wildfly 8 ~ 16

JDK 版本

Oracle JDK 6~15
OpenJDK 6~11

数据库

MySQL
SQLServer
SQLite3
Oracle

PHP Agent

SAPI 支持范围（同时支持TS/非TS版本）

PHP-FPM
Apache PHP 模块

操作系统

Linux

PHP 5.3 ~ 5.6，7.0 ~ 7.3
- Ubuntu 14.04 以及更高版本
- RHELL/CentOS 6 以及更高版本

Mac OS

Homebrew PHP 5.6，7.0 ~ 7.3 (没有深入测试)

数据库

MySQL (mysql/mysqli/PDO 等连接方式)
PostgreSQL
SQLite3

管理后台

操作系统

Linux
- CentOS 6 以及更高版本
- Ubuntu 14.04 以及更高版本

安装管理后台

快速开始

在开始之前，请先根据软件下载里的说明，下载 rasp-cloud.tar.gz，并解压缩到本地。

安装数据库

目前，我们使用了和两种数据库。前者用来存储报警和统计信息，后者用来存储应用、账号密码等信息。

目前我们对数据库的要求是，

MongoDB 版本大于等于 3.6
ElasticSearch 版本大于等于 5.6，小于 7.0 (ES 7.X 变化较大，暂无计划支持)

具体如何安装数据库，这里不在赘述。

启动管理后台

首先，编辑 conf/app.conf 文件，修正 ElasticSearch 和 MongoDB 两个服务器的地址。如果这两个数据库都安装在了本机，且使用默认端口，请跳过此步骤:

关于 MongoDB 认证配置，可参考文章操作；如果 MongoDB 有主从，只需要填写主地址。

然后，在终端里执行如下命令，启动后台服务器:

最后，在浏览器里打开 http://your-ip:8086，登录管理后台。其中用户名固定为 openrasp，初始密码为 admin@123。如果不能访问，请检查防火墙设置，或者检查 logs/api/agent-cloud.log 下面的错误信息。

登录成功后，请根据文档，了解如何添加第一台主机。

高级配置

后台负载均衡

在实际场景中，我们需要部署多个服务器，才能处理来自数十万主机的连接。因此，我们将管理后台拆分为 Agent 接口服务器 (AgentServer) 和 前端服务器 (PanelServer)。前者用于跟agent通信，比如心跳、日志上传，可以部署多个；后者用于展示数据、定时报警、修改配置，用户可访问这个后台来查看报警。后者用于发送报警邮件，部署多个会有重复报警的问题，所以目前只能部署一个。

在百度，我们会启动一个前端服务器，

然后在不同的机房，分别启动一个 agent 服务器（使用同一份 conf/app.conf 配置文件即可）

服务器部署完成后，请根据文档，将所有的Agent服务器填入。之后就可以在 添加主机 界面上，生成自动安装命令了。

容量说明: 目前，在2核4GB的主机上，按照3分钟一个心跳计算，大概单台机器可容纳 1000个 客户端。

ElasticSearch 负载均衡

在使用ES集群时，EsAddr 填写一个服务器的地址即可。我们自动会调用 /_nodes/ 接口获取全部服务器信息并轮询，以避免单点问题。

配置项详细说明

以下配置均为在 conf/app.conf 中配置

Beego 相关

常用 beego 配置项如下，更多设置请参考文档，

参数

说明

默认值

OpenRASP 相关

OpenRASP 可用配置项目如下，

参数

说明

默认值

开启 HTTPS

在 conf/app.conf 中加入以下配置即可，修改后重启后台生效:

后台运维

升级后台

请登录到每一台部署了 rasp-cloud 的主机，并按照如下步骤进行升级:

如果是 v1.3.0 之前的后台

备份原来的配置文件，conf/app.conf
下载新的安装包，解压缩到相同目录
检查是否需要更新配置文件

如果是 v1.3.0 甚至更高版本的后台

备份原来的配置文件，conf/app.conf
下载新的安装包，解压缩到相同目录
检查是否需要更新配置文件

找回密码

请登录到后台所在的主机，执行如下命令，根据提示重置密码。目前密码强度要求是 8-50 位，必须包含数字和字母。

检查后台状态

请登录到后台所在的主机，执行如下命令即可:

查看后台版本

请登录到后台所在的主机，执行如下命令即可:

定期备份

在百度，我们以小时级别对 MongoDB 和 ElasticSearch 数据库进行备份。其中，MongoDB 需要备份 openrasp 数据库，可以使用 mongodump + mongorestore 实现；ElasticSearch 需要备份如下索引，可以用 snapshot 方式备份:

当然，如果公司有DBA团队，可以考虑托管给他们。

其他说明

Logstash 配置

当 AlarmLogMode 设置为 file 时，可使用 Logstash 采集文件日志。Logstash 样例配置如下，使用前请先修正日志路径

FAQ

1. 常见启动失败原因

日志会打印到 logs/api/agent-cloud.log 里。如果启动时没有增加 -d 参数，我们将同时在前台打印错误消息，e.g

目前定义的错误如下，

具体错误信息请查看 nohup 控制台输出

2. 管理后台打开后空白、按钮点不动等问题

我们目前只兼容 Google Chrome 浏览器。如果页面出现任何问题，请按下 F12 调出开发工具，并检查控制台是否有错误输出。如下图中的红色字样:

如果发现这种问题，请加入QQ群联系我们处理。

3. ElasticSearch "Result window is too large" 错误

如果你搜索的时间范围太大，ES 可能会爆出如下错误:

Result window is too large, from + size must be less than or equal to: [10000] but was [281280]. See the scroll api for a more efficient way to request large data sets. This limit can be set by changing the [index.max_result_window] index level setting.

这是因为你搜索的时间范围很大，导致ES需要对大量的数据进行排序。解决方法是打开 config/elasticsearch.yml，修改或者增加 index.max_result_window 配置，将它调整为一个较大的值。当然，修改这个值会消耗更多的内存。

4. 我的主机名显示为 "im-not-resolvable"

在 Java 版本里，我们使用了 InetAddress 来获取主机名称，如果这个主机名在 /etc/hosts 下面没有对应的记录，Java 将抛出 Unknown host 异常。在这种情况下，我们会将主机名设置为 im-not-resolvable，并让程序继续运行。

解决方法是，在 /etc/hosts 下面为你的主机名添加一条记录:

添加后，重启 Java 服务器生效。再次启动时，我们会注册一个新的agent到后台。

5. 管理后台打不开，Chrome 浏览器提示 ERR_CONNECTION_REFUSED

默认情况下，后台监听地址为 0.0.0.0:8086。如果你无法访问服务器，请检查防火墙是否开启对应端口。对于基于 netfilter 的防火墙，你可以执行如下命令开放 8086 端口:

6. 无法发送邮件报警，提示 5XX 错误

大部分国内邮箱都不支持密码登录，需要申请授权码进行登录。如果你在使用下列邮箱，请参考他们的 FAQ 文档进行配置:

Coremail - 请联系销售

7. ElasticSearch X-Pack 使用说明

目前，后台使用的索引名称前缀为:

real-openrasp-X (alias)
openrasp-X

如果你在使用 X-Pack，且需要按照索引名称前缀进行授权，可以根据上述规则添加认证。若要查看当前 ES 的索引和别名列表，可访问如下URL:

8. 自己编译的后台，访问前端服务器 8086 端口提示 404 错误

前端文件在 dist 目录下，如果前端服务器返回 404 则说明这个目录不存在，或者 dist/index.html 不存在。

9. 误删ES索引，如何处理？{#es-index-reset}

ES索引里只保存报警信息，误删索引不会导致agent信息丢失。若要完全重置ES，请先删除所有以 real-openrasp-、openrasp- 开头的索引，并重新启动 rasp-cloud 即可。rasp-cloud 会在启动时检查并重新创建索引。

10. 报警上传成功，后台看不到报警而且 ES 健康状态为 yello

为了避免阻塞，管理后台是异步将报警日志写入 ElasticSearch，因此 API 接口成功不代表报警保存成功。当 ES 服务器磁盘空间占用超过 95%，ES 会拒绝接受日志并抛出 cluster_block_exception 异常:

修复方式请参考文章解决。

11. 我使用 nginx 作为管理后台的反向代理，iast 扫描器无法连接，总是提示400错误

iast 扫描器使用 websocket upgrade 协议连接管理后台，nginx 需要同时传递 Upgrade 头才能工作:

否则会在管理后台 api/agent-cloud.log 看到如下错误

12. 管理后台假死，日志里出现大量 too many open files

参考修正 limits.conf 里的配置即可，修正后需要重新登录生效。

最后通过 ulimits -n 命令确认即可。

13. 离线主机排查

如果后台出现离线主机，请按照如下步骤排查:

检查客户端与后台是否连通。使用 curl 命令访问管理后台，检查是否能访问。
重启 Tomcat/PHP 服务器，检查主机是否上线。
检查客户端主机名、网卡信息是否有变化。如果有，后台信息会跟着变更，并产生一台新的主机。这个问题会在后续版本修正，即固定 rasp_id 到配置目录。

14. rasp-cloud 启动卡住

目前已知的情况有

beego自身存在BUG，如果日志目录被链接到 /dev/null，将会卡住。e.g log/access 目录

快速接入

OpenRASP 支持私有化部署，包含客户端与服务端两个组件。在接入之前，请先阅读兼容性说明文档，检查客户端是否支持你的应用服务。

第一步: 下载最新版本的安装包

常用镜像

文件说明

文件名

说明

第二步: 安装管理后台（可选）

OpenRASP 支持单机防护，也支持远程管理。若要开启远程管理，请先参考安装管理后台。

第三步: 安装客户端

取决于你的服务器类型，请参考不同的子章节进行安装。比如 Tomcat 可以查看进行操作。

第四步: 安装测试用例（可选）{#step4}

如果你需要测试漏洞检测效果，请参考安装漏洞环境。

第五步: 安装IAST扫描工具（可选）{#step5}

如果你需要安装扫描工具，请参考页面进行安装和配置。

其他常用链接

开发相关

常见问题

1. 常见自动安装失败原因

Java 版本

错误码

说明

关于 java 不重启安装，卸载：由于不支持不重启升级，所以在不重启安装然后不重启卸载之后，想要再次安装需要重启服务器安装。

PHP 版本

错误码

分类说明

2. OpenRASP 无法拦截攻击

Java 服务器

首先，使用浏览器访问网站，检查服务器是否启动成功
- 若服务器没有启动，可检查启动日志，寻找堆栈信息。对于 tomcat 通常是 catalina.out
根据子章节的文档，检查 OpenRASP 是否安装成功

PHP 服务器

首先，使用浏览器访问网站，检查服务器是否启动成功
- 若服务器没有启动，可检查 PHP/Apache/Nginx 错误日志
根据子章节的文章，检查 OpenRASP 扩展是否安装成功

3. jnotify 无法释放

有的公司会定制应用启动脚本，比如 catalina.sh，当以root启动tomcat，他会自动切换到低权限用户，再继续启动

通常，你会看到如下的堆栈错误

这说明 OpenRASP 在释放 jnotify 动态链接库时出错（用来监控插件目录变更），错误原因是 Permission denied

所以，你可能需要调整下RASP目录权限，e.g chmod 777 -R rasp，然后再次启动 tomcat

4. Could not find or load main class com.baidu.rasp.App 错误

QQ群用户反馈，执行 RaspInstall 时报错，

经过排查，这是因为当前目录本身没有读取权限导致的，执行 chmod 777 $PWD 后解决。

5. APM 兼容性说明

如果你同时使用 OpenRASP 和 APM 产品，比如，那你需要增大 -XX:MaxPermSize 参数。否则运行一段时间后可能会出现 java.lang.OutOfMemoryError: PermGen space 错误，产生大量GC，最终导致服务器假死。

如果原先没有配置过此参数，我们建议你设置为 1024m；如果配置过，我们建议在原先基础上增加至少 512m。

另外，为了避免APM回滚钩子，请将我们的 -javaagent 参数放在前面。

6. JDK9 以上安装问题

由于JDK9以上版本的 Modularity System 属性，需要在手动安装后为服务器添加以下 Java 启动参数:

7. 常见 v8 加载失败原因

7.1 java.io.IOException: Permission denied 异常

如果 /tmp 目录没有写权限，Java 会抛出 java.io.IOException: Permission denied 异常，e.g

此时请检查 /tmp 是否有写权限，以及是否有安全防护软件对 /tmp 目录增加了写保护。

7.2 libopenrasp_v8_java.so: failed to map segment from shared object: Permission denied

对于以下两种场景，

机器开启了SELinux，不允许Tomcat加载不符合策略的动态链接库
so释放目录没有执行权限，比如使用了 noexec 参数挂载

Java可能会出现无法加载so的情况，并提示无法创建区段映射:

解决方法是关闭SELinux(如果开启)，并去掉释放目录的noexec挂载(如果有)。如果不是上述两种情况，请加入QQ群联系我们排查。

7.3 java.io.IOException: Couldn't load library openrasp_v8_java

如果你在不支持的系统架构上运行OpenRASP(比如aarch64)，可能会看到 Couldn't find resource 错误:

目前我们仅支持x64/x86_64两类架构，其他架构会逐步支持

7.4 java.lang.UnsatisfiedLinkError 错误

如果释放的 libopenrasp_v8_java.so 无法加载，Java 会抛出如下异常:

目前已知的情况有:

JDK是32位的，没有安装32位的glibc运行库。在CentOS系统下可以安装 glibc.i686 软件包。
JDK是64位的，且在 docker alpine 环境里无法启动。这个因为你没有装 libcurl libstdc++ 两个软件包。

如果是其他情况，请加入联系我们。

8. libzip.so 崩溃问题

Java 在运行时可能会产生这个错误:

OpenRASP会定期读取jar包里的pom信息，获取应用所使用的类库和版本。这个是JDK自身的BUG，与OpenRASP无关。你可以通过如下几种方式解决问题:

方案1: 升级JDK版本

根据用户反馈，JDK 1.8 Update 261 没有这个问题。

方案2: 关掉jar包的内存映射

这可能因为Java在读取jar包时，对应的文件已经被修改，导致JVM崩溃，具体可以参考。

通过增加如下JVM启动参数可以解决问题，但可能带来额外的性能损耗:

方案3: 关闭依赖库采集功能

参考文档，将 dependency_check.enable 设置为 false 即可。另外，也可以在执行RaspInstall安装的时候增加 -nodep 参数，程序会自动将 dependency_check.enable 改为 false。

方案4: 避免多个Java进程使用相同的业务jar包

有用户反馈，他们的业务存在多个容器共用jar的问题，将jar打包到容器内部就没有这个错误了。

PHP 服务器

OpenRASP 依赖于如下几个扩展。如果你在使用发行版自带的 PHP 环境，可以使用 yum、apt-get 等工具安装下这些扩展；如果是自己编译的 PHP 环境，则需要在编译阶段开启这些功能。

pdo
pcre
json

对于服务器环境和操作系统的支持情况，可查看，目前 5.3 - 7.3 都是支持的。

自动化安装

下载 rasp-php-linux.tar.bz2 或者 rasp-php-linux-ts.tar.bz2（线程安全版本） 并解压缩。之后进入到解压后的目录中，e.g rasp-php-20180320

如果你要开启远程管理，请先参考文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -d 参数，

其中 /opt/rasp 为 OpenRASP 安装目录，用于存储检测插件、报警日志等等，可根据实际情况调整。在某些情况下，php cli 和 php-fpm 使用的 ini 不同，自动安装程序可能会失败。

升级 PHP Agent

首先，备份老的扩展，e.g

然后，安装新的扩展，e.g

最后，通过 graceful reload 方式重新加载服务。

针对不同的服务器类型，你需要执行不同的命令，e.g

需要注意的是，请不要直接覆盖 openrasp.so，否则会产生意想不到的内存错误。我们建议使用 重命名方式 来安装新版，以避免出现问题。

手动安装 - Linux

1. 确认基本信息

在 web 目录下面，我们建立一个 info.php，并填写如下内容

在浏览器里打开这个页面，使用搜索功能，

定位到 extension_dir 字样，确认PHP扩展安装目录
- e.g /usr/lib/php/20151012
搜索 Additional .ini files parsed 字样，

2. 安装软件

首先，根据你的 PHP 版本号，复制正确的 openrasp.so 到扩展目录，e.g

然后，确定 OpenRASP 安装目录，在这里我们使用 /opt/rasp

这个目录将会用于存储检测插件、报警日志、插件日志等内容，需要手动创建，并保证 PHP 进程可以写入，e.g

由于报警日志存储在 /opt/rasp/logs，我们建议挑选一个空间较大的分区，以避免将根分区打满

最后，修改 php.ini，或者创建 z-openrasp.ini 文件，添加如下内容:

其中，openrasp.root_dir 表示刚才选择的 OpenRASP 安装目录，不填写则无法加载。对于其他配置参数，可参考文档进行调整。

3. 安装检测插件

点击这里下载官方插件，并放置到 <openrasp.root_dir>/plugins/ 目录，下载后自动加载并生效。

4. 验证安装是否成功

访问刚才创建的 info.php，检查 openrasp 模块是否加载成功即可，e.g

如果你没有看到类似的信息，则说明扩展加载失败。常见原因有

PHP版本和扩展版本不一致，比如 PHP 是 5.3 版本，但你安装了 PHP 5.6 版本的 openrasp.so
INI 配置不正确，请参考 php error.log 里的错误消息
- 所有的错误消息都以 [OpenRASP] 错误码 开头，方便和其他日志进行区分

确认安装成功后，请删除 info.php 这个文件，以避免泄露敏感信息。

手动安装 - MacOS

我们只支持 Homebrew PHP 5.6 版本，安装过程同 Linux 系统，aka

复制 dylib 文件到 PHP 扩展目录
修改 INI 配置文件
重启 php-fpm 生效

另外，MacOS 版本不支持远程管理。

FAQ

1. include/require hook 点未生效

OpenRASP 扩展跟 xdebug 模块存在冲突，若同时开启了 xdebug 模块，请先禁用它

2. 单机版 php-fpm 模式下，插件目录的文件监控功能，有时会失效

在 openrasp 扩展初始化时，我们创建了文件监控线程，用于插件目录的监控。当我们发现插件目录发生变化，就会通过发送 USR2 信号的方式，通知 php-fpm master process 去重新加载子进程，即 gracefully reload。

然而，如果你在启动 php-fpm 的时候，没有使用 -F 参数，则意味着 php-fpm 会主动 fork() 到后台。此时，我们创建的文件监控线程就会失效，也就无法监控插件目录了。

解决方法就是使用 php-fpm -F 这样的方式启动PHP服务器。当然，如果你使用发行版自带的 php-fpm，通常都是这样启动的，无需担心。

3. OpenRASP正常拦截攻击，但是alarm.log没有日志

默认情况下，OpenRASP会被安装到/opt/rasp，以下用<openrasp.root_dir>代替。你需要检查<openrasp.root_dir>/rasp/logs目录是否存在，以及是否有写权限。

常见没有权限的原因有:

使用了root账号安装OpenRASP，而应用使用低权限账号运行(比如nobody)。
1. 可以执行chmod 777 -R <openrasp.root_dir>/logs增加权限
2. 也可以使用chmod修改上述目录的属主(更加安全)

4. CentOS 7.4 apache 使用 systemd 启动会崩溃的问题

systemd 会限制应用栈的大小，导致 openrasp 无法启动。你通过修改 /usr/lib/systemd/system/httpd.service，并提高 LimitStack 的值来解决问题。经过测试，我们发现将栈大小限制改为 16MB 可以解决问题，对应的配置为:

当然，直接使用命令行启动 apache 是没有这个问题的，因为他会继承系统默认的 limit 配置，即 unlimited。

5. php_json_encode 未定义错误

OpenRASP 依赖于多个PHP扩展，json、pdo、pcre 等等。由于 PHP 不会严格按照依赖顺序去加载扩展，所以当 openrasp 先于 json 加载，就会产生这个错误，e.g

解决方法就是让 openrasp 扩展最后加载。常见的做法是调整配置文件的权重，比如将 openrasp 配置文件改为 /etc/php.d/z-openrasp.ini，这样 json 配置文件就会先于 openrasp 配置文件加载，就解决了扩展依赖的问题。

6. 无法检测到 web 目录下的敏感文件？{#faq-webdir-scan}

当PHP服务器处理过至少一次请求后，我们才能够检测到 webroot，之后才会启动敏感目录检测功能。为了保证性能，该检测点具有如下限制:

只会检测根目录，子目录不会处理
最多在内存里缓存 256 个不同的 webroot 路径，超过这个限制时，只保留已有的路径

7. alphine 环境无法启动，提示找不到 ld-linux-x86-64.so.2

根据QQ群用户反馈，增加软连接可以解决问题:

8. 如何判断PHP是否为线程安全版本

执行如下命令，如果返回 bool(true) 则是线程安全(TS)版本

当然也可以编写PHP脚本来测试，如果页面返回 bool(true) 则是线程安全(TS)版本

Tomcat 服务器

自动化安装

下载 rasp-java.tar.gz 或者 rasp-java.zip 并解压缩。之后进入到解压后的目录中，e.g rasp-20181221

如果你要开启远程管理，请先参考管理后台 - 添加主机文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -install 参数，

这里的 <tomcat_root> 不是 webapps 目录，而是 tomcat 的根目录。没有错误表示安装成功，其他配置请参考文档。安装后，需要重启 Tomcat 服务器生效。

不重启安装（仅支持 JDK 6-8）

以上方式安装成功之后需要重启服务器，如果在服务器启动的情况下，不重启安装 OpenRASP，需要在以上命令后面增加 -pid 参数指定运行的服务器进程ID:

在 Windows 下面请替换 $JAVA_HOME 为 %JAVA_HOME%

RASP 升级方法

在 Linux 下面，可以使用 bin/catalina.sh stop 来执行 graceful stop

你会在日志里看到类似下面的输出，这表明 Tomcat 将在处理完当前的HTTP后退出

之后参考我们的自动或者手动安装文档，重新安装即可

手动安装 - Linux

1. 安装软件

进入到 tomcat 安装目录(绝对路径包含空格将导致启动失败)，e.g /opt/apache-tomcat-8.5.6，将 rasp 目录复制过来

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

否则你可能在 catalina.out 里看到类似这样的错误，

2. 修改 Tomcat 启动脚本

打开 bin/catalina.sh, 找到如下内容：

修改为如下（增加 -javaagent 项）

对于使用 yum 安装的 tomcat，你需要创建 /etc/tomcat/conf.d/rasp.conf，并写入以下内容

对于JDK9以上版本，还需要增加额外的JDK启动参数，e.g

3. 开启远程管理

如果你不需要远程管理功能，请跳过这个步骤。

首先，请先参考文档，找到 openrasp.yml 配置文件内容。然后打开 <tomcat_home>/rasp/conf/openrasp.yml，添加或者修改如下内容:

4. 验证安装是否成功

首先重启tomcat服务器。如果安装了管理后台，在管理后台检查主机是否上线即可；如果是单机版，可以按照如下流程检查:

检查响应的请求头是否包含 X-Protected-By 字样，出现则表示安装成功:

如果使用了反向代理，可能不会看到上面的请求头。此时可以检查 rasp/logs/rasp/rasp.log 中是否出现 OpenRASP Engine Initialized 字样，出现也表示安装成功:

如果服务器无法启动，请检查 tomcat 启动日志，看Java是否抛出异常，e.g catalina.out。如果你无法解决问题，请。

手动安装 - Windows

1. 安装软件

进入到 tomcat 安装目录，e.g D:\apache-tomcat-8.5.6，将 rasp 目录复制过来

2. 修改 tomcat 配置

2.1 如果是下载的 "32-bit/64-bit Windows Service Installer" 安装包，

请参考，打开 bin/tomcatXw.exe

切换到 Java 标签页，

在 Java Options 下面增加启动参数，注意替换下绝对路径，e.g

对于JDK9以上版本，还需要额外增加如下内容

2.2 如果是下载的 "Windows zip" 安装包

打开 bin\catalina.bat, 找到 :setArgs 处：

在 :setArgs 下增加新的 JAVA_OPTS，e.g

对于JDK9以上版本，还需要额外增加两个JDK启动参数，e.g

3. 开启远程管理

方法同 Linux 版本，在 openrasp.yml 里增加相关配置即可。

4. 验证安装是否成功

重启 tomcat 服务器，然后检查日志文件，一般是 rasp/logs/rasp/rasp.log，如果出现 OpenRASP Engine Initialized 字样，出现则说明安装成功；或者访问一下服务器，检查是否存在 X-Protected-By: OpenRASP 响应头，存在即表示安装成功。

常见问题

1. Tomcat Windows Service Installer 版本，无法自动安装

服务版本的安装包，没有提供 catalina.sh，只提供了 tomcatX.exe 作为启动工具

请参考，打开 bin/tomcatXw.exe 进行配置

JBoss 服务器

自动化安装

解压缩后，首先进入到解压后的目录中，e.g rasp-20170721

如果你要开启远程管理，请先参考管理后台 - 添加主机文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -install 参数，

安装成功后，需要重启 JBoss 服务器生效。

不重启安装

以上方式安装成功之后需要重启服务器，如果在服务器启动的情况下，不重启安装 OpenRASP，需要在以上命令后面增加 -pid 参数指定运行的服务器进程 id，JDK6 - JDK8 样例命令如下，

** 由于无法在运行时增加 JbossEAP 对 OpenRASP 的运行时依赖，所以无法支持 JbossEAP 的不重启安装 **

** jdk9 ～ jdk11 不支持不重启安装 **

手动安装 - Linux

1. 安装软件

进入到 jboss 安装目录(绝对路径包含空格将导致启动失败)，e.g /opt/jboss

复制安装包内的 rasp 目录到当前目录，

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

2. 配置 JBoss

如果是 JBoss 4-6 (非 EAP 版本)，

打开bin/run.sh, 找到任意以 JAVA_OPTS= 为起始的行，e.g

在下面增加 JAVA_OPTS="-javaagent:${JBOSS_HOME}/rasp/rasp.jar ${JAVA_OPTS}"，最终效果如下:

如果是 JBoss EAP，

standalone模式

打开bin/standalone.sh，找到# Display our environment处，在下面添加：

domain模式

server-group方式配置rasp

如果按照server-group配置rasp，那么此group下面所有的服务器都会安装rasp，打开domain/configuration/domain.xml文件，找到<server-groups>标签，在需要安装rasp的server-group中找到<jvm>标签添加如下配置：

server方式配置rasp

如果只对某个server-group的特定的server安装rasp，打开domain/configuration/host.xml文件，找到<servers>标签，在需要安装rasp的server中添加如下配置：

3. 开启远程管理

配置方法同，不再赘述。

4. 验证安装是否成功

重启 JBoss 服务器，观察启动日志中是否出现 OpenRASP Engine Initialized字段，出现则说明安装成功

手动安装 - Windows

1. 安装软件

进入到 jboss 安装目录，e.g D:\\jboss

复制安装包内的 rasp 目录到当前目录

2. 配置 JBoss

如果使用Jboss 4～6 (非 EAP 版本)，则打开 bin\run.bat;

打开脚本后，找到任意以 set JAVA_OPTS 为起始的行，如：

在下面增加 set JAVA_OPTS=-javaagent:%JBOSS_HOME%\rasp\rasp.jar %JAVA_OPTS%：

如果使用Jboss EAP,

standalone模式

打开 bin\standalone.bat 找到第一次出现rem Setup JBoss specific properties处，在下面添加：

domain模式

方法同 Linux 版本

3. 开启远程管理

配置方法同，不再赘述。

4. 验证安装是否成功

重启 JBoss 服务器，观察启动日志(默认输出到终端)中是否出现 OpenRASP Engine Initialized字段，出现则说明安装成功；或者访问一下服务器，检查是否存在 X-Protected-By: OpenRASP 响应头，存在即表示安装成功。

已知问题

1. java.io.ObjectInputStream 错误

这个并不是 OpenRASP 的问题，请尝试更新JDK到最新版本

参考资料

2. JDK 9 以上版本兼容性问题

请参考手动修改启动参数。我们会尽快修改 RaspInstall 程序，并自动添加这个配置。

3. org.jboss.logmanager.PropertyConfigurator cannot be cast to org.jboss.as.logging.logmanager.ConfigurationPersistence 异常

在JBoss EAP 6.1.0上安装OpenRASP后，JBoss可能会无法启动并打印如下错误:

，有两种解决方法:

升级到 JBoss EAP 6.1.1
手动修正 JBOSS_MODULES_SYSTEM_PKGS 配置，暴露相关的Jar给javaagent

Wildfly 服务器

自动化安装

解压缩后，首先进入到解压后的目录中，e.g rasp-20181221

如果你要开启远程管理，请先参考管理后台 - 添加主机文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -install 参数，

这里的 <wildfly_root> 是 wildfly 的根目录。没有错误表示安装成功，其他配置请参考文档。安装后，需要重启 Wildfly 服务器生效。

** 由于无法在运行时增加 Wildfly 对 OpenRASP 的运行时依赖，所以无法支持 Wildfly 的不重启安装 **

手动安装 - Linux

1. 安装软件

进入到 wildfly 安装目录(绝对路径包含空格将导致启动失败)，e.g /opt/wildfly-9.0.1.Final，将 rasp 目录复制过来

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

2. 修改 Wildfly 启动脚本

如果是standalone模式

打开 bin/standalone.sh, 找到如下内容：

在其下面增加如下内容:

如果是domain模式

server-group

server

如果只对某个server-group的特定的server安装rasp，打开domain/configuration/host.xml文件，找到<servers>标签，在需要安装rasp的server中添加如下配置：

3. 开启远程管理

如果你不需要远程管理功能，请跳过这个步骤。

首先在管理后台找到 app_id、app_secret 两个关键参数，然后打开 <wildfly_home>/rasp/conf/openrasp.yml，添加或者修改如下内容:

4. 验证安装是否成功

重启 wildfly 服务器，然后检查 rasp/logs/rasp/rasp.log 中是否出现 OpenRASP Engine Initialized 字样，e.g

或者检查响应的 Header 是否包含 X-Protected-By 字样，e.g

出现则表示安装成功

手动安装 - Windows

1. 安装软件

进入到 wildfly 安装目录，e.g D:\wildfly-9.0.1.Final，将 rasp 目录复制过来

2. 修改 wildfly 配置

如果是standalone模式

打开 bin\standalone.bat, 找到 rem Setup JBoss specific properties 处：

在其下增加如下内容:

如果是domain模式

方法同 Linux 版本

3. 开启远程管理

方法同 Linux 版本，在 openrasp.yml 里增加相关配置即可。

4. 验证安装是否成功

重启 wildfly 服务器，然后检查日志文件，一般是 rasp/logs/rasp/rasp.log，如果出现 OpenRASP Engine Initialized 字样，出现则说明安装成功；或者访问一下服务器，检查是否存在 X-Protected-By: OpenRASP 响应头，存在即表示安装成功。

Resin 服务器

自动化安装

解压缩后，首先关闭Resin服务器，然后进入到解压后的目录中，e.g rasp-20180522

如果你要开启远程管理，请先参考管理后台 - 添加主机文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -install 参数，

安装成功后，需要重启 Resin 服务器生效。

不重启安装

Resin 目前不支持。

手动安装

1. 安装软件

进入到 resin 安装目录(绝对路径包含空格将导致启动失败)，e.g /opt/resin

复制安装包内的 rasp 目录到当前目录，

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

2. 配置 Resin

注意: 对于集群模式，可能不存在 <server-default> 标签。对于此类情况，请联系研发团队，并确认应该在哪里增加 JVM 启动参数。

如果是 resin 3，

打开conf/resin.conf, 找到 <server-default> 下面的 <jvm-arg> 起始行，e.g

在下面增加:

如果是 resin 4，

打开 conf/cluster-default.xml, 找到 <server-default> 下面的 <jvm-arg-line> 起始行，e.g

在下面增加:

3. 开启远程管理

配置方法同，不再赘述。

4. 验证安装是否成功

重启 Resin 服务器，观察启动日志中是否出现 OpenRASP Engine Initialized 字样，出现则说明安装成功；或者访问一下服务器，检查是否存在 X-Protected-By: OpenRASP 响应头，存在即表示安装成功。

Jetty 服务器

手动安装

1. 安装软件

进入到 jetty 安装目录，e.g /opt/jetty

复制安装包内的 rasp 目录到当前目录，

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

2. 配置 Jetty

这里假设 rasp 目录释放到了 /opt/jetty/rasp/。

修改 java 启动参数，增加 -javaagent 参数（注意将 -jar 放在命令最末尾):

需要注意的是，对于Windows服务器，请修正 -javaagent 参数，比如

3. 开启远程管理

配置方法同，不再赘述。

4. 检查 Jetty 是否安装成功

重启 Jetty 服务器，然后检查日志文件，如果出现 OpenRASP Engine Initialized 字样，出现则说明安装成功；或者访问一下服务器，检查是否存在 X-Protected-By: OpenRASP 响应头，存在即表示安装成功。

FAQ

1. Jetty / JDK 兼容性问题

Jetty 在 linux/windows 下存在很多问题，经常会看到以下几种错误

PWC6345: There is an error in invoking javac
PWC6199: The type java.io.ObjectStream cannot be resolved

以上这些问题大多是JDK、Jetty自身的问题，可通过更换其他小版本来解决。即使没有安装OpenRASP，Jetty运行也是不正常的。在安装 OpenRASP 前，请先保证Jetty是正常运行的

当然，如果安装OpenRASP后导致jetty出错，你可以

Spring Boot 框架

我们支持 war 包、jar 包两种部署模式。如果是 war 包的形式，直接参考相应服务器文档即可；如果是内嵌服务器的 jar 包形式，请参考本文档安装。对于 WebGoat 项目，对应的 jar 包通常为 webgoat-XXX.jar。

半自动安装

从 v1.2.0 版本开始，我们加入了 SpringBoot 半自动安装支持。之前的版本请参考手动安装章节。

1. 安装软件

SpringBoot 没有提供通用的启动脚本，所以我们的半自动安装程序只会释放文件。在解压缩后，首先进入到解压后的目录中，e.g rasp-20181221

如果你要开启远程管理，请先参考文档，找到 app_id/app_secret/backend_url 三个关键参数，然后执行如下命令，

如果你只是运行单机版，只需要指定 -install 参数，

这里的 <spring_boot_folder> 通常是 XXX.jar 包所在的目录。具体 jar 的名字请咨询业务线。

2. 配置启动参数

假设 spring_boot_folder 目录为 /opt/spring-boot/。

修改 SpringBoot 启动参数，增加 -javaagent 绝对路径参数（注意将 -jar 放到命令最末尾），e.g

如果JDK版本为6-8，那么启动参数如下配置

如果JDK版本为11，那么启动参数如下配置

3. 检查安装是否成功

访问服务器，检查是否存在 X-Protected-By: OpenRASP 响应头即可。

手动安装

1. 安装软件

进入到 Spring Boot 所在目录，通常是 jar 所在的目录，e.g /opt/spring-boot

复制安装包内的 rasp 目录到当前目录，

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以还需要修改 rasp 目录的权限，e.g

2. 开启远程管理

配置方法同，不再赘述。

3. 配置启动参数

假设 rasp 目录释放到了 /opt/spring-boot/rasp/。

修改 SpringBoot 启动参数，增加 -javaagent 绝对路径参数（注意将 -jar 放到命令最末尾），e.g

如果JDK版本为6-8，那么启动参数如下配置

如果JDK版本为11，那么启动参数如下配置

4. 检查安装是否成功

访问服务器，检查是否存在 X-Protected-By: OpenRASP 响应头即可。

东方通TongWeb服务器

手动安装

1. 安装软件

复制安装包内的 rasp 目录到 TongWeb 安装目录，比如

D:\tongweb安装目录\rasp
/opt/tongweb安装目录/rasp

OpenRASP 需要在 rasp 目录下释放一些动态链接库，所以在 Linux 下还需要修改 rasp 目录的权限，e.g

2. 配置 TongWeb 服务器

2.1 方法一: 手动配置 external.vmoptions 文件

打开 Tongweb安装目录/bin/external.vmoptions，然后在其中添加javaagent的配置项:

添加完成后的效果如下图所示(参考红线部分):

配置完成后，重启TongWeb服务器即可生效。

2.2 方法二: 通过TongWeb控制台进行配置

登陆TongWeb的管理控制台，点击左侧 启动参数配置，然后找到 其他jvm参数，添加javagent配置项即可:

添加完成后的效果如下图所示(参考红线部分):

添加完成后点击保存按钮，然后重启TongWeb服务器即可生效。

3. 开启远程管理

配置方法同，不再赘述。

4. 检查安装是否成功

访问下服务器，检查响应头里是否存在 X-Protected-By: OpenRASP 字样，存在即表示安装成功。当然，如果安装 OpenRASP 后导致TongWeb出错，你可以

安装管理后台

快速开始

在开始之前，请先根据软件下载里的说明，下载 rasp-cloud.tar.gz，并解压缩到本地。

安装数据库

目前，我们使用了和两种数据库。前者用来存储报警和统计信息，后者用来存储应用、账号密码等信息。

目前我们对数据库的要求是，

MongoDB 版本大于等于 3.6
ElasticSearch 版本大于等于 5.6，小于 7.0 (ES 7.X 变化较大，暂无计划支持)

具体如何安装数据库，这里不在赘述。

启动管理后台

首先，编辑 conf/app.conf 文件，修正 ElasticSearch 和 MongoDB 两个服务器的地址。如果这两个数据库都安装在了本机，且使用默认端口，请跳过此步骤:

关于 MongoDB 认证配置，可参考文章操作；如果 MongoDB 有主从，只需要填写主地址。

然后，在终端里执行如下命令，启动后台服务器:

登录成功后，请根据文档，了解如何添加第一台主机。

高级配置

后台负载均衡

在百度，我们会启动一个前端服务器，

然后在不同的机房，分别启动一个 agent 服务器（使用同一份 conf/app.conf 配置文件即可）

服务器部署完成后，请根据文档，将所有的Agent服务器填入。之后就可以在 添加主机 界面上，生成自动安装命令了。

容量说明: 目前，在2核4GB的主机上，按照3分钟一个心跳计算，大概单台机器可容纳 1000个 客户端。

ElasticSearch 负载均衡

在使用ES集群时，EsAddr 填写一个服务器的地址即可。我们自动会调用 /_nodes/ 接口获取全部服务器信息并轮询，以避免单点问题。

配置项详细说明

以下配置均为在 conf/app.conf 中配置

Beego 相关

常用 beego 配置项如下，更多设置请参考文档，

参数

说明

默认值

OpenRASP 相关

OpenRASP 可用配置项目如下，

参数

说明

默认值

开启 HTTPS

在 conf/app.conf 中加入以下配置即可，修改后重启后台生效:

后台运维

升级后台

请登录到每一台部署了 rasp-cloud 的主机，并按照如下步骤进行升级:

如果是 v1.3.0 之前的后台

备份原来的配置文件，conf/app.conf
下载新的安装包，解压缩到相同目录
检查是否需要更新配置文件

如果是 v1.3.0 甚至更高版本的后台

备份原来的配置文件，conf/app.conf
下载新的安装包，解压缩到相同目录
检查是否需要更新配置文件

找回密码

请登录到后台所在的主机，执行如下命令，根据提示重置密码。目前密码强度要求是 8-50 位，必须包含数字和字母。

检查后台状态

请登录到后台所在的主机，执行如下命令即可:

查看后台版本

请登录到后台所在的主机，执行如下命令即可:

定期备份

当然，如果公司有DBA团队，可以考虑托管给他们。

其他说明

Logstash 配置

当 AlarmLogMode 设置为 file 时，可使用 Logstash 采集文件日志。Logstash 样例配置如下，使用前请先修正日志路径

FAQ

1. 常见启动失败原因

日志会打印到 logs/api/agent-cloud.log 里。如果启动时没有增加 -d 参数，我们将同时在前台打印错误消息，e.g

目前定义的错误如下，

具体错误信息请查看 nohup 控制台输出

2. 管理后台打开后空白、按钮点不动等问题

我们目前只兼容 Google Chrome 浏览器。如果页面出现任何问题，请按下 F12 调出开发工具，并检查控制台是否有错误输出。如下图中的红色字样:

如果发现这种问题，请加入QQ群联系我们处理。

3. ElasticSearch "Result window is too large" 错误

如果你搜索的时间范围太大，ES 可能会爆出如下错误:

Result window is too large, from + size must be less than or equal to: [10000] but was [281280]. See the scroll api for a more efficient way to request large data sets. This limit can be set by changing the [index.max_result_window] index level setting.

4. 我的主机名显示为 "im-not-resolvable"

解决方法是，在 /etc/hosts 下面为你的主机名添加一条记录:

添加后，重启 Java 服务器生效。再次启动时，我们会注册一个新的agent到后台。

5. 管理后台打不开，Chrome 浏览器提示 ERR_CONNECTION_REFUSED

6. 无法发送邮件报警，提示 5XX 错误

大部分国内邮箱都不支持密码登录，需要申请授权码进行登录。如果你在使用下列邮箱，请参考他们的 FAQ 文档进行配置:

Coremail - 请联系销售

7. ElasticSearch X-Pack 使用说明

目前，后台使用的索引名称前缀为:

real-openrasp-X (alias)
openrasp-X

如果你在使用 X-Pack，且需要按照索引名称前缀进行授权，可以根据上述规则添加认证。若要查看当前 ES 的索引和别名列表，可访问如下URL:

8. 自己编译的后台，访问前端服务器 8086 端口提示 404 错误

前端文件在 dist 目录下，如果前端服务器返回 404 则说明这个目录不存在，或者 dist/index.html 不存在。

9. 误删ES索引，如何处理？{#es-index-reset}

10. 报警上传成功，后台看不到报警而且 ES 健康状态为 yello

修复方式请参考文章解决。

11. 我使用 nginx 作为管理后台的反向代理，iast 扫描器无法连接，总是提示400错误

iast 扫描器使用 websocket upgrade 协议连接管理后台，nginx 需要同时传递 Upgrade 头才能工作:

否则会在管理后台 api/agent-cloud.log 看到如下错误

12. 管理后台假死，日志里出现大量 too many open files

参考修正 limits.conf 里的配置即可，修正后需要重新登录生效。

最后通过 ulimits -n 命令确认即可。

13. 离线主机排查

如果后台出现离线主机，请按照如下步骤排查:

检查客户端与后台是否连通。使用 curl 命令访问管理后台，检查是否能访问。
重启 Tomcat/PHP 服务器，检查主机是否上线。
检查客户端主机名、网卡信息是否有变化。如果有，后台信息会跟着变更，并产生一台新的主机。这个问题会在后续版本修正，即固定 rasp_id 到配置目录。

14. rasp-cloud 启动卡住

目前已知的情况有

beego自身存在BUG，如果日志目录被链接到 /dev/null，将会卡住。e.g log/access 目录

云控后台接口

接口描述

** 请求格式 **：

请求体采用 json 格式，分页页码从 1 开始计数，分页请求格式如下所示：

** 分页参数说明 **：

参数

说明

** 响应格式 **：

响应采用 json 格式，示例如下：

** 参数说明**：

参数

说明

** 接口类型 **：接口分为两类，一类是为前端服务的前端接口，另一类是为 RASP Agent 服务的 Agent 接口，具体接口格式如下文所示。

Ping 接口

** 描述 **：用来测试后台联通性的通用接口

** 请求方法 **：GET，POST

** 路径 **：v1/ping

** 请求体 **：空

** 返回结果 **：

Version 接口

** 描述 **：用来获取当前RASP云控后台的版本号

** 请求方法 **：POST

** 路径 **：v1/version

** 请求体 **：空

** 返回结果 **：

前端接口

认证方式

认证方式分为两种:

登陆之后获取 cookie 认证，cookie字段为 RASP_AUTH_ID，cookie有效期默认 7 天。
通过在请求头中添加静态 token 进行认证，请求头字段为 X-OpenRASP-Token，具体的 token 管理方式，参照下文 token 管理接口。

** 描述 **：登录接口，初始管理后台用户名：openrasp ，密码：admin@123，登陆成功设置登录 cookie

** 请求方法 **：POST

** 路径 **：v1/user/login

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

登出接口

** 描述 **：退出登录状态，清空 cookie

** 请求方法 **：GET

** 路径 **：v1/user/logout

** 请求体 **：无

** 返回结果 **：

获取是否登录

** 描述 **：获取当前是否为登录状态

** 请求方法 **：GET

** 路径 **：v1/user/islogin

** 请求体 **：无

** 返回结果 **：

默认密码判断接口

** 描述 **：判断当前用户密码是否为默认密码，用于给前端提供是否需要修改密码的提醒

** 请求方法 **：GET，POST

** 路径 **：v1/user/default

** 请求体 **：无

** 返回结果 **：

参数

说明

更改密码接口

** 描述 **：更改管理员密码，密码长度 8~50 个字节，必须同时包含字母和数组

** 请求方法 **：POST

** 路径 **：v1/user/update

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

插件管理接口

上传插件

** 描述** ：上传文件为 .js 结尾的插件文件，插件版本在文件第一行，插件名称在插件的第二行

** 请求方法 **：POST

** 路径 **：v1/api/plugin?app_id=c593342c72eb78fc8e7393d0a87b8f3fc54dfbec

** 请求体 **： form data 格式的文件参数，参数名称 plugin

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

下载插件

** 描述 ** ：根据插件 id 下载插件

** 请求方法 **：GET

** 路径 **：v1/api/plugin/download?id=47af9da31ec3f233f35a25776f5e06086ebf239ff60a021ada4750b65640d0d24b9ae382

** 请求体 **：无

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：插件文件，文件名称为 {NAME}-{VERSION}.js，{VERSION} 为插件版本，{NAME}为插件名称

获取插件基本信息

** 描述 ** ：根据插件 id 获取插件

** 请求方法 **：POST

** 路径 **：v1/api/plugin/get

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

下发算法配置

** 描述 ** ：给插件下发插件算法开关配置，下发的算法配置会合并到插件中

** 请求方法 **：POST

** 路径 **：v1/api/plugin/algorithm/config

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

恢复插件默认算法配置

** 描述 ** ：根据插件 id 恢复插件最开始的默认算法配置

** 请求方法 **：POST

** 路径 **：v1/api/plugin/algorithm/restore

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

删除插件

** 描述 ** ：根据插件 id 删除插件，无法删除被选中的插件

** 请求方法 **：POST

** 路径 **：v1/api/plugin/delete

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

App管理接口

新增 APP

** 描述 ** ：新增一个 APP

** 请求方法 **：POST

** 路径 **：v1/api/app

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

删除 APP

** 描述 ** ：删除一个 APP ，同时删除该 APP 下所有的 RASP 和插件，当仅剩一个 APP 无法删除，至少保留一个 APP，无法删除还存在在线 RASP 的 APP

** 请求方法 **：POST

** 路径 **：v1/api/app/delete

** 请求体 **：

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

获取 App

** 描述 ** ：获取所有App，或某一个 id 的 app，如果参数中有 id 参数，则返回相应id的 app，如果没有 id 参数，则需要 page 和 perpage 参数来做分页，返回相应数量的 APP 数组

** 请求方法 **：POST

** 路径 **：v1/api/app/get

** 请求体 **：

获取相应 id APP

按照APP名称检索

获取一定数量 APP

** 参数说明**：

参数

参数类型

必须

说明

** 返回结果 **：

返回相应 id APP

返回一定数量 APP

下发通用配置

描述：给 app 下发 rasp 通用配置

请求方法：POST

路径：v1/api/app/general/config

请求体：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：返回更新之后的完整 APP 信息

下发白名单配置

** 描述 **：给 app 下发 rasp 白名单配置

** 请求方法 **：POST

** 路径 **：v1/api/app/whitelist/config

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：返回更新之后的完整 APP 信息

下发报警配置

** 描述 **：给 app 下发报警配置

** 请求方法 **：POST

** 路径 **：v1/api/app/alarm/config

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：返回更新之后的完整 APP 信息

APP 配置接口

** 描述 **：下发 APP 配置，用于配置 APP 名称，语言和描述信息

** 请求方法 **：POST

** 路径 **：v1/api/app/config

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：返回更新之后的完整 APP 信息

获取 APP 下的所有插件

** 描述 **：根据 APP ID 获取所有的插件内容

** 请求方法 **：POST

** 路径 **：v1/api/app/plugin/get

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

获取 APP 下发的插件

** 描述 **：获取 APP 当前选中的插件，该插件会下发给 APP 下的 RASP

** 请求方法 **：POST

** 路径 **：v1/api/app/plugin/select/get

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

设置 APP 下发的插件

** 描述 **：设置 APP 下发给 RASP 的插件

** 请求方法 **：POST

** 路径 **：v1/api/app/plugin/select

** 请求体 **：

** 参数说明 **：

** 描述 **：如果当前插件是 official.js 的话，判断当前下发插件是否为最新官方插件。如果不是（如 iast.js），返回当前下发插件和最新插件的版本信息

** 描述 **：按条件搜索 rasp，并把搜索结果导出到 csv 文件，app_id 字段为必选，剩余搜索条件为可选

** 请求方法 **：GET

** 路径 **：v1/api/rasp/csv?app_id=eaGdr22DfthDz51JHF65sd

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **： csv 文件

删除 RASP

** 描述 **：删除指定条件的 RASP，在线的 rasp 不允许删除，当参数中存在 id，删除指定 id 的 rasp 并忽略其他参数

** 请求方法 **：POST

** 路径 **：v1/api/rasp/delete

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

批量删除 RASP

** 描述 **：根据 rasp id 批量删除rasp

** 请求方法 **：POST

** 路径 **：v1/api/rasp/batch_delete

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

RASP 备注接口

** 请求方法 **：POST

** 路径 **：v1/api/operation/search

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

服务器管理接口

获取服务器 url

** 描述 **：获取 panel 和 agent 服务器的 url 地址

** 请求方法 **：POST

** 路径 **：v1/api/server/url/get

** 参数 **：无

** 返回结果 **：

参数

说明

更改服务器地址

** 描述 **：更改 panel 和 agent 服务器的访问地址

** 请求方法 **：POST

** 路径 **：v1/api/server/url

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

清空数据

** 描述 **：清空数据库中的攻击事件、基线报警、异常日志、请求数量、崩溃信息

** 请求方法 **：POST

** 路径 **：v1/api/server/clear_logs

** 请求体 **：

** 参数说明 **：

参数

说明

** 返回结果 **：

请求统计接口

请求统计信息聚合

** 描述 **：按照时间聚合 RASP 上传的请求统计数据

** 请求方法 **：POST

搜索异常信息

** 描述 **：根据条件搜索异常信息

** 请求方法 **：POST

** 路径 **：v1/api/log/error/search

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

RASP接口

认证方式

增加 APP ID 请求头： X-OpenRASP-AppID: 9b3554a97673f1f8f5c929310298037a660d3b7a
增加 APP Secret 请求头： X-OpenRASP-AppSecret: 2wMG8K9F71CZyvlWu1CRwf7tVDVW7Ud4gxCY5X4aMzO

RASP 注册接口

** 描述 **：注册 RASP 基本信息，如果有 id 参数，那么为更新相应的 RASP 信息，否则为新增 RASP

** 请求方法 **：POST

** 路径 **：v1/agent/rasp

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

** 参数说明 **：

参数

说明

心跳接口

** 描述 **：接受 RASP 向云控后台的定时心跳，如果请求参数中的 md5 和后台指定的插件 md5 不同则判定有新插件，如果配置时间小于云控后台的最后配置时间，判定有新配置，每次更新都是插件和配置的全量更新。

** 请求方法 **：POST

** 路径 **：v1/agent/heartbeat

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

** 参数说明 **：

参数

说明

统计上报接口

** 描述 **：上传 rasp 统计信息

** 请求方法 **：POST

** 路径 **：v1/agent/report

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

崩溃上报接口

** 描述 **：上传 rasp 奔溃信息

** 请求方法 **：POST

** 路径 **：v1/agent/crash/report

** 请求体 **：

格式： multipart/form-data

内容：

crash_log: hs_err_pid25945.log

hostname: Mac-xxxx-host

language: java

rasp_id: d5ged5g54dr1gdr5d5erg5rdg

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

上传攻击报警日志

** 描述 **：上传 RASP 攻击日志

** 请求方法 **：POST

** 路径 **：v1/agent/log/attack

** 请求体 **：

** 参数说明 **：攻击日志数组，包含多条攻击日志，日志字段说明：

** 返回结果 **：

参数

说明

上传类库依赖信息{#upload-dependencies}

** 描述 **：根据主机上传类库信息

** 请求方法 **：POST

** 路径 **：v1/agent/dependency

** 请求体 **：

** 参数说明 **：

参数

参数类型

必须

说明

** 返回结果 **：

上传基线报警日志

** 描述 **：基线报警内容，基线报警会根据 "stack_trace,rasp_id, policy_id, policy_param “ 几个字段进行去重操作，这几个字段相同的报警只会出现一次。

** 请求方法 **：POST

** 路径 **：v1/agent/log/policy

** 请求体 **：

** 参数说明 **：基线日志数组，包含多条基线日志，极限报警字段说明：

** 返回结果 **：

参数

说明

上传异常日志

** 描述 **：上传异常日志

** 请求方法 **：POST

** 路径 **：v1/agent/log/error

** 请求体 **：

** 参数说明 **：错误日志数组，包含多条错误日志，字段说明同上文基线报警字段说明。

** 返回结果 **：

参数

说明

RASP Agent认证接口

** 描述 **：用于认证 app id 和 app secrete

** 请求方法 **：POST

** 路径 **：v1/agent/auth

** 请求体 **：空

** 返回结果 **：

扫描器接口

接口描述{#iast-api-description}

** 请求格式 **：

请求体采用 json 格式，分页页码从 1 开始计数，分页请求格式如下所示：

** 参数说明 **：

参数

说明

** 响应格式 **：

响应采用 json 格式，示例如下：

** 参数说明 **：

参数

说明

认证方式{#iast-auth}

增加请求头： Content-Type: application/json

认证接口{#iast-api-auth}

参数类型

必须

说明

** 返回结果 **：

参数

说明

扫描数据类{#scanner-data}

获取所有目标{#getall-task}

** 描述 **：获取所有安装rasp agent的主机（agent至少发送过一次http请求结果）

** 请求方法 **：POST

** 路径 **：v1/iast

** 请求体 **：

参数

参数类型

必须

说明

** 返回结果 **：

** 参数说明 **：

参数

说明

清空扫描任务{#clean-task}

** 描述 **：清空目标主机的信息(重置为一个未配置的agent状态)，或清空url列表

** 请求方法 **：POST

** 路径 **：v1/iast

** 请求体 **：

参数

参数类型

必须

说明

** 返回结果 **：

参数

说明

OpenRASP Documents (Old)

简介

hashtag常用链接

安装部署

兼容性说明

hashtagJava Agent

hashtagPHP Agent

hashtag管理后台

安装管理后台

hashtag快速开始

hashtag安装数据库

hashtag启动管理后台

hashtag高级配置

hashtag后台负载均衡

hashtagElasticSearch 负载均衡

hashtag配置项详细说明

hashtag后台运维

hashtag升级后台

hashtag找回密码

hashtag检查后台状态

hashtag查看后台版本

hashtag定期备份

hashtag其他说明

hashtagLogstash 配置

hashtagFAQ

hashtag1. 常见启动失败原因

hashtag2. 管理后台打开后空白、按钮点不动等问题

hashtag3. ElasticSearch "Result window is too large" 错误

hashtag4. 我的主机名显示为 "im-not-resolvable"

hashtag5. 管理后台打不开，Chrome 浏览器提示 ERR_CONNECTION_REFUSED

hashtag6. 无法发送邮件报警，提示 5XX 错误

hashtag7. ElasticSearch X-Pack 使用说明

hashtag8. 自己编译的后台，访问前端服务器 8086 端口提示 404 错误

hashtag9. 误删ES索引，如何处理？{#es-index-reset}

hashtag10. 报警上传成功，后台看不到报警而且 ES 健康状态为 yello

hashtag11. 我使用 nginx 作为管理后台的反向代理，iast 扫描器无法连接，总是提示400错误

hashtag12. 管理后台假死，日志里出现大量 too many open files

hashtag13. 离线主机排查

hashtag14. rasp-cloud 启动卡住

快速接入

hashtag快速接入

hashtag其他常用链接

hashtag常见问题

PHP 服务器

hashtag自动化安装

hashtag升级 PHP Agent

hashtag手动安装 - Linux

hashtag1. 确认基本信息

hashtag2. 安装软件

hashtag3. 安装检测插件

hashtag4. 验证安装是否成功

hashtag手动安装 - MacOS

hashtagFAQ

hashtag1. include/require hook 点未生效

hashtag2. 单机版 php-fpm 模式下，插件目录的文件监控功能，有时会失效

hashtag3. OpenRASP正常拦截攻击，但是alarm.log没有日志

hashtag4. CentOS 7.4 apache 使用 systemd 启动会崩溃的问题

hashtag5. php_json_encode 未定义错误

hashtag6. 无法检测到 web 目录下的敏感文件？{#faq-webdir-scan}

hashtag7. alphine 环境无法启动，提示找不到 ld-linux-x86-64.so.2

hashtag8. 如何判断PHP是否为线程安全版本

Tomcat 服务器

hashtag自动化安装

hashtagRASP 升级方法

hashtag手动安装 - Linux

hashtag手动安装 - Windows

hashtag常见问题

JBoss 服务器

hashtag自动化安装

hashtag手动安装 - Linux

hashtag手动安装 - Windows

hashtag已知问题

Wildfly 服务器

hashtag自动化安装

hashtag手动安装 - Linux

hashtag手动安装 - Windows

Resin 服务器

hashtag自动化安装

hashtag手动安装

Jetty 服务器

常用链接

Java Agent

PHP Agent

管理后台

快速开始

安装数据库

启动管理后台

高级配置

后台负载均衡

ElasticSearch 负载均衡

配置项详细说明

后台运维

升级后台

找回密码

检查后台状态

查看后台版本

定期备份

其他说明

Logstash 配置

FAQ

1. 常见启动失败原因

2. 管理后台打开后空白、按钮点不动等问题

3. ElasticSearch "Result window is too large" 错误

4. 我的主机名显示为 "im-not-resolvable"

5. 管理后台打不开，Chrome 浏览器提示 ERR_CONNECTION_REFUSED

6. 无法发送邮件报警，提示 5XX 错误

7. ElasticSearch X-Pack 使用说明

8. 自己编译的后台，访问前端服务器 8086 端口提示 404 错误

9. 误删ES索引，如何处理？{#es-index-reset}

10. 报警上传成功，后台看不到报警而且 ES 健康状态为 yello

11. 我使用 nginx 作为管理后台的反向代理，iast 扫描器无法连接，总是提示400错误

12. 管理后台假死，日志里出现大量 too many open files

13. 离线主机排查

14. rasp-cloud 启动卡住

快速接入

其他常用链接

常见问题

自动化安装

升级 PHP Agent

手动安装 - Linux

1. 确认基本信息

2. 安装软件

3. 安装检测插件

4. 验证安装是否成功

手动安装 - MacOS

FAQ

1. include/require hook 点未生效

2. 单机版 php-fpm 模式下，插件目录的文件监控功能，有时会失效

3. OpenRASP正常拦截攻击，但是alarm.log没有日志

4. CentOS 7.4 apache 使用 systemd 启动会崩溃的问题

5. php_json_encode 未定义错误

6. 无法检测到 web 目录下的敏感文件？{#faq-webdir-scan}

7. alphine 环境无法启动，提示找不到 ld-linux-x86-64.so.2

8. 如何判断PHP是否为线程安全版本

自动化安装

RASP 升级方法

手动安装 - Linux

手动安装 - Windows

常见问题

自动化安装

手动安装 - Linux

手动安装 - Windows

已知问题

自动化安装

手动安装 - Linux

手动安装 - Windows

自动化安装

手动安装

手动安装

FAQ

半自动安装

手动安装

手动安装

1. 安装软件

2. 配置 TongWeb 服务器

3. 开启远程管理

4. 检查安装是否成功

自动化安装

升级 PHP Agent

手动安装 - Linux