Dynamic Runtime Scanning (Deprecated Java Agent)

There are two parts to the Java Runtime agent solution: a Lineai 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 Lineai agent, which then reports to Lineai.

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.
• Data is sent to the Lineai server every 5 minutes.

Docker

Run the dynamic agent

Pull and run the deprecated Java dynamic agent Docker image:

docker run --pull always --rm --interactive                        \
     --env LINEAI_HOST="https://yourinstance.app.lineai.com" \
     --env AGENT_UUID="your-agent-uuid"                            \
     --env AGENT_PASSWORD="your-agent-password"                    \
     --env NAMESPACES="com.lineai,com.example"                  \
     yourinstance.app.lineai.com/lineai_java_dynamic:latest

The dynamic agent waits 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

Download the deprecated Java instrumentation agent JAR from your Lineai server:

wget http://your_server/lineai/server/packages/java-instrumentation-deprecated.jar

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-deprecated.jar" -Xbootclasspath/a:"/path/to/java-instrumentation-deprecated.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/lineai/java/agentConfig.json
  • Windows: C:\Program Files (x86)\Lineai\java\agentConfig.json
  • Example

  "packageLinkingFilters" : ["com.lineai", "com.example"],

  Note

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

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

• Open the Command Line as an Administrator.

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

  Linux:
  /opt/lineai/java# ./run_dynamic.sh
  
  Windows:
  C:\Program Files (x86)\Lineai\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 Lineai.

Obtain AGENT_UUID and AGENT_PASSWORD from your Lineai administrator, or set these environment variables before starting the agent. If credentials are not pre-provisioned, the agent may register with the server and await administrator approval before scans are accepted.

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/lineai/java/java-instrumentation-deprecated.jar -Xbootclasspath/a:/opt/lineai/java/java-instrumentation-deprecated.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/lineai/java/java-instrumentation-deprecated.jar=rmiRegistryPort=1097 -Xbootclasspath/a:/opt/lineai/java/java-instrumentation-deprecated.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/lineai/java/java-instrumentation-deprecated.jar=rmiRegistryPort=1097;rmiRegistryHost=192.168.0.10 -Xbootclasspath/a:/opt/lineai/java/java-instrumentation-deprecated.jar -jar /path/to/your/application.jar

Stop the Scan

Stop your application to stop the scan.