Deploying a Java IAST agent

This topic explains how to create a Java IAST agent type on your web server.

Before you begin

The simplest and most effective way to use IAST is to deploy it as a WAR file servlet on your web server. When this is not possible, for example when running IAST on a Quarkus framework, the IAST agent can be installed as a Java agent using a JAR file.
Support:
Only web application servers running JRE/JDK 1.8 or higher are supported.
  1. If the server where IAST is running is behind a proxy:
    • For a transparent proxy, use any one of the following Java properties when running the server:
      • Standard Java properties:
        -Dhttps.proxyHost={proxy_ip} -Dhttps.proxyPort={proxy_port}
      • Custom Java properties:
        -DIast.proxyHost={proxy_ip} -DIast.proxyPort={proxy_port}
      • Environment variables:
        IAST_PROXY_HOST={proxy_ip} IAST_PROXY_PORT={proxy_port}
    • If a certificate is needed to communicate externally (for example, to pass a transparent proxy), supply a valid certificate and run the following command to import it to the keystore:
      Note:
      If you have installed JRE with default settings, the keystore name is cacerts and it is protected by the password changeit. Otherwise, replace the -storepass, -keystore, and -file values with your own.
      keytool.exe -import 
                                        -storepass "changeit" 
                                        -keystore "C:\Program Files (x86)\Java\jre1.8.0_144\lib\security\cacerts" 
                                        -alias certificate.cer 
                                        -file "C:\certificate.cer" 
                                        -noprompt
  2. For IAST agent versions prior to 1.14.2, if both the compile-time and the runtime Java versions are 9 or higher, add the following flag to the java run command:
    –Djava.lang.invoke.stringConcat=BC_SB

Procedure

  1. Download the ASoC Java IAST agent:
    1. Follow the instructions provided here to download the agent.
  2. Extract the ZIP file:
    1. Unzip the downloaded file to access its contents.
  3. Deploy the IAST agent:
    Option A: Deploy as a WAR servlet:
    1. Locate the WAR file:
      1. Find Secagent.war in the root directory of the extracted ZIP file.
    2. Deploy your server:
      • Tomcat server / Jetty server: Copy Secagent.war to your webapps folder, or deploy it as you would any other WAR servlet.
      • WebSphere server: Deploy Secagent.war as a web application, not as an enterprise application. Ensure the context root is set to /Secagent.
      • WebSphere Liberty server / Open Liberty server: Copy Secagent.war to the dropins folder, or deploy it as usual.
      • Jboss/WildFly server / JBoss EAP server: Copy Secagent.war to the deployments folder, or deploy it as you would any other WAR servlet.
      • Weblogic: Deploy Secagent.war as you would any other WAR servlet.
    3. Verify deployment:
      1. Open a web browser and navigate to http://<server address>/Secagent.
      2. If the Secagent page opens, the agent has been successfully deployed.
      3. The IAST agent will monitor requests and report security issues as you use or test your application (run functional tests, run a Dynamic Scan, or explore the app manually).
    Option B: Deploy as a JAR file:

    Use this method if deploying the IAST agent as a WAR file is not possible (for example, when using the Quarkus framework).

    1. Locate the JAR file:
      1. Find secagent.jar in the jar_deployment folder.
    2. Add the Java agent to your application:
      1. Command line option: Add the following flag to your application's command line: 
        -Djavaagent:<path to secagent.jar>
      2. Environment variable option: Set the JAVA_TOOL_OPTIONS environment variable: 
        set JAVA_TOOL_OPTIONS=-javaagent:<path to secagent.jar>
    3. Verify deployment:
      1. Check the stdout for messages starting with "[IAST Secagent]".
      2. If these messages appear, the agent has been successfully installed.
      3. The IAST agent will monitor requests and report security issues as you use or test your application (run functional tests, run a Dynamic Scan, or explore the app manually).

Running a Java agent with security manager

About this task

You can run the Java agent with security manager:

  • As a war file on Tomcat or
  • As a jar file on servers other than Tomcat. Contact the AppScan support team for guidance.

To run the Java agent with security manager as war on Tomcat:

Procedure

  1. Locate the catalina.policy file.
    The catalina.policy file is usually located in the Tomcat installation configuration directory. The exact path might vary depending on your operating system and Tomcat version.
  2. Open the catalina.policy file in a text editor.
  3. Locate the "grant" block.

    Look for a block starting with the keyword "grant" followed by one or more "permission" statements.

  4. Add the required permissions as follows:
    1. Inside the "grant" block, add the following permission: 
      permission java.lang.RuntimePermission "net.bytebuddy.*";
    2. At the end of the file, add the following permission: 
      grant codeBase "file:${catalina.base}/webapps/Secagent/-" {
                                    permission java.security.AllPermission;
                                    };
  5. Save the catalina.policy file.
  6. Restart the Tomcat server to apply the changes.