Skip to content

Executing Agents Interactively via the CLI

The CodeLogic 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/codelogic/java/run_agent.sh and /opt/codelogic/sql/run_agent.sh. The Windows CLI is in C:\Program Files (x86)\CodeLogic\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 ID on a Linux system, the default permissions of the /opt/codelogic 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. It will appear in Administration>Agents.

  • Start the Interactive Shell.
sudo su  
systemctl stop codelogic-java  
cd /opt/codelogic/java  
java -Dspring.profiles.active=interactive -jar cc-java-agent-main.jar

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

cd "C:\Program Files (x86)\CodeLogic\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 codelogic-java  
cd /opt/codelogic/java  
./run_agent.sh

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

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

  • Authorize the Interactive Agent.

    • Every agent must be authorized before it will communicate with the CodeLogic Server. The interactive agent will output a reminder.
    # ./run_agent.sh  

…  

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. 

      # ./run_agent.sh  

…  
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.codelogic.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 the Codelogic Server.

Sample output (Analyzing a JAR Interactively)

Note

Timestamps are omitted and blank lines are inserted for clarity.

codelogic-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/codelogic/java/codelogic-tmp/analysis-results/codelogic\_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 appear in your CodeLogic Server.

  • Interactive Shell Help

    • The interactive shell has a help facility. The default destination for an analysis is the CodeLogic Server. 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.
    List of available commands 
    $ sudo su  
$ systemctl stop codelogic-sql  
$ cd /opt/codelogic/sql  
$ java -Dspring.profiles.active=interactive -jar cc-sql-agent-main.jar  
…  
codelogic-java:>help  


AVAILABLE COMMANDS  

Agent Management 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.  
Analysis Commands  
analyze:  
Analyze java artifacts on demand. this command requires parameters be passed in interactive of commandline mode. Values from the agent configuration are ignored.  
run-analysis:  
Analyze java artifcacts from the currently configured agent configuration.  

Built-In Commands  
clear: Clear the shell screen.  
exit, quit: Exit the shell.  
help: Display help about available commands.  
script: Read and execute commands from a file.  
stacktrace: Display the full stacktrace of the last error.
    Help for the agent-register command 
    codelogic-java:>help agent-register  


NAME  
agent-register -  
Retrieve agent credentials after approval or force re-registration of this agent.  

SYNOPSYS  
agent-register[-f]  

OPTIONS  
-f or --force  
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 
    codelogic-java:>help analyze  


NAME  
analyze - Analyze an archive by decomposing its constituent parts.  

SYNOPSYS  
analyze [[-t] string][[-f] string][[-o] string][[-r] string]  

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

-p or --path  
A comma-separated list of absolute filepaths to analyze or scan.  
[Optional, default = <none>]  

-o or --outputstring  
'API' - send results to the api for processing.  
'FILE' - write results to json files in the auxiliary directory.  
'PRINT - print results to console (not recommended).  
[Optional, default = API]  

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