JarLock Documentation

JarLock is a super easy way to add a powerful layer of protection to applications running on the Java Virtual Machine.

Download
JarLock

Installation

JarLock runs as a Java Agent, and must be added to the JVM startup args.

Example Command

java -javaagent:/path/to/jarlock-1.x.x.jar -jar /path/to/myApp.jar

You can also pass a path to a jarlock.properties file in the java agent argument, like this:

java -javaagent:/path/to/jarlock-1.x.x.jar=/path/to/jarlock.properties -jar /path/to/myApp.jar
Installation Tip

The -javaagent argument must be first, before any other JVM args.

Using JAVA_TOOL_OPTIONS Environment Variable

One easy way to add a java agent to your application, that works pretty much everywhere is to set the JAVA_TOOL_OPTIONS environment variable.

JAVA_TOOL_OPTIONS=-javaagent:/path/to/jarlock-1.x.x.jar

You can also pass the properties file in via this argument or set a environment variable JARLOCK_CONFIG_FILE which points to the file.

Configuration Properties

Configuration properties can be specified in a jarlock.properties file or as environment variables.

The JarLock configuration properties can be placed in a properties file, and passed as an argument value to the -javaagent argument, like this:

-javaagent:/path/to/jarlock-1.x.x.jar=/path/to/jarlock.properties

Or you can specify an environment variable that points to the file:

JARLOCK_CONFIG_FILE=/path/to/jarlock.properties

Or you can pass each configuration property as its own environment variable. The loading of properties goes in this order: Agent Args, Environment Variable, then JARLOCK_CONFIG_FILE. This means that any property is overridden in the JARLOCK_CONFIG_FILE will have the final say.

Keep in mind that JarLock configuration is immutable at runtime. This means that once the agent has loaded with configuration, it cannot be changed until you restart the JVM.

General Configuration Properties

JARLOCK_CONFIG_FILE

When set as an environment variable specifies a path to a properties file which contain configuration. Ignored when present inside a properties file.

JARLOCK_LICENSE_KEY

The software license key, obtained by purchase or by requesting a trial key.

JARLOCK_BLOCK_ENABLED

Default: true
You can turn off blocking mode to test your application to see what would have been blocked.

JARLOCK_LOG_ENABLED

Default: true
Logging mode writes logs to a log file when things are blocked, or would be blocked if blocking mode is not enabled.

JARLOCK_LOG_VERBOSE

Default: false
Verbose Logging adds Stack Traces and additional info to the logs.

Common Java Features

JARLOCK_BLOCK_JAVA_DESERIALIZATION

Default: false
Blocks Java ObjectInputStream Deserialization. In addition to blocking class instantiation on Java 9 and above it will also set jdk.serialFilter to !* (blocking all deserialization) if it has not already been set to something else when the agent initializes.

JARLOCK_BLOCK_JAVA_SERIALIZATION

Default: false
Blocks Java ObjectOutputStream Serialization

JARLOCK_BLOCK_JNDI

Default: false
Blocks Java Naming and Directory Interface (JNDI) by preventing Contexts from being created.

JARLOCK_BLOCK_JSP_COMPILATION

Default: false
Blocks the compiling of JSP files, currently supports Apache/Tomcat's Jasper JSP Engine. Additional engines will be added in the future.

JARLOCK_BLOCK_RUNTIME_EXIT

Default: false
Blocks Calls to Java Runtime.exit() and related APIs which causes the java process to exit.

JARLOCK_BLOCK_CLASSES

Default: empty
A comma separated list of class names to block. You can specify a wildcard * at the beginning or the end of each entry, eg *.log4j.net.SocketAppender or *.log4j.net.* which can help account for shaded jars.

JARLOCK_TRUSTED_SOURCES

Default: empty
A comma separated list of classes which are Trusted and can bypass the restrictions of JarLock. This is useful for debugging issues, but use with caution. Wild cards are supported at the beginning or end of each entry. For example: com.example.trusted.*

