Executing Agents Interactively via the CLI

The Lineai Agents can be executed interactively from the CLI. Executing an agent interactively allows you to view specific decompositions immediately.

An example Linux CLI is in /opt/lineai/java/run_agent.sh and /opt/lineai/sql/run_agent.sh. The Windows CLI is in C:\Program Files (x86)\Lineai\java\run_agent.bat. The example CLIs are also listed below.

The examples assume that java is Java 11.

A list of commands executed while in the shell is saved in a text file of the current working directory.

Depending upon the User user ID on a Linux system, the default permissions of the /opt/lineai directory may require a sudo su command to use the root account. Similarly, a Windows system may require starting a cmd terminal as an Administrator.

The interactive agent must be registered and approved before it will communicate with Lineai. Obtain credentials from your Lineai administrator, or allow the agent to self-register and await approval.

Start the Interactive Shell.

sudo su
systemctl stop lineai-java
cd /opt/lineai/java
java -Dspring.profiles.active=interactive -jar cc-java-agent-main.jar

sudo su
systemctl stop lineai-sql
cd /opt/lineai/sql
java -Dspring.profiles.active=interactive -jar cc-sql-agent-main.jar

cd "C:\Program Files (x86)\Lineai\java"
SET JAVA_HOME="%CD%\AdoptOpenJDK"
%JAVA_HOME%\bin\java -Dspring.profiles.active=interactive -jar "%CD%\cc-java-agent-main.jar"

Alternatively, the run_agent.sh (Linux) or run_agent.bat (Windows) script is used to run the agent interactively.

sudo su
systemctl stop lineai-java
cd /opt/lineai/java
./run_agent.sh

sudo su
systemctl stop lineai-sql
cd /opt/lineai/sql
./run_agent.sh

"C:\Program Files (x86)\Lineai\java\run_agent.bat"

Authorize the Interactive Agent.

Every agent must be authorized before it will communicate with Lineai. The interactive agent will output a reminder.

Before Authorization
After Authorization

…

2021-06-03 16:07:20.747INFO 30267 --- [main] .a.s.c.i.RegistrationContextIntitializer : Registering agent: f5539052-aa28-4914-a25b-573ed483daad
2021-06-03 16:07:21.062INFO 30267 --- [main] .a.s.c.i.RegistrationContextIntitializer : Agent: f5539052-aa28-4914-a25b-573ed483daad successfully registered.
2021-06-03 16:07:21.062INFO 30267 --- [main] .a.s.c.i.RegistrationContextIntitializer : Waiting on agent authorization...

The Request Status changes to APPROVED after the agent is authorized. The next time the agent is run interactively, the authorization status is remembered.

…
2021-06-03 17:55:06.378INFO 30426 --- [main] .a.s.c.i.RegistrationContextIntitializer : Agent with id f5539052-aa28-4914-a25b-573ed483daad is already authorized.
…

2021-06-03 17:55:07.696INFO 30426 --- [main] org.pf4j.AbstractPluginManager: Start plugin 'cc-sql-agent-plugin-jdbc@21.9.0'
2021-06-03 17:55:07.701INFO 30426 --- [main] c.c.a.s.p.j.plugin.JdbcSpringPluginImpl: plugin.start()
2021-06-03 17:55:07.951INFO 30426 --- [main] com.lineai.agent.sql.MainShell: Started MainShell in 4.897 seconds (JVM running for 5.342)

Interactively Analyze a JAR.

This example analyzes /usr/share/apport/apport.jar and sends the metadata to Lineai.

Sample output (Analyzing a JAR Interactively)

Timestamps are omitted and blank lines are inserted for clarity.

lineai-java:>analyze --type ARCHIVE --path /usr/share/apport/apport.jar --recursive -1

… INFO 10317 --- [main] c.c.agent.java.shell.AnalyzeCommands: Found analyze type: ARCHIVE

… INFO 10317 --- [main] a.j.a.d.a.DatabaseUsageClassFileAnalyzer : Class File Analysis complete for: ApportUncaughtExceptionHandler

… INFO 10317 --- [main] c.c.agent.java.shell.AnalyzeCommands: OutputFile written to: /opt/lineai/java/lineai-tmp/analysis-results/lineai\_tmp\_analyze-result\_92aba250-1d1e-469c-a7ec-43715e30108c.json

… INFO 10317 --- [main] c.c.util.client.AbstractNeo4capeClient: Submitting entity to neo4cape api. Attempt 1 of 5

… INFO 10317 --- [main] c.c.util.client.AbstractNeo4capeClient: Successfully posted entity to neo4cape api.

When the scan is complete you will receive a message. Please note that it may take a few minutes for the results to be processed on the Lineai server.

