How to Configure the Microagent

Though Protect's Microagent can be run using its default settings, you may choose to configure the Microagent for use specifically in your environment.

Ways to Configure the Microagent

There are three ways to configure the Microagent:

  1. Modifying the ShiftLeft Configuration file

  2. Setting and using Java System Properties

  3. Setting and using environment variables

Java System Properties override any options set in ShiftLeft's configuration file, while environment variables override both Java System Properties and any options set in ShiftLeft's configuration file.

The ShiftLeft Configuration file

The shiftleft.json configuration file is automatically generated by Inspect whenever it analyzes your code. You can pass it to the Microagent using the $SHIFTLEFT_CONFIG environment variable or the Dshiftleft.config Java System Property. If you do not provide any arguments, the Microagent uses the shiftleft.json file in the working directory.

Java System Properties

You can configure the Microagent by setting Java System Properties that you specify as arguments to your JVM commands:

-D${prop-name}=${prop-value}

For example, you can set the debug level for logging using Java System Properties as follows:

java -javaagent:sl-microagent-x.y.z.jar -Dshiftleft.log.level=DEBUG -jar /hello-shiftleft-x.y.z.jar

Environment Variables

You can configure the Microagent using the environment variables passed to JVM by its parent process:

SHIFTLEFT_PROP_NAME="prop-value"

For example, you can use the SHIFTLEFT_CONFIG environment variable to pass the path of the ShiftLeft configuration file to the Microagent:

SHIFTLEFT_CONFIG=<path>/shiftleft.json sl run

If you would like to save your environment variables locally so that you don't have to redefine them with each use, you can do so as follows:

export SHIFTLEFT_CONFIG=<path>/shiftleft.json
SHIFTLEFT_CONFIG sl run

Configurable Microagent Options

The following are the Microagent options that you can change by modifying the ShiftLeft configuration file, Java System Properties, or environment variables.

HTTPS Proxy

The Microagent supports the https_proxy environment variable, which you can use to configure an HTTPS proxy.

export https_proxy="https://[$user:$password@]$host:$port"

Log

The Microagent allows you to set the amount of detail you want the logger to output, the file pattern name for your log files, the number of rolling files in a set of logs, and the file size for your logs.

Example from the ShiftLeft configuration file:

"log": {
"level": "TRACE",
"file": "",
"maxFiles": 5,
"maxFileBytes": 10000000
}

Log Level

The log level determines the amount of detail that Microagent includes in your log output.

Method

Parameter

Configuration File

log.level

log.level

Java System Properties

-Dshiftleft.log.level

Environment Variable

SHIFTLEFT_LOG_LEVEL

Accepted Values:

Log Level

Description

TRACE

Finest level; useful for technical debugging. Not recommended for use in Production environments

DEBUG

Detailed level; useful for debugging. Not recommended for use in Production environments

INFO

Reasonable informative level. Returns information relevant to the user

WARNING

Warnings only

ERROR

Errors only

QUIET

Default. Does not create log files; logs are redirected to the application stderr

Log Files

Denotes the file name pattern for a rolling set of log files that are written to the file system. If you don't specify a value, the Microagent redirects logs to the target application stderr.

Method

Parameter

Configuration File

log.file

Java System Properties

-Dshiftleft.log.file

Environment Variable

SHIFTLEFT_LOG_FILE

Rolling Log Files

Used to set the number of files used in a set of rolling files. This parameter is needed only if you log to the file system. Accepts integer values

Method

Parameter

Configuration File

log.maxFiles

Java System Properties

-Dshiftleft.log.max.files

Environment Variable

SHIFTLEFT_LOG_MAX_FILES

Log File Size

Limits the log file size (in bytes). This parameter is needed only if you log to the file system. Accepts integer values

Method

Parameter

Configuration File

log.maxFileBytes

Java System Properties

-Dshiftleft.log.max.file.bytes

Environment Variable

SHIFTLEFT_LOG_MAX_FILE_BYTES

Proxy

Proxy configuration settings determine how the Microagent communicates with ShiftLeft.

"slProxy": {
"host": "agentproxy.stg.shiftleft.io",
"port": 443,
"certificate": "*"
}

Host Name

Sets the host name/IP address for the proxy.

Method

Parameter

Configuration File

slProxy/host

Java System Properties

-Dshiftleft.sl.proxy.host

Environment Variable

SHIFTLEFT_SL_PROXY_HOST

Port

Sets the TCP port on which the Proxy listens.

Method

Parameter

Configuration File

slProxy/certificate

Java System Properties

-Dshiftleft.sl.proxy.certificate

Environment Variable

SHIFTLEFT_SL_PROXY_CERTIFICATE

Certificate

The proxy certificate to trust.

Method

Parameter

Configuration File

slProxy/port

Java System Properties

-Dshiftleft.sl.proxy.port

Environment Variable

SHIFTLEFT_SL_PROXY_PORT

Accepted Values:

Value

Description

No certificate provided

The proxy certificate chain will be validated using the agent's root certificates (CA)

*

No certificate validation performed. The connection is encrypted, but the proxy identity won't be verified (useful for cases where proxy host name is an IP address)

Certificate provided

Certificate is trusted

Security

The following security-related settings configure the Microagent's detection and blocking capabilities.

Mode

The security mode determines how the Microagent handles attacks (or malicious external payloads).

Method

Parameter

Configuration File

sec.mode

Java System Properties

-Dshiftleft.sec.mode

Environment Variable

SHIFTLEFT_SEC_MODE

Accepted Values:

Mode

Description

REPORT

Default. The Microagent reports the detected attacks, but does not make any changes to you application's behavior

BLOCK

The Microagent reports the attack and blocks your application from executing (by throwing a java.lang.SecurityException) if attacks are found

XXE

Determines the type of protection against [external entity injection (XXE)](https://owasp.org/www-community/vulnerabilities/XML_External_Entity_(XXE)_Processing ) to adopt when parsing XML documents coming from non-trusted origins.

Method

Parameter

Configuration File

sec.xxe

Java System Properties

-Dshiftleft.sec.xxe

Environment Variable

SHIFTLEFT_SEC_XXE

Accepted Values:

Value

Description

OFF

Default. No protection against XXE

DTD

Disable DTDs; prevents XXE attacks, including denial of services attacks (e.g., Billion Laughs)

External

Disables external DTDs and entities. Protects against XXE attacks, but not denial of services attacks (e.g., Billion Laughs)

Collect Attack Information

Enables collection of full payloads of attack events. Data may contain sensitive information (though it is encrypted before storage).

Method

Parameter

Configuration File

sec.collect.attack.info

Java System Properties

-Dshiftleft.sec.collect.attack.info

Environment Variable

SHIFTLEFT_SEC_COLLECT_ATTACK_INFO

Accepted Values:

Value

Description

true

Attack payloads collected and sent to ShiftLeft's infrastructure for viewing in the Vulnerability Dashboard Event Viewer

false

Default. No attack payloads collected

Strictness

Strictness determines how to Microagent performs if it loses connection with the Proxy Server.

Strictness

Description

false

Proxy availability not required. Event notifications may be lost, but the application can run uninstrumented

true

The Microagent blocks all interactions with the Proxy until the connection is reestablished

By default, the Microagent is set to non-strict (that is, strict is set to false).

Method

Parameter

Value

Configuration File

strict

"strict": true or "strict": false

Java System Properties

-Dshiftleft.strict

-Dshiftleft.strict=true or -Dshiftleft.strict=false

Environment Variable

SHIFTLEFT_STRICT

SHIFTLEFT_STRICT=true or SHIFTLEFT_STRICT=false