You can limit the trust to a single method within a class like this: com.example.TrustedClass.trustedMethod() wild cards are supported in the beginning but not at the end in this case.

You can also trust source files by prefixing the entry with sourcefile: for example sourcefile:*/Trusted.cfc

The class names, method names and source file paths are case sensitive.

Warning: Use trusted sources with caution, it allows you to remove the protections of JarLock on certain classes and methods.

Process APIs

JARLOCK_BLOCK_PROCESS_CREATION

Default: false
Blocks calls to Java's ProcessBuilder as well as Runtime.exec

JARLOCK_BLOCK_PROCESS_DESTROY

Default: false
Blocks the Java api to kill a running process on the server.

JARLOCK_BLOCK_PROCESS_ENUMERATION

Default: false
Blocks Java apis that list processes running on the server.

JARLOCK_BLOCK_TOOLS

Default: false
Blocks several common known apis for accessing internal Java tools such as compiler and jar tool.

Network APIs

JARLOCK_ALLOW_ADDRESS_RESOLUTION

Default: *
Requires Java 18+ - Blocks DNS host address resolution requests that do not meet this allowed list. A comma separated list of allowed domains, or none to block all. Wildcards can be used at the beginning of a name, eg: *.example.com

JARLOCK_ALLOW_SOCKET_CONNECT

Default: *
Blocks outgoing (egress) network connections (Sockets) created by your Java Application. This typically includes all DB, and HTTP connections. It does not block all possible connections made by the jvm, for example DNS address resolution is not covered by this setting. Create a comma separated list of host:port,ip:port use * as a wildcard host/port.

Examples

JARLOCK_ALLOW_SOCKET_LISTEN=*:443,db.example.com:3306,127.0.0.1:*

JARLOCK_ALLOW_SOCKET_LISTEN

Default: *
Blocks creation of ServerSockets (used for listening, ingress) in your Java Application. If you are running tomcat with a HTTP connector running on port 8080, then you would want to add 127.0.0.1:8080 to the list. Create a comma separated list of host:port,ip:port use * as a wildcard host/port. Set to an empty value or none to block all, or * to allow all. The IP 0.0.0.0 is often used as a default listen binding, which binds to all IP address interfaces.

JARLOCK_ALLOW_DATAGRAM_SOCKET_CONNECT

Default: *
Blocks outgoing (egress) datagram network connections (DatagramSocket or MulticastSocket) created by your Java Application. This typically includes UDP. See also the JARLOCK_ALLOW_SOCKET_CONNECT setting. Create a comma separated list of host:port,ip:port use * as a wildcard host/port or none to block all.

JARLOCK_ALLOW_DATAGRAM_SOCKET_LISTEN

Default: *
Blocks bind calls on DatagramSocket. Allows for filtering of the SocketAddress via a list of allowed addresses in host/ip:port format.

CFML / ColdFusion Specific Configuration

If you do not use ColdFusion / Lucee you can ignore these settings.

JARLOCK_BLOCK_CFML_REMOTE_FUNCTIONS

Default: false
Blocks remotely calling Functions with access=remote on ColdFusion/Lucee via SOAP, URL, etc.

JARLOCK_BLOCK_CFML_REST

Default: false
Blocks the ColdFusion / Lucee REST Implementations. This would include components with restpath and remote functions. It does not prevent rest apis written in pure CFML (such as Taffy, or ColdBox Rest).

JARLOCK_BLOCK_CFML_DEV_SERVLETS

Default: false
Blocks Servlets which are not meant for production servers such as RDS, JSDebuggingServlet, and others.

JARLOCK_BLOCK_CFML_TAGS

Default: empty
Provide a list of CFML tags, such as cfexecute,cfregistry which will be blocked.

JARLOCK_BLOCK_CFML_FUNCTIONS

Default: empty
Provide a list of CFML functions, such as evaluate,iif which will be blocked.

Logging Configuration

Logging, when enabled uses the java.logging module.

JARLOCK_LOG_CONSOLE