Interactive Shell Help

The interactive shell has a help facility. The default destination for an analysis is Lineai. Several actions are demonstrated below using the Java Agent.
Some output is omitted for clarity.
The prompt changes to the name of the agent.

Type exit to leave the interactive shell.

Starting the Interactive Shell

sudo su
systemctl stop lineai-java
cd /opt/lineai/java
./run_agent.sh

List of available commands

lineai-java:>help
AVAILABLE COMMANDS

agent-details:
                    Display registration status and current configuration for this agent.
agent-register:
                    Retrieve agent credentials after approval or force re-registration of this agent.
scan-namespaces:
                    Returns a list of available namespaces in a given artifact.
analyze:
                    Analyze java artifacts on demand. This command requires parameters
                    in interactive or commandline mode. Values from the agent
                    configuration are ignored.
run-analysis:
                    Analyze java artifacts from the currently configured agent configuration
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit, exit: Exit the shell.
history: Display or save the history of previously run commands
version: Show version info
script: Read and execute commands from a file.
prev: Runs the previously executed command

Help for the agent-register command

lineai-java:>help agent-register
NAME
      agent-register -
                  Retrieve agent credentials after approval or force re-registration of this agent.

SYNOPSIS
      agent-register --force boolean

OPTIONS
       --force or -f boolean
       [Flag Parameter: 'true' if option is specified.]

       Forcibly re-register this agent with the server.
       WARNING: This will generate a new agentId and discard any existing remote configuration.
       [Optional, default = false]

Help for the analyze command

lineai-java:>help analyze
NAME
       analyze -
            Analyze java artifacts on demand. This command requires parameters
            in interactive or commandline mode. Values from the agent
            configuration are ignored.

SYNOPSIS
       analyze [--application String] [--path String] --type String --output String --depth Integer --filter String --recursive String --database String --method-filter String --rescan boolean --expunge-scan-sessions boolean --scan-space-name String

OPTIONS
       --application or -a String
            The Application node to create that will be the parent of all objects found in the scan.
            The value is a comma-separated list of 'Application' semantic names.
            Semantic names may be anything you wish if creating a new application.
            If linking grouping to an existing application, use its semantic identity (the value without the `grouping:` prefix).
            [Mandatory]

       --path or -p String
            A comma-separated list of absolute filepaths to analyze or scan.
            [Mandatory]

       --type or -t String
            'SCAN' - automatically search for archives
            'ARCHIVE' - specify a Java archive to analyze (.jar,.war,.ear)
            'FILE' - (deprecated) Specify a file to analyze. Usually a .class file.
            [Optional, default = SCAN]

       --output or -o String
            'API_CSV' - Batch data locally in CSV zipped in the auxiliary directory. Upload the zip to the api when finished.
            'CSV' - Batch data locally in CSV files zipped in the auxiliary directory.
            [Optional, default = API_CSV]

       --depth Integer
            During scanning, this value will be used as the depth of subdirectories to traverse before stopping.
            [Optional, default = 500]

       --filter or -f String
            A comma-separated list of partial filenames that will cause an artifact to be marked for
            analysis during a SCAN if the artifact's filename contains the filter.
            Wildcards are not supported.
            [Optional]

       --recursive or -r String
            A comma-separated list of substrings to key off of to trigger recursive analysis (jar within jar).
            Ex: 'lineai,spring' would match 'lineai-core-services.jar' and 'spring-data-jpa.jar'.
            The star character '*' may be used to match all jars recursively. Warning: expensive operation.
            [Optional]

       --database or -d String
            A comma-separated list of database identities to use in the creation of relationships.
            These database identities will only be used if the scan finds tables and columns but cannot find
            the related database connection. One example where this may happen is with external configuration files.
            [Optional]

       --method-filter or -m String
            A comma-separated list of Java package prefixes that should be included in
            method-invokes-method relationships. By default no packages are included in method-to-method scanning.
            [Optional]

       --rescan boolean
            [Flag Parameter: 'true' if option is specified.]

            Normally to speed up analysis, archives already detected in the Lineai DB are skipped.
            With this flag, all archives that match filters will be scanned regardless.
            [Optional, default = false]

       --expunge-scan-sessions or -e boolean
            [Flag Parameter: 'true' if option is specified.]

            Instruct the server to delete all other scan sessions created
            by this agent and its configuration after the current scan
            session has completed successfully.
            [Optional, default = false]

       --scan-space-name or -s String
            The name of the scan space that the data will be saved to.
            If specified, a ScanSpace with this name will be created if not found.
            If not specified, information will be saved to the default ScanSpace.
            [Optional]