Setting up and Configuring the CxIAST Java Agent in the AUT Environment
Pre-Requisites
Java version 8 - 12
One of the application servers listed under Supported Environments for Applications Under Testing.
Notice
Java 6 is no longer supported.
The automatic upgrade for the Java agent is not supported when running on IBM JDK . The Agent must therefore be upgraded manually.
The Java agent running on the IBM JDK does not send diagnostic notifications to the CxIAST Manager.
Test applications must have read, write and modify access to the IAST agent unzipped folder.
Extract the java-agent.zip archive to a folder of your choice on the host where the application under testing (AUT) is going to run.
Running the Test Application with the Java Agent
The Java agent requires additional JVM options on the AUT.
To add the JVM options to the AUT, do one of the following:
Add the JVM options after the Java command (for example, if you run your app using
java -jar app.jar, runjava <options> -jar app.jar).Add the JVM options to the
JAVA_TOOL_OPTIONSenvironment variable and then run the application from the same shell. Do one of the following:For some application servers, you can use the CxIAST.bat/sh script in the agent folder to easily set this variable and start your app
Some application servers have custom environment variables that can be used. For example, with Apache Tomcat, you can use
CATALINA_OPTS.
Windows: Enter the following
Windows: C:\agent\folder\CxIAST.bat -e C:\tomcat\folder\bin\startup.bat
Linux: Enter the following
/agent/folder/CxIAST.sh -e /tomcat/folder/bin/startup.sh
Windows: Enter the following
set "CATALINA_OPTS=-javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none" C:\tomcat\folder\bin\startup.bat
Add it to the service (Windows only):
Run C:\agent\folder\CxIAST.bat -a <TomcatServiceName>
Linux: Enter the following
export "CATALINA_OPTS=-javaagent:/agent/folder/cx-launcher.jar -Xverify:none" /tomcat/folder/bin/startup.sh
Warning
The service runs with the agent once it has been restarted.
Notice
To remove the agent, run C:\agent\folder\CxIAST.bat -r <TomcatServiceName>
Windows: Enter the following
C:\agent\folder\CxIAST.bat -e "java -jar myapp.jar"
Linux: Enter the following
/agent/folder/CxIAST.sh -e "java -jar myapp.jar"
Windows: Enter the following
set "JAVA_TOOL_OPTIONS=-javaagent\agent\folder\cx-launcher.jar -Xverify:none"
Linux: Enter the following
export "JAVA_TOOL_OPTIONS= -javaagent:/agent/folder/cx-launcher.jar -Xverify:none"
Now run your app (Windows or Linux):
java -jar myapp.jar
Windows: Enter the following
java -javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none -jar myapp.jar
Linux: Enter the following
java -javaagent:/agent/folder/cx-launcher.jar -Xverify:none -jar myapp.jar
Notice
Gradle You can run SpringBoot projects directly from the IDE or command line using the bootRun Gradle task. Customize the task in your build.gradle file as follows:
bootRun { jvmArgs = ["-javaagent:/agent/folder/cx-launcher.jar", "-Xverify:none"] }Maven You can run SpringBoot projects directly from the IDE or command line using the spring-boot:run task. Following is an example of running it from the command line:
mvn spring-boot:run "-Dspring-boot.run.jvmArguments=-javaagent:/path/to/cx-launcher.jar -Xverify:none"
For Jetty,
myapp.jaris usuallystart.jar
Linux: Enter the following
/agent/folder/CxIAST.sh -j standalone.sh
Notice
You can use the same command for domain.bat/sh.
Windows: Enter the following
set "JAVA_TOOL_OPTIONS=-javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none" set "JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.cx,com.checkmarx" set "JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -Djava.util.logging.manager=org.jboss.logmanager.LogManager" set "JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -Xbootclasspath/p:<JBOSS-FOLDER>/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-XX.jar"
For JBoss 7.2 and above, also run
set "JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -Xbootclasspath/p:<JBOSS-FOLDER>/modules/system/layers/base/org/wildfly/common/main/wildfly-common-XX.jar"
If running on Java 9 and above, also run
set "JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -Dsun.util.logging.disableCallerCheck=true"
Linux: Enter the following
export "JAVA_TOOL_OPTIONS=-javaagent:/agent/folder/cx-launcher.jar -Xverify:none" export "JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS} -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager,com.cx,com.checkmarx" export "JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS} -Djava.util.logging.manager=org.jboss.logmanager.LogManager" export "JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS} -Xbootclasspath/p:<JBOSS-FOLDER>/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-XX.jar"For JBoss 7.2 and above, also run
export "JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS} -Xbootclasspath/p:<JBOSS-FOLDER>/modules/system/layers/base/org/wildfly/common/main/wildfly-common-XX.jar"If running on Java 9, also run
export "JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS} -Dsun.util.logging.disableCallerCheck=true"Now start JBoss as you normally would using standalone.bat/sh or domain.bat/sh
To solve timeout errors during JBoss startup:
Increase the JBoss memory to 2GB.
In the file configuration XML file (
jboss/standalone/configuration/standalone.xmlorjboss/domain/configuration/domain.xml, depending on which configuration you're running), add the following section under the 'server' node, after the 'extensions' node:<system-properties> <property name="jboss.as.management.blocking.timeout" value="600"/> </system-properties>
Windows: Enter the following
-javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none" set "CLASSPATH=C:\agent\folder\cx-agent.jar"
Linux: Enter the following
export "JAVA_OPTIONS=-javaagent:/agent/folder/cx-launcher.jar -Xverify:none" export "CLASSPATH=/agent/folder/cx-agent.jar"
Now you can start Weblogic using startWebLogic.cmd/sh.
Increase WebLogic memory. We recommend doubling the current memory limit, but you should have at least 2GB.
Windows: Append the following to
<WEBLOGIC_DOMAIN_FOLDER>\bin\setDomainEnv.cmd, for example 2GB:set WLS_MEM_ARGS_64BIT=-Xmx2048m set WLS_MEM_ARGS_32BIT=-Xmx2048m
Linux: Append the following to
<WEBLOGIC_DOMAIN_FOLDER>/bin/setDomainEnv.sh, for example 2GB:export WLS_MEM_ARGS_64BIT="-Xms2048m -Xmx2048m" export WLS_MEM_ARGS_32BIT="-Xms2048m -Xmx2048m"
Add cx-agent.jar to the classpath.
Windows: Append the following to
<WEBLOGIC_DOMAIN_FOLDER>\bin\setDomainEnv.cmd:set CLASSPATH=C:\agent\folder\cx-agent.jar;%CLASSPATH%
Linux: Append the following to
<WEBLOGIC_DOMAIN_FOLDER>/bin/setDomainEnv.sh:export CLASSPATH="/agent/folder/cx-gent.jar:${CLASSPATH}"Register the Java agent.
Windows: In the file
<WEBLOGIC_DOMAIN_FOLDER>\bin\startWebLogic.cmd, at the end, change%JAVA_HOME%\bin\java %JAVA_VM%to%JAVA_HOME%\bin\java -javaagent:"C:\agent\folder\cx-launcher.jar" -Xverify:none %JAVA_VM%Linux: In the file
<WEBLOGIC_DOMAIN_FOLDER>/bin/startWebLogic.sh, at the end, change${JAVA_HOME}/bin/java ${JAVA_VM}to${JAVA_HOME}/bin/java "-javaagent:/agent/folder/cx-launcher.jar" -Xverify:none ${JAVA_VM}Restart the WebLogic server.
Notice
If the application is not running on the same node as the Weblogic admin server, you can improve the agent performance by disabling instrumentation for the admin server by adding the -javaagent:… inside an if $SERVER_NAME is not "AdminServer" statement. For an example, refer to the troubleshooting document.
If using a jar file in Windows, enter the following:
C:\agent\folder\CxIAST.bat -e "java -jar vertx-XXX-fat.jar"
If using a jar file in Linux, enter the following:
/agent/folder/CxIAST.sh -e "java -jar vertx-XXX-fat.jar"
If you use vertx.bat in Windows, enter the following:
C:\agent\folder\CxIAST.bat -e "vertx.bat run Verticle.java"
If you use vertx.bat in Linux, enter the following:
/agent/folder/CxIAST.sh -e "vertx.bat run Verticle.java"
Windows: Enter the following
set "JAVA_TOOL_OPTIONS=-javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none"
Linux: Enter the following
export "JAVA_TOOL_OPTIONS=-javaagent:/agent/folder/cx-launcher.jar -Xverify:none"
Now run your application (Windows or Linux) using one of the following commands:
java -jar vertx-XXX-fat.jar vertx.bat run Verticle.java
If using a jar file, you can add the arguments directly as follows:
java -javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none -jar vertx-XXX-fat.jar
Linux: Enter the following
Linux: java -javaagent:/agent/folder/cx-launcher.jar -Xverify:none -jar vertx-XXX-fat.jar
Notice
For Vert.x, it is recommended that you increase the event-loop thread timeout, by setting the Java system variable vertx.options.maxeventloopexecutetime to > 10000000000 (nanoseconds)
To set the Java system variable:
Add it to the Java command, as follows:
java -Dvertx.options.maxeventloopexecutetime=10000000000 -jar vertx-XXX-fat.jarAdd
-Dvertx.options.maxeventloopexecutetime=10000000000to the value of theJAVA_TOOL_OPTIONSenvironment variable.
To use WebSphere Traditional:
Copy the files cx-agent.jar and cx-launcher.jar from
/agent/folderto the/IBM/WebSphere/AppServer/libfolder.Go to WebSphere admin console:
https://<WebSphere-Machine>:9043/ibm/consoleFrom the admin console, select Servers > Application servers > (select a server) > Configuration > Server Infrastructure > Java and Process Management.
Select Process Definition > Additional Properties, then select Java Virtual Machine.
In the Generic JVM arguments field, add the following parameters:
-javaagent:/IBM/WebSphere/AppServer/lib/cx-launcher.jar -Daj.weaving.loadersNotToSkip=ALL -Xverify:none -Diast.home=/iast-java-agent
Click <Apply> and then click <Save>.
Restart your server.
Add the following actions to the end of the Dockerfile:
Copy (or map) the extracted agent folder to the image under
/cx-agent.In the image, create a Python script
/work/cx-agent/add_cx_gent.pywith the following content:import os, shutil iast_home = '/cx-agent' iast_jvm_args = '-javaagent:/opt/IBM/WebSphere/AppServer/lib/cx-launcher.jar' \ ' -Diast.home=' + iast_home + \ ' -Daj.weaving.loadersNotToSkip=ALL' \ ' -DcxAgentAutoUpgrade=no' # get jvm (there should be only one) jvm = AdminConfig.list('JavaVirtualMachine') # append to jvm args orig = AdminConfig.showAttribute(jvm, 'genericJvmArguments') AdminConfig.modify(jvm, [['genericJvmArguments', orig + u' ' + iast_jvm_args]]) # recommended to increase memory (value is in MB) AdminConfig.modify(jvm, [['maximumHeapSize', 4000]]) AdminConfig.save() # copy required jars to WS lib shutil.copyfile(iast_home + '/cx-launcher.jar', '/opt/IBM/WebSphere/AppServer/lib/cx-launcher.jar') shutil.copyfile(iast_home + '/cx-agent.jar', '/opt/IBM/WebSphere/AppServer/lib/cx-agent.jar') if os.path.exists(iast_home + '/cx-agent-extension.jar'): shutil.copyfile(iast_home + '/cx-agent-extension.jar', '/opt/IBM/WebSphere/AppServer/lib/cx-agent-extension.jar')Run the script using
RUN /opt/IBM/WebSphere/AppServer/bin/wsadmin.sh -lang jython -conntype NONE -f /work/cx-agent/add_cx_gent.py
Alternatively, if you don’t want to modify the Dockerfile/image, you can do the following:
Map the agent folder and script as a volume instead of copying it.
Change the container CMD to run the above command and then run the original CMD.
If using the default WS Docker configuration, change the command to:
docker run <args> <image_name> bash -c "/opt/IBM/WebSphere/AppServer/bin/wsadmin.sh -lang jython -conntype NONE -f /work/cx-agent/add_cx_gent.py && /work/start_server.sh"
Notice
In the above copy commands, make sure the new file owner is the same as the WS process.
If using the default WS Docker configuration, it should look like
COPY --chown=was:root <src> <dest>.These instructions are suitable for the official
ibmcom/websphere-traditionalimage.However, you should be able to use them for custom WS images with minor corrections to the paths and permissions.
Create a file jvm.options under the server folder (/liberty/wlp/usr/servers/<server-name>) and add the following lines to it:
-javaagent:/iast-java-agent/cx-launcher.jar-Daj.weaving.loadersNotToSkip=com.ibm.ws.classloading.internal.AppClassLoader-Xverify:none
Windows: Enter the following
Set "JAVA_TOOL_OPTIONS=-javaagent:C:\agent\folder\cx-launcher.jar -Daj.weaving.loadersNotToSkip=com.ibm.ws.classloading.internal.AppClassLoader -Xverify:none"
Linux: Enter the following
Export "JAVA_TOOL_OPTIONS=-javaagent:/agent/folder/cx-launcher.jar -Daj.weaving.loadersNotToSkip=com.ibm.ws.classloading.internal.AppClassLoader -Xverify:none"
Now run WebSphere Liberty using the 'server' shell script (server.bat on Windows).
Warning
Before making any changes, create a backup of domain.xml
Open thedomain.xmlyou're using (e.g.,payara-4.1.2.174/payara41/glassfish/domains/domain1/config/domain.xml) and make the following changes:
Locate the node domain->configs->config->java-config. The config node to which the changes should be made is the one where config name has the same value as the
domain->servers>server config-ref attribute.
Locate the jvm-options entry starting with -Djava.ext.dirs= and append the following to its value
${path.separator}/agent/folder. If the entry doesn't exist, createand add it as follows:
<jvm-options>-Djava.ext.dirs=${path.separator}/agent/folder</jvm-options>Add the following entries:
<jvm-options>-javaagent:/agent/folder/cx-launcher.jar</jvm-options> <jvm-options>-Daj.weaving.loadersNotToSkip=ALL</jvm-options> <jvm-options>-Xverify:none</jvm-options> <jvm-options>-Dorg.osgi.framework.bootdelegation=com.cx.*,com.checkmarx.*,org.xml.*,org.w3c.*,org.ietf.jgss,javax.ws.*,javax.xml.*,com.sun.security.*</jvm-options>
If you're running a standalone application (not a web application), you need to add the cx.standalone option.
Uncomment the -Dcx.standalone=yes line from the .bat/sh file and then run the following…
For Windows
C:\agent\folder\CxIAST.bat -e "java -jar standalone_app.jar"
For Linux
/agent/folder/CxIAST.sh -e "java -jar standalone_app.jar"
Enter the following:
For Windows:
set "JAVA_TOOL_OPTIONS=-javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none -Dcx.standalone=yes"
For Linux:
export "JAVA_TOOL_OPTIONS=-javaagent:/agent/folder/cx-launcher.jar -Xverify:none -Dcx.standalone=yes"
Run your application (Windows or Linux):
java -jar standalone_app.jar
Adding the Arguments Directly
Windows: Enter the following
java -javaagent:C:\agent\folder\cx-launcher.jar -Xverify:none -Dcx.standalone=yes -jar myapp.jar
Linux: Enter the following
java -javaagent:/agent/folder/cx-launcher.jar -Xverify:none -Dcx.standalone=yes -jar myapp.jar
To run a test application with the Java agent using Docker, whether a plain Dockerfile or using Docker Compose, follow the same basic steps.
Obtaining the Agent:
Download the agent zip archive and extract it. Do one of the following:
Copy the folder into the Docker image.
Use a volume to map the extracted folder into the image.
Running the test application with the Java agent: Add the required JVM options by doing one of the following:
Modify the CMD or ENTRYPOINT
javacommand in the Dockerfile to include the options, as described for each server.Set the application environment variable, as described for each server, in the Dockerfile or in the Docker Run command.
Replace or override the CMD command to use the CxIAST.bat/sh file.
The following section illustrates examples:
Assuming you have a Dockerfile which has the following CMD, and you've copied/mapped the agent to /cx-agent:
CMD java -jar mySpringBootApp.jar
You can modify the command to:
CMD java -javaagent:/cx-agent/cx-launcher.jar -Xverify:none -jar mySpringBootApp.jarYou can add an environment variable inside the Dockerfile:
ENV JAVA_TOOL_OPTIONS -javaagent:/cx-agent/cx-launcher.jar -Xverify:noneCMD java -jar mySpringBootApp.jarChange only the 'docker run' command, adding an environment variable and mapping the agent folder:
docker run -v /agent/folder:/cx-agent -e JAVA_TOOL_OPTIONS=-javaagent:/cx-agent/cx-launcher.jar -Xverify:none my_docker_imageOverride the CMD command with the CxIAST.sh file:
docker run /cx-agent/CxIAST.sh -e "java -jar mySpringBootApp.jar"
Assuming you have the following yml file:
tomcat:
image: tomcat:latest
ports:
- 8080:8080
db: ...To run it with the agent, add an environment variable and a volume as follows:
tomcat:
image: tomcat:latest
ports:
- 8080:8080
environment:
- CATALINA_OPTS=-javaagent:/cx-agent/cx-launcher.jar -Xverify:none
volumes:
- /agent/folder:/cx-agent
db: ...The following additional parameters can be applied to the Java Agent:
appTag - Add a tag to the application (for example, Application1 will be TAG:Application1).
scanTag - Add a tag to a scan. Allows you to differentiate between two different tests or to relate a scan in CxIAST to a build version or test name.
team - Allows an automatic assignment of a team to any application discovered by the agent. Note that the team must be configured in Access Control.
Special Configuration in cx_agent.properties:
metadataMandatory - appTag/scanTag/team parameters are mandatory, if set to true.
appTagRegexp=
<regex>- is defined, appTag must match the regex.
Add the parameters, using the -key=value format, at the end of the command, for example:
CxIAST.bat -e C:\tomcat\folder\bin\startup.bat -appTag=myApp -scanTag=myScan -team=myTeam
Add the following JVM arguments using the environment variable or the configuration file:
-DcxAppTag=<application tag> -DcxScanTag=<scan tag> -DcxTeam=<team to assign>
To use the Java agent with SpringBoot or Tomcat applications on Cloud Foundry, use the following buildpack:
https://github.com/checkmarx-ts/cx-iast-buildpack/
Refer to the README in the buildpack repository for detailed instructions.
Removing an Agent
Reverse the changes made in the 'Running the Agent' section or if you used the CxIAST.bat / CxIAST.sh, start the application without it. For Services, use the remove option to remove the agent.