Default: false
Outputs log messages to System.out / System.err

JARLOCK_LOG_FILE

Default: %t/jarlock.%g.log
When JARLOCK_LOG_ENABLED=true this setting denotes the path where the jarlock log file is written. Supports tokens defined by java.util.logging.FileHandler such as %t meaning the system temp directory. You can also set it to none or an empty string to disable writing logs to a file.

JARLOCK_LOG_FILE_APPEND

Default: false
When JARLOCK_LOG_ENABLED=true and JARLOCK_LOG_FILE is not none, this setting determines if the logs are appended to an existing log file or not.

JARLOCK_LOG_FILE_COUNT

Default: 5
When JARLOCK_LOG_ENABLED=true and JARLOCK_LOG_FILE is not none, this setting determines the number of log files to rotate between. Default: 5

JARLOCK_LOG_FILE_LIMIT

Default: 50000000
When JARLOCK_LOG_ENABLED=true and JARLOCK_LOG_FILE is not none, and JARLOCK_FILE_COUNT is greater than 1 this setting is the target size of the log file before rotating it. Default: 50000000 (50mb)

Example Configuration Files

Here are some example configuration files to get you started:

Strict Blocking Configuration

This configuration blocks a lot of potentially harmful things, but it may be too strict for some applications.

JARLOCK_LICENSE_KEY=your-key
JARLOCK_LOG_FILE=/var/log/jarlock.%g.log
JARLOCK_LOG_ENABLED=true
JARLOCK_LOG_VERBOSE=true
JARLOCK_BLOCK_ENABLED=true
JARLOCK_LOG_CONSOLE=true

JARLOCK_BLOCK_JAVA_SERIALIZATION=true
JARLOCK_BLOCK_JAVA_DESERIALIZATION=true

JARLOCK_BLOCK_PROCESS_CREATION=true
JARLOCK_BLOCK_PROCESS_DESTROY=true
JARLOCK_BLOCK_PROCESS_ENUMERATION=true

JARLOCK_BLOCK_RUNTIME_EXIT=true

JARLOCK_BLOCK_TOOLS=true

JARLOCK_BLOCK_JNDI=true

JARLOCK_ALLOW_ADDRESS_RESOLUTION=none
JARLOCK_ALLOW_SOCKET_LISTEN=none
JARLOCK_ALLOW_SOCKET_CONNECT=none
JARLOCK_ALLOW_DATAGRAM_SOCKET_LISTEN=none
JARLOCK_ALLOW_DATAGRAM_SOCKET_CONNECT=none

JARLOCK_BLOCK_JSP_COMPILATION=true

#ColdFusion / CFML
JARLOCK_BLOCK_CFML_FUNCTIONS=evaluate,iif
JARLOCK_BLOCK_CFML_TAGS=cfexecute,cfregistry
JARLOCK_BLOCK_CFML_REMOTE_FUNCTIONS=true
JARLOCK_BLOCK_CFML_DEV_SERVLETS=true
JARLOCK_BLOCK_CFML_REST=true

Trusted Sources for Maven Surefire

Maven Surefire will fork the JVM process and tries to call Runtime.exit(), which you may have blocked. You can add Trusted Sources to your config to allow this code to exit the JVM. 

JARLOCK_TRUSTED_SOURCES=org.apache.maven.surefire.booter.ForkedBooter.acknowledgedExit(),org.apache.maven.surefire.booter.ForkedBooter.exit1()

Agent Installation Tips

ColdFusion Installation

To install JarLock on an Adobe ColdFusion server, locate the jvm.config file, typically located in the bin directory of your ColdFusion instance. For example the default instance on a Windows server might be located at c:\ColdFusion2023\cfusion\bin\jvm.config

Make a backup of the jvm.config file before editing it. The locate the line that starts with java.args

java.args=-server ...

Insert the -javaagent argument at the beginning of the args, directly after the equals sign:

-javaagent:c:/jarlock/jarlock-agent-1.0.0.jar=c:/jarlock/jarlock.properties -server ...