The ShiftLeft Microagent is run with an application that has been analyzed by ShiftLeft. The Microagent runs alongside the application in production (or other environments such as staging, test, UAT).
To run the ShiftLeft microagent, you must:
Use a supported 64-bit JVM
Analyze the application beforehand OR pass in
--analyze <path.jar> flag to perform analysis before running the application. If analyzed beforehand, include the
shiftleft.json file (that was generated during analysis) with the target application you are deploying, or specify the
SHIFTLEFT_CONFIG environment variable that points to the path for this file.
Before running the Microagent, analysis of the target application must be performed. This allows ShiftLeft to generate instrumentation custom tailored to the specific version of the application that is run.
Performing analysis can be performed either as a separate step, allowing installation in a build / Continuous Integration (CI) environment, or in the same command used for running the agent itself.
To perform analysis beforehand, see Analyzing Applications in CI. Note that in this case, you will need to carry the produced
shiftleft.json file to your runtime environment and make it available to the ShiftLeft Microagent. This allows the Microagent to associate the application to be run with the analysis.
To perform analysis in the same command as running the agent, pass the
--analyze flag to the
sl run command as shown below. The system will then submit the application to the cloud for analysis, wait for it to finish, then run the application with the Microagent installed. Subsequent runs of the same command, with the same version of the application will start immediately with the Microagent installed, as the analysis is only performed the first time.
sl run [--analyze <file.jar> --app myapp] -- <command> to run a target application with the ShiftLeft Microagent:
sl run --analyze target/hello-shiftleft-0.0.1.jar --app hello-shiftleft -- java -jar target/hello-shiftleft-0.0.1.jar
sl run -- sbt run
The command performs the following tasks:
--analyze <file.jar> flag was provided, it checks with the ShiftLeft server whether analysis of this version of the application was performed before. If it was not, it performs analysis in the cloud and waits for it to complete. If this flag is not passed, then the agent will look for the
shiftleft.json file which resulted from performing analysis ahead of time. **Note: if you are a current ShiftLeft user and you plan to use the
--analyze option here, please ensure that you have authenticated yourself to your ShiftLeft tenant using
sl auth (see Authenticating with ShiftLeft).
If not already at the latest version, it downloads the latest Microagent to a local directory.
It runs the
<command> with a certain environment variable set, which instructs the JVM to load the Microagent.
Before the application code is triggered, the Microagent connects to the ShiftLeft Proxy server to fetch the SPR (Security Profile for Runtime) that results from analysis.
sl run process is a wrapper around the target Java application process. The
sl run process spawns the target application process as a child. When you deploy your application using
sl run, you will see two processes: the parent (
sl run) and the child (application).
If wrapping your application command line with
sl run is not an option for you, then it is possible to instruct the JVM to load the ShiftLeft Microagent via the Java flag
Note that passing the
javaagent flag directly skips the ShiftLeft's Microagent's auto-update mechanism. In this situation, we strongly recommend running this command
sl update java-agent
every time, before starting the application, to ensure that you have the latest version. Also, use the
~/.shiftleft/sl-microagent-latest.jar symlink, which points to the latest downloaded version of the ShiftLeft Microagent.
# Optionally analyze app (if not analyzed before)sl analyze --wait --app example-app exampleapp.jar# Auto-update ShiftLeft Microagent.sl update java-agent# Run application with ShiftLeft Microagent.java -javaagent:~/.shiftleft/sl-microagent-latest.jar -jar exampleapp.jar
The ShiftLeft Microagent is a lightweight agent that runs in-memory within the JVM of each app you want to monitor and protect using ShiftLeft. Once started, the microagent periodically pushes runtime data and metrics to the proxy server.
--analyze flag was not provided, the microagent requires the
shiftleft.json file that is generated during analysis. The
shiftleft.json file contains the License and SPR ID which are required parameters that must be passed using the
By default the microagent expects the
shiftleft.json file to be in the working directory where you run the application. If you are running the application in an environment different from where you performed analysis, copy
shiftleft.json to the working directory where the application is run.
Alternatively you can set the
SHIFTLEFT_CONFIG environment variable to pass in the path to the
shiftleft.json file. For example:
There are various ways to confirm that the ShiftLeft Microagent is running.
As shown below, when the microagent is connected you will see this reflected in the App Card as "X Instances." If you don't see this, check the microagent command output.
In addition, runtime metrics and throughput data will appear at the App Summary screen for a selected application. For example:
sl run command is a wrapper around the target Java application process. The
sl run process spawns the target application process as a child process. So, when you deploy your application using
sl run, you will see two Java processes: the parent
sl run process and the child
When you run the microagent and it connects to the ShiftLeft Proxy server, you will see a success message similar to the following in the microagent output:
- ------------------------------<< ShiftLeft Microagent (0.4.0)- ------------------------------<< 2018-02-05 11:20:01.257 INFO 1 Starting ShiftLeft Microagent...<< 2018-02-05 11:20:01.354 INFO 6 Connecting to ShiftLeft Proxy server at agentproxy.shiftleft.io:443 (TLS enabled. ShiftLeft Proxy certificate validated via root CAs)<< 2018-02-05 11:20:03.415 INFO 6 Requesting application SPR (non-strict mode)<< 2018-02-05 11:20:05.205 INFO 9 Obtained SPR
The ShiftLeft Microagent for Java runs out-of-the-box with default settings. See Configuring the Microagent for details on configuration options.