# 云鲨RASP插桩教程

# 1. 兼容性说明

语言 兼容范围 支持的Web 容器/框架
Java JDK(8-18) Apache Tomcat(6-10)
Spring Boot(1.x, 2.x)
Jetty(7, 8, 9)
JBoss EAP(6,7)
Wildfly(8-18)
Weblogic(10, 12)
Resin(3.x, 4.x)
WebSphere(8.5)
Liberty(wlp8.x, wlp13-22)
Python 3.5 – 3.9

架构：x86_64		 Bottle(0.11, 0.12)
Django(1.x, 2.x)
Django Rest Framework(3.7+)
Falcon(2.x, 3.x)
Flask(0.10-0.12, 1.x, 2.x)
Pyramid(1.4.5, 1.9, 1.10.x)
FastAPI(0.68+)
Tornado(4.5+)
PHP 5.3-5.6
7.0-7.4

架构：x86_64		 Apache httpd扩展(1.3-2.4)
Nginx + fpm(1.0-1.18)

表 1 云鲨RASP探针兼容性说明

# 2 RASP启动参数

# 2.1 JavaAgent 配置参数

参数名 参数说明 类型 是否必填 可选值 默认值
1 -Dxmrasp.delay.init 初始化规则的延迟时间(毫秒) Integer 否 整型数值，单位毫秒 0
2 -Dxmrasp.log.out 日志输出路径 String 是 任意有读写权限的目录 jvm临时目录(建议手动填写)
3 -Dxmrasp.log.level 日志输出等级 String 否 ERROR/DEBUG/
WARN/INFO/
TRACE/OFF		 OFF
4 -Dxmrasp.instrument.
ignore.packages		 忽略的插桩类的前缀 String 否 字符串以逗号分割即可 无
5 -Dxmrasp.log.mode 日志模式 String 否 console/file file
6 -Dxmrasp.report.
stack.depth		 上报堆栈长度 Integer 否 任意整数 20
7 -Dxmrasp.wrap.
request		 是否获取请求体 Boolean 否 true/false TRUE
8 -Dxmrasp.only.ipv4 是否仅仅获取ipv4地址 Boolean 否 true/false TRUE
9 -Dxmrasp.app.name 应用名称 String 是 任意字符串 默认自动获取(SpringBoot项目必须手动填写)
10 -Dxmrasp.address 当前节点ip String 否 任意ip格式字符串 默认自动获取
11 -Dxmrasp.delay.start 探针延迟启动时间(毫秒) Integer 否 整型数值，单位毫秒 0
12 -Dxmrasp.report.
protect		 是否开启攻击上报保护，开启之后频繁上报会触发熔断 String 否 true/false FALSE
13 -Dxmrasp.ip 探针服务端心跳地址 String 是 云鲨RASP平台域名 rasp.xmirror.cn:8088
14 -Dxmrasp.token 探针注册需要的token String 是 从探针注册界面复制可得 自填
15 -Dxmrasp.nodename 探针节点名称 String 是 唯一节点名称 自填

表 2-1 JavaAgent配置参数

# 2.2 PHPAgent 配置参数

参数名 参数说明 类型 是否必填 可选值 默认值
1 -projectname 应用名称 String 是 任意字符串 自填
2 -ip 探针服务端心跳地址 String 是 云鲨RASP平台域名 rasp.xmirror.cn
3 -token 探针注册需要的token，用于用户验证 String 是 从探针注册界面复制可得 自填
4 -nodename 探针节点名称 String 否 唯一节点名称 无
5 -mode 探针运行模式 String 否 rasp 无
6 -port 探针server服务端口 Integer 是 云鲨RASP平台服务端口 8088
7 -php 使用的php执行文件绝对路径 String 否 任意字符串 默认使用系统环境变量中的php
8 -path agent安装目录 String 是 任意字符串 自填

表 2-2 PHPAgent配置参数

# 2.3 PythonAgent 配置参数

参数名 参数说明 类型 是否必填 可选值 默认值
1 --log 日志输出路径 String 否 任意有读写权限的目录 无
2 --projectname 应用名称 String 是 任意字符串 自填
3 --ip 探针服务端心跳地址 String 是 云鲨RASP平台域名 rasp.xmirror.cn
4 --token 探针注册需要的token，用于用户验证 String 是 从探针注册界面复制可得 自填
5 --nodename 探针节点名称 String 否 唯一节点名称 无
6 --region 区域代号 String 否 任意字符串 无
7 --mode 探针运行模式 String 否 rasp 无
8 --env 指定需要安装的环境，多环境适用 String 否 可执行python路径 无
9 --port 探针server服务端口 String 是 云鲨RASP平台服务端口 8088

