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.
    Starting the Interactive Shell 
    $ sudo su
$ systemctl stop codelogic-java
$ cd /opt/codelogic/java
$ ./run_agent.sh
    List of available commands 
    codelogic-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 
    codelogic-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 
    codelogic-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,the semantic name is its 'identity' minus the 'grouping:' prefix.
            Identities for items may be found in the 'Item Details' page of the CodeLogic UI.
            [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: '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]

       --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 CodeLogic 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]