Spring Boot アプリケーションの保護

springboot は Spring Boot アプリケーションを保護し、BOOT-INF/classes、BOOT-INF/lib、Spring Boot Loader、フレームワークのスキャンを扱います。

1. GUI での操作

  1. アプリケーションの種類のページで Spring Boot を選びます。

    Spring Boot を選ぶ

  2. 保護する Spring Boot アプリケーション、同梱する Java バージョン、ターゲットプラットフォームを選び、シンプルモードか詳細設定モードかを選びます。

    入力、Java バージョン、ターゲットプラットフォーム、モードを選ぶ

  3. 詳細設定モードでは、出力レイアウト、保護する依存 JAR、JavaFX の設定、JVM スタートアップオプション、除外ルールを選びます。シンプルモードでは、レイアウトと除外を互換性スキャンの結果から決めます。各オプションの意味は Protector4J 詳細設定モードを参照してください。

    Spring Boot の詳細オプションを設定する

  4. 出力ディレクトリを選び、サマリーを確認して保護を実行をクリックします。

    出力ディレクトリを選んで保護を実行する

2. CLI の例

最も短い形：

p4j springboot app.jar dist

既定では p4jx-fat レイアウトを使います。別のレイアウトを明示的に選ぶ場合：

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

アプリケーションの一部だけを保護する場合：

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

3. 出力の構成とレイアウト

p4jx-fat：既定のレイアウト、単一の保護済みアーカイブ

dist/
├── app.p4jx              # jar アーカイブサフィックスを使うと app.jar
├── vlxjre/
├── run.sh
├── run.command
└── run.bat

特徴：

  • アプリケーション全体が 1 つの P4JX アーカイブとして配布されます。
  • 物理ファイルは既定では ZIP ではありません。
  • Spring Boot のリソース、ネストした依存関係、メタデータは仮想 JAR ビュー経由で提供されます。
  • 保護範囲がもっとも広く、サードパーティのクラスパススキャナに依存しないアプリケーションに向いています。

fat：Spring Boot 互換レイアウト

dist/
├── app.jar
├── app.p4jx              # jar サフィックスを使うと app-protected.jar
├── vlxjre/
└── run.*

特徴：

  • app.jar は標準的な BOOT-INF の物理構造を保ちます。
  • 保護対象クラスの実際の実装は、隣にある P4JX アーカイブに入ります。
  • ClassGraph や Reflections を使うなど、物理的な Spring Boot JAR の構造をスキャンする必要があるアプリケーションに向いています。
  • 2 つのファイルは互いに依存するため、必ず一緒に更新し、一緒に配布してください。

separate：分割型の互換レイアウト

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

特徴：

  • Spring Boot Loader、保護していないクラス、依存関係を分けて配置します。
  • lib/* のフラットなクラスパスを必要とする、古い連携環境に向いています。
  • 保護対象クラスは、生成されたランチャーが事前に読み込みます。
  • 新規プロジェクトでは p4jx-fat、またはスキャナが推奨する p4jx-fat / fat を選んでください。

レイアウトの選び方

状況推奨レイアウト
標準的な Spring Boot サービスp4jx-fat
ClassGraph や Reflections などのスキャナを実際に使っているfat
外部依存をフラットなディレクトリに置きたい、または依存ファイルを個別に暗号化したいseparate
判断がつかないまず --compat-scan を実行

ZIP オーバーレイが助けになるのは、ZIP の中央ディレクトリを直接読むツールだけです。ClassLoader やクラスパススキャナが必要とする物理的な Spring Boot 構造の代わりにはなりません。

4. 起動

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

Windows：

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

出力ディレクトリの vlxjre をシステムの JRE で置き換えないでください。

Windows 向けにパッケージングする場合は、ネイティブランチャーも生成できます。3 つのレイアウトすべてに対応し、起動スクリプトと併存します。詳細は Windows EXE ランチャーの生成を参照してください。

JVM スタートアップオプション

パッケージング時にオプションを固定できます。GUI の JVM スタートアップオプションで 1 行に 1 つ入力するか、コマンドラインで指定します。

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

配備済みパッケージに対して、その回だけオプションを足す場合：

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

配備済みのスクリプトを直接編集することもできます。

  • macOS と Linux：run.sh で、生成された JVM_OPTS=(...) と JVM_OPTS+=(...) の後に JVM_OPTS+=("-Xms1g" "-Xmx2g") を追加します。
  • Windows：run.bat で、生成された set "JVM_OPTS=..." の後に set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g" を追加します。

パッケージャーが Spring Boot や JavaFX のために生成した --add-opens やモジュールパスなどのオプションは削除しないでください。再パッケージングすると手動の変更はすべて上書きされます。詳細は JVM スタートアップオプションを参照してください。

5. 保護範囲

既定では BOOT-INF/classes 配下のアプリケーションクラスを保護します。次のような Spring 関連のクラスは、保護しないままにしておくほうが安全です。

  • @Controller、@RestController、@ControllerAdvice のクラス
  • @Configuration クラス、自動構成クラス、AOT や CGLIB で拡張されたクラス
  • Jackson の DTO、JPA エンティティ、レコード、バリデーション用モデル
  • アプリケーションのエントリポイント、およびフレームワークが直接生成・プロキシするクラス
  • 実行時にバイトコード拡張が必要なクラス

サービスの実装を保護し、公開されたファサードやインターフェイス経由で利用してください。ルールでは、完全なクラス名のほか pkg.* と pkg.** が使えます。

6. 依存 JAR の保護

--protect-lib は BOOT-INF/lib の中で条件に一致する依存関係を保護します。3 つのレイアウトすべてで使えます。

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

保護するのは自社のクローズドソースの依存関係だけにしてください。「保護を増やしたい」という理由で、Spring、Tomcat、ロギングライブラリ、データベースドライバーといったサードパーティのフレームワークを暗号化してはいけません。

7. 互換性スキャン

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

この 2 つのオプションは同時に使えません。違いは次のとおりです。

オプション動作使いどころ
--compat-scan入力 JAR をスキャンし、リスクと設定の推奨を表示して終了します。エンコードは行わず dist も生成しないため、出力ディレクトリは不要です。初めて保護するとき、Spring Boot やその他の依存関係を更新したあと、保護範囲やレイアウトを変えたあと、互換性の問題を調べるときに、まずレポートを確認します。
--compat-applyスキャン後に保守的な推奨設定を取り込み、そのままエンコードして出力します。そのため出力ディレクトリが必要です。スキャン結果を確認して推奨設定を受け入れたあと、パッケージングを仕上げるときに使います。ルールが検証済みの繰り返しビルドや CI にも適します。

springboot では、--compat-apply はスキャン結果にもとづいてレイアウトを選び、除外ルールを追加し、スキャナ ZIP オーバーレイ、JavaFX、アーカイブサフィックスなどを調整できます。除外ルール以外については、コマンドラインで明示した値が優先されます。推奨される除外は、既定で明示した --exclude にマージされます。自動追加を望まない場合は --no-compat-excludes も一緒に指定してください。スキャナは静的なヒューリスティック解析のみを行うため、ソース修正が必要な問題は --compat-apply では解決されず、パッケージング後もターゲットプラットフォームでの回帰テストが必要です。

その他の CLI コマンド、全オプション、環境変数、自動化の例は CLI リファレンスを参照してください。