表 2-3 PythonAgent配置参数

# 3. 添加节点（探针插桩）

添加节点步骤即为将agent探针插桩至应用中，正确插桩后重启应用，则应用会以自免疫安全漏洞的状态安全运行，点击云鲨RASP顶部的【添加节点】，依据应用开发语言选择Java,Python或PHP探针。

添加节点

图 3-1 添加节点

# 3.1 Java

下载探针安装包：

下载方式分为wget，curl，以及点击按钮通过浏览器直接下载三种方式。

wget：

wget https://rasp.xmirror.cn/rasp/static/jar/agent.jar

curl：

curl -# -O https://rasp.xmirror.cn/rasp/static/jar/agent.jar

直接下载：

下载探针安装包

图 3.1-2 下载探针安装包

# 3.1.1 Tomcat

  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；

  2. 进入Tomcat安装目录下bin子目录，Linux系统创建《setenv.sh》文件，Windows系统创建《setenv.bat》文件，文件内容添加如下内容：

  • setenv.sh(Linux)：
export CATALINA_OPTS="
 -javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token= <token> 
-Dxmrasp.password=<password>
-Dxmrasp.nodename=<node name>"
  • setenv.bat(Windows):
set JAVA_OPTS="
 -javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token= <token> 
-Dxmrasp.password=<password>
-Dxmrasp.nodename=<node name>"

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

JAVA应用Tomcat下环境配置参数参考

图 3.1-3 Java应用Tomcat下环境配置参数参考

节点安装过程中可依据需要，判断是否需要开启探针日志记录、关闭字节码校验，如确需此类服务，在云鲨产品【添加节点】功能内，开启相关按钮可获取开启服务所需环境配置参数，将此参数添加至《setenv.sh》（Linux）或《setenv.bat》（Windows）中即可。

编辑完成后保存上述环境配置文件，应用即开始安装探针。

  1. 检查探针安装是否成功，重启应用服务。

  • 安装探针后，应用程序会出现在【应用管理---未监控】列表内，可在此列表按需选择是否开启应用监控；

  • 探针注册需要一定时间，若长时间未出现在上述列表可通过如下步骤进行排查：

    • 检查应用是否正常启动，若未启动成功，可尝试【关闭字节码校验】，即在环境配置文件《setenv》文件中添加“-noverify”参数后重启应用；
    • 检查网络，通过ping，telnet等工具验证应用服务器与云鲨RASP AgentServer网络是否通畅；
    • 若仍无法解决，请至云鲨官网加入社区联系工作人员协助排查。（QQ号：837548005）
    社区支持

    图 3.1-4 社区支持

# 3.1.2 Spring Boot

  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 如果使用 war 包方式部署，请参考具体中间件的部署方式；
  3. 如果使用 jar 包方式部署，则直接在启动命令中增加RASP相关参数：
java -javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>  
-Dxmrasp.password=<password>
-Dxmrasp.nodename=<node name>
-Dxmrasp.app.name=<app name>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.1.3 Jetty

  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 进入Jetty安装目录，在《start.ini》文件插入如下内容：
--exec
-javaagent: <替换为探针存放位置> /agent.jar
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>   
-Dxmrasp.password=<password>  
-Dxmrasp.nodename=<node name>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.1.4 Resin

# 3.1.4.1 Resin3
  1. 将探针安装包放在Resin3的根目录或根目录的子目录下，确保安装包内容可用；
  2. 进入Resin3安装目录，打开conf/resin.conf文件，在<!--adds all.jar files under the resin/lib directory -->的<class-loader>中间添加：
<tree-loader path="${resin.home}/ <替换为探针存放位置> /xm-boot"/>
<tree-loader path="${resin.root}/ <替换为探针存放位置> /xm-boot"/>
3. 复制以下内容，添加在上述文件conf/resin.conf中的下: 
jvm_args: 
-javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>  
-Dxmrasp.password=<password> 
-Dxmrasp.nodename=<nodename>
4. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。
# 3.1.4.2 Resin4
  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 进入Resin4安装目录，在 conf/resin.properteis 中找到 “jvm_args:”（默认是注释掉的），取消注释并修改为以下内容：
