Protection for Spring Boot applications

springboot is used to protect Spring Boot applications and can handle BOOT-INF/classes, BOOT-INF/lib, Spring Boot Loader, and framework scanning.

1. GUI operations

  1. Select Spring Boot on the application type page.

    Select Spring Boot

  2. Choose the Spring Boot application to be protected, The included Java version, and the target platform, then select either simple mode or advanced mode.

    Select input, Java version, target platform, and mode

  3. When using advanced mode, select the output layout, protected dependency JARs, JavaFX, JVM parameters, and exclusion rules as needed; simple mode will automatically suggest layouts and exclusions based on the compatibility scan. For the meaning of each option, see Protector4J Advanced Mode Settings.

    Configure advanced Spring Boot parameters

  4. Select the output directory, review the parameter summary, and then click Run protection.

    Select the output directory and perform protection on the protected application.

2. CLI examples

Minimum command:

p4j springboot app.jar dist

The p4jx-fat layout is used by default. To explicitly select another layout:

p4j springboot app.jar dist --layout fat
p4j springboot app.jar dist --layout separate

Selective protection:

p4j springboot app.jar dist \
  --protect 'com.example.service.impl.**' \
  --exclude 'com.example.dto.**,com.example.config.**'

3. Output structure and layout

p4jx-fat: Default, for archiving a single protected application

dist/
├── app.p4jx              # It becomes app.jar when using the jar archive suffix
├── vlxjre/
├── run.sh
├── run.command
└── run.bat

Features:

  • Delivered as an archive of a single P4JX application
  • Physical files are not ZIP by default;
  • Spring Boot resources, nested dependencies, and metadata are provided through a virtual JAR view;
  • It offers the widest protection scope, making it suitable for applications that do not rely on third-party classpath scanners.

fat: Spring Boot compatibility layout

dist/
├── app.jar
├── app.p4jx              # When using the jar suffix, it becomes app-protected.jar
├── vlxjre/
└── run.*

Features:

  • app.jar retains the standard physical structure of BOOT-INF;
  • The actual implementation of the protected classes is located in the adjacent P4JX archive;
  • Suitable for applications such as ClassGraph and Reflections that require scanning the physical Spring Boot JAR structure;
  • The two files are interdependent and must be updated and delivered together.

separate: Separated compatibility layout

dist/
├── plain-launcher.jar
├── app.p4jx
├── lib/
├── vlxjre/
└── run.*

Features:

  • Separation of Spring Boot Loader, public classes, and dependencies;
  • Suitable for older integration environments that require a flat classpath of lib/*;
  • Protected classes are preloaded by the generated starter;
  • New projects should prefer to use p4jx-fat or fat recommended by the scanner.

How to Choose a Layout

ScenariosRecommended Layouts
Standard Spring Boot Servicesp4jx-fat
When the application actually uses scanners such as ClassGraph and Reflectionsfat
When a flat external dependency directory is required, or when dependency files need to be encrypted separatelyseparate
UncertainExecute --compat-scan first

ZIP overlay only assists tools that directly read the central directory of a ZIP file; it cannot replace the physical Spring Boot structure required by ClassLoader/classpath scanners.

4. Launch

./run.sh --spring.profiles.active=prod

Windows:

run.bat --spring.profiles.active=prod

Do not use the system JRE in place of vlxjre in the output directory.

When packaging for Windows targets, a native launcher can also be generated additionally. All three layout types are supported, and it coexists with the launch script, as detailed in Generate a Windows EXE launcher.

JVM startup parameters

During packaging, JVM parameters can be fixed via the GUI’s JVM startup options (one per line) or via the CLI:

p4j springboot app.jar dist \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

Temporarily add them during deployment:

APP_JAVA_OPTS="-Duser.timezone=Asia/Shanghai" ./run.sh

The current deployment script can also be modified directly:

  • macOS/Linux: Append JVM_OPTS+=("-Xms1g" "-Xmx2g") after JVM_OPTS=(...)/JVM_OPTS+=(...) that have been generated from run.sh.
  • Windows: Append set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g" after set "JVM_OPTS=..." that has been generated from run.bat.

Do not delete internally generated files such as --add-opens and module path created by Spring Boot or JavaFX. Repackaging will overwrite any manual modifications; see JVM startup parameters configuration for details.

5. Protection scope

By default, it protects the application classes under BOOT-INF/classes. It is recommended to keep the following Spring-related classes as regular classes:

  • @Controller, @RestController, @ControllerAdvice;
  • @Configuration, auto-configuration classes, and AOT/CGLIB enhanced classes;
  • Jackson DTOs, JPA Entities, records, and validation models;
  • Application entry points and classes directly constructed/proxied by the framework;
  • Classes that require runtime bytecode enhancement.

Implementation of protection services, accessed through public facades or interfaces. Rules support exact class names, as well as pkg.* and pkg.**.

6. JAR files that are part of the protection dependencies.

--protect-lib can protect matching BOOT-INF/lib dependencies; all three deployment layouts are supported.

p4j springboot app.jar dist \
  --protect-lib 'company-core-*.jar,pricing-*.jar'

Only protects proprietary, closed-source dependencies. Do not encrypt third-party framework packages such as Spring, Tomcat, logging tools, or database drivers for the purpose of “Provide better protection”.

7. Compatibility scan.

p4j springboot app.jar --compat-scan
p4j springboot app.jar dist --compat-apply

These two options cannot be used simultaneously; their differences are as follows:

OptionsBehaviorWhen to use
--compat-scanIt only scans the input JAR, prints risks and configuration suggestions, and then exits; it does not encode or generate dist, so there is no need for an output directory.Use this first to view reports after initially protecting an application, upgrading Spring Boot or other dependencies, adjusting the protection scope or layout, or troubleshooting compatibility issues.
--compat-applyIt automatically combines conservative suggestions after scanning, then proceeds with encoding and generating outputs, so an output directory must be specified.Use this to complete packaging after reviewing the scan results and accepting the automatic suggestions; it can also be used for repeated builds with verified rules or in CI workflows.

For springboot and --compat-apply, you can select a layout based on the scan results, add exclusion classes, and adjust options such as ZIP overlay, JavaFX, and archive suffix. For options other than exclusion classes, the values explicitly specified in the command line take precedence; the suggested exclusion classes are merged with the explicitly specified --exclude by default. If you do not want exclusion classes to be added automatically, you can pass --no-compat-excludes at the same time. The scanner performs only static heuristic analysis, and issues requiring code modifications will not be automatically fixed by --compat-apply; regression testing on the target platform is still required after generation.

For other CLI commands, all options, environment variables, and automation examples, please refer to CLI Parameters Reference.