Skip to content

Dynamic Runtime Scanning (Java)

There are two parts to the Java Runtime agent solution: a CodeLogic agent and a Java instrumentation agent that attaches to your application. The instrumentation agent collects data from the application that you attach it to and sends it to the CodeLogic agent, which then reports to your CodeLogic Server. The results of the scan are viewed in your CodeLogic Server.

Important

  • To perform a runtime scan, you must have an environment in which you can start your application with additional JVM options.
  • Analysis is done in pairs. One instrumented application to one instance of the dynamic agent.

Docker

Generate the Docker command

  • Click Store from the left hand menu.

DockerAgents.png

  • Locate the Java Dynamic Agent Docker Image tile and click Generate.
  • Enter your CodeLogic Server IP address or hostname.
  • Enter the Namespaces for the code you are instrumenting in the field provided.
    • Values are comma separated with no spaces.
    • Example: com.codelogic,com.example
  • Click Next.
  • Copy your code snippet from the Success! window.
  • Run the dynamic agent with the command you copied. It will wait for a connection from the instrumentation agent.

Note

You can override the default port by passing the RMI_REGISTRY_PORT and SERVER_RMI_PORT environment variables to the docker container.

  • Example for port 1097: 
    --env RMI_REGISTRY_PORT="1097"
--env SERVER_RMI_PORT="1097"
--publish 1097:1097

Instrument Your Application

  • Click Store from the left hand menu.

Store_JavaDynamicInstrumentionAgent.png

  • Locate the Java Dynamic Instrumentation Agent tile and click Download.
  • Save the jar file in a location your application can access.
  • Add the following to your application's JVM options:
    • -javaagent:"/path/to/java-instrumentation.jar" -Xbootclasspath/a:"/path/to/java-instrumentation.jar"
  • Run your application. The instrumentation agent will report that it has connected to the dynamic agent.

Manual

  • Edit the configuration file to include "packageLinkingFilters".

    Note

    Before you edit the configuration file, you may want to save a copy of the default configurations.

    • Linux: /opt/codelogic/java/agentConfig.json
    • Windows: C:\Program Files (x86)\CodeLogic\java\agentConfig.json
    • Example 
      "packageLinkingFilters" : ["com.codelogic", "com.example"],

    Note

    A copy of the configuration file with comments that explain the configuration options, is located in:

    • Linux: /opt/codelogic/java/agentConfig_documentation.json
    • Windows: C:\Program Files (x86)\CodeLogic\java\agentConfig_documentation.json

  • Open the Command Line as an Administrator.

  • Enter the command to tell the agent to start listening.

    Linux:
/opt/codelogic/java# ./run_dynamic.sh

Windows:
C:\Program Files (x86)\CodeLogic\java>run_dynamic.bat

    You may also run the command with these options: * --rmi-registry-port - The port at which the agent will try to create or locate the RMI registry on which to host the runtime agent server. * --server-rmi-port - The port at which the agent will export the RMI interface for communication from the instrumentation agent. * --server-name - The name of the server object registered with RMI.

Authorize the Agent

For security, agents must be authorized before they will send metadata to the CodeLogic Server.

  • Click Admin and then select the Agents tab.

  • Locate the agent in the list.

    Note

    The Request Status will be listed as OPEN.

  • Click the more menu icon in the Actions column and select Approve/Reject.

    • The Approve window opens.
  • Optionally, enter a name for the agent in the Agent Name field.
  • Click Approve to complete the authorization process.

Scanning

After the runtime agent reports that it is Waiting for connection from instrumentation JAR, you can start the application with the instrumentation JAR attached.

java -javaagent:/opt/codelogic/java/java-instrumentation.jar -Xbootclasspath/a:/opt/codelogic/java/java-instrumentation.jar -jar /path/to/your/application.jar

Settings to the instrumentation agent are passed in with the -javaagent option after the path to the jar as a sequence of key value pairs:

  • rmiRegistryHost - the host at which the agent will try to contact an RMI registry.
  • rmiRegistryPort - the port at which the agent will try to contact an RMI registry.

  • serverName - the name of the server object bound by the runtime agent to which we are trying to connect.

    Example Usages 
    # Using Alternate Port 1097 
java -javaagent:/opt/codelogic/java/java-instrumentation.jar=rmiRegistryPort=1097 -Xbootclasspath/a:/opt/codelogic/java/java-instrumentation.jar -jar /path/to/your/application.jar

# Using Alternate Host 192.168.0.10 and Port 1097 (Note: Semicolons need escaped in some shells.)
java -javaagent:/opt/codelogic/java/java-instrumentation.jar=rmiRegistryPort=1097;rmiRegistryHost=192.168.0.10 -Xbootclasspath/a:/opt/codelogic/java/java-instrumentation.jar -jar /path/to/your/application.jar

Stop the Scan

Stop your application to stop the scan.

View Scan Results

  • Log in to the CodeLogic Server.
  • Select the Search tab.
  • Expand the application to view items and their dependencies.