jvm_args: 
-javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>  
-Dxmrasp.password=<password> 
-Dxmrasp.nodename=<nodename>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.1.5 WebSphere

  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 登录WebSphere Console，选择要修改的服务器：
选择欲修改的服务器

图 3.1-5 选择欲修改的服务器

  1. 在 Server Infrastructure > Java and Process Management 中选择 Process definition：
设置Process definition

图3.1-6 设置Process definition

  1. 在 Process definition 中选择 Java Virtual Machine：
选择Java Virtual Machine

图 3.1-7 选择Java Virtual Machine

  1. 在 Generic JVM arguments 中填入：
-javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>   
-Dxmrasp.password=<password> 
-Dxmrasp.nodename=<node name> 

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

配置Generic JVM arguments参数

图 3.1-8 配置Generic JVM arguments参数

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.1.6 Liberty

  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 创建或修改 ${server.config.dir}/bootstrap.properites（例如：/opt/ibm/wlp/usr/servers/defaultServer/bootstrap.properties），添加如下内容：
 org.osgi.framework.bootdelegation = cn.xmirror.rasp.*
  1. 创建或修改 ${server.config.dir}/jvm.options（例如：/opt/ibm/wlp/usr/servers/defaultServer/jvm.options），添加如下内容：
-javaagent: <替换为探针存放位置> /agent.jar
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>  
-Dxmrasp.password=<password>
-Dxmrasp.nodename=<node name>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.1.7 东方通

# 3.1.7.1 通过配置文件修改
  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 进入 TongWeb 安装目录，修改 bin/external.vmoptions 在 “#jvm_options”下添加如下内容：
-javaagent: <替换为探针存放位置> /agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>   
-Dxmrasp.password=<password> 
-Dxmrasp.nodename=<node name>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。
# 3.1.7.2 通过TongWeb Console配置
  1. 将探针安装包存放于应用任意可读写目录下，确保应用可用安装包内容；
  2. 登录TongWeb Console后，在启动参数配置>其他jvm参数中添加如下内容：
-javaagent:<替换为探针存放位置>/agent.jar 
-Dxmrasp.ip=<ip> 
-Dxmrasp.token=<token>   
-Dxmrasp.password=<password> 
-Dxmrasp.nodename=<node name>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

配置jvm参数

图 3.1-9 配置jvm参数

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

# 3.2 Python

  1. 下载探针安装包 选择探针版本，复制命令至服务环境执行命令，即可下载探针安装包及其依赖；
下载探针安装包

图 3.2-1 下载Python探针

  1. 配置探针 复制下面内容，在服务环境执行此命令：
xmirror-set-config
--ip=rasp.xmirror.cn
--port=8088
--token=<token> 
--projectname=<projectname>
--nodename=<node name>
  1. 启动应用 使用"xmirror + 正常启动命令"启动应用，例如 Flask:xmirror python flask_app.py
  2. 检查探针安装是否成功，参考3.1.1.Tomcat下检查步骤。

# 3.3 PHP

下载探针安装包：

下载方式分为wget，curl，以及点击按钮通过浏览器直接下载三种方式。

wget：

wget https://rasp.xmirror.cn/rasp/static/php/xshark_php.bin

curl：

curl -# -O https://rasp.xmirror.cn/rasp/static/php/xshark_php.bin

直接下载： 下载探针安装包

图 3.3-1 下载PHP探针

  1. 将探针安装包存放于应用任意可读写目录下，并授予执行权限：
cd [探针下载目录] && chmod +x [下载的探针文件名]

例如：

cd /opt/xmrasp && chmod +x xshark_php.bin
  1. 配置命令行参数，在终端执行如下命令：
./xshark_php.bin
-ip=<ip>
-port=<port>
-token=<token> 
-mode=rasp
-projectname=<project name>
-nodename=<node name>
-path=<path>

注：其中红色字体部分请依据安装环境实际参数进行填写，具体可用内容可至云鲨产品【添加节点】功能处获取！

  1. 检查探针安装是否成功，重启应用服务：参考3.1.1.Tomcat下检查步骤。

←