Package io.jguard.gradle.policy

Class JGuardPolicyExtension

java.lang.Object
io.jguard.gradle.policy.JGuardPolicyExtension
public abstract class JGuardPolicyExtension extends Object
Configuration extension for the jGuard policy plugin.

Example usage in build.gradle: 

 jguardPolicy {
     sourceFile = file("src/main/jguard/module-info.jguard")
     outputDir = layout.buildDirectory.dir("generated/jguard")
     mode = "strict"  // strict, permissive, or audit
 }

Run with agent: ./gradlew runWithAgent

Properties:

  • -Pjguard.skip=true - Skip agent enforcement
  • -Pjguard.mode=audit - Override enforcement mode

JSON Output: The Gradle plugin only generates binary policy files (.bin). For JSON output (useful for debugging or documentation), use the jGuard CLI: 

 jguardc --json -o policy.json src/main/java/module-info.jguard

  • Constructor Summary

    Constructors
    Constructor
    Description
    JGuardPolicyExtension()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract org.gradle.api.provider.Property<Boolean>
    getAllowTrusted()
    Whether to allow trusted modules.
    abstract org.gradle.api.provider.Property<Boolean>
    getAllowUnsignedPolicies()
    Whether to allow policies from unsigned JARs during discovery.
    abstract org.gradle.api.provider.Property<String>
    getBinName()
    The name of the binary policy file.
    abstract org.gradle.api.provider.Property<Boolean>
    getDiscoveryMode()
    Whether to use policy discovery mode (automatic policy detection from JARs).
    abstract org.gradle.api.provider.Property<Boolean>
    getExternalPoliciesIncludeJson()
    Whether to generate JSON alongside binary for external policies (for debugging).
    abstract org.gradle.api.file.DirectoryProperty
    getExternalPoliciesOutputDir()
    The output directory for compiled external policy .bin files.
    abstract org.gradle.api.file.DirectoryProperty
    getExternalPoliciesSourceDir()
    The source directory containing external policy .jguard files.
    abstract org.gradle.api.provider.Property<Boolean>
    getHotReload()
    Whether to enable policy hot reload.
    abstract org.gradle.api.provider.Property<Integer>
    getHotReloadInterval()
    The interval in seconds between policy file checks when hot reload is enabled.
    abstract org.gradle.api.provider.Property<Boolean>
    getIncludeJson()
    Whether to generate a JSON representation alongside the binary.
    abstract org.gradle.api.provider.Property<String>
    getJarPath()
    The path within the JAR where policy files are placed.
    abstract org.gradle.api.provider.Property<String>
    getJsonName()
    The name of the JSON policy file.
    abstract org.gradle.api.provider.Property<String>
    getLogLevel()
    The log level for the agent.
    abstract org.gradle.api.provider.Property<String>
    getMode()
    The enforcement mode for the agent.
    abstract org.gradle.api.file.DirectoryProperty
    getOutputDir()
    The output directory for compiled policy files.
    abstract org.gradle.api.file.RegularFileProperty
    getSourceFile()
    The source policy descriptor file.
    abstract org.gradle.api.file.DirectoryProperty
    getTestPoliciesOutputDir()
    The output directory for compiled test policy .bin files.
    abstract org.gradle.api.file.DirectoryProperty
    getTestPoliciesSourceDir()
    The source directory containing test-specific policy .jguard files.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • JGuardPolicyExtension

      public JGuardPolicyExtension()

  • Method Details

    • getSourceFile

      public abstract org.gradle.api.file.RegularFileProperty getSourceFile()
      The source policy descriptor file.

      Default: src/main/jguard/module-info.jguard

    • getOutputDir

      public abstract org.gradle.api.file.DirectoryProperty getOutputDir()
      The output directory for compiled policy files.

      Default: build/generated/jguard/

    • getIncludeJson

      public abstract org.gradle.api.provider.Property<Boolean> getIncludeJson()
      Whether to generate a JSON representation alongside the binary.

      Default: false

      Note: JSON output is disabled by default because the required Jackson library is excluded from the plugin to avoid JPMS conflicts in Gradle buildSrc. For JSON output, use the jGuard CLI (jguardc --json).

    • getBinName

      public abstract org.gradle.api.provider.Property<String> getBinName()
      The name of the binary policy file.

      Default: policy.bin

    • getJsonName

      public abstract org.gradle.api.provider.Property<String> getJsonName()
      The name of the JSON policy file.

      Default: policy.json

    • getJarPath

      public abstract org.gradle.api.provider.Property<String> getJarPath()
      The path within the JAR where policy files are placed.

      Default: META-INF/jguard

    • getMode

      public abstract org.gradle.api.provider.Property<String> getMode()
      The enforcement mode for the agent.

      Valid values: strict, permissive, audit

      Default: strict

    • getLogLevel

      public abstract org.gradle.api.provider.Property<String> getLogLevel()
      The log level for the agent.

      Valid values: error, warn, info, debug, trace

      Default: info

    • getDiscoveryMode

      public abstract org.gradle.api.provider.Property<Boolean> getDiscoveryMode()
      Whether to use policy discovery mode (automatic policy detection from JARs).

      When enabled (the default), the agent discovers policies from all module JARs on the classpath instead of loading a single policy file. This works for both single-module and multi-module JPMS applications.

      Set to false to use explicit single-module mode where the compiled policy file is passed directly to the agent.

      Default: true

    • getAllowUnsignedPolicies

      public abstract org.gradle.api.provider.Property<Boolean> getAllowUnsignedPolicies()
      Whether to allow policies from unsigned JARs during discovery.

      For development, set this to true since JARs are typically not signed during development. For production, leave as false to only load policies from signed JARs.

      Default: false

    • getExternalPoliciesSourceDir

      public abstract org.gradle.api.file.DirectoryProperty getExternalPoliciesSourceDir()
      The source directory containing external policy .jguard files.

      All *.jguard files in this directory will be compiled to binary format and packaged into the JAR at META-INF/jguard/external/. These policies provide capabilities for third-party libraries that don't ship with their own jGuard policies.

      The output filename will be derived from the source filename (e.g., io.netty.jguard becomes io.netty.bin).

      Default: src/main/jguard (mirrors src/test/jguard for test policies)

      Example usage: 

       // File: src/main/jguard/io.netty.common.jguard
 security module io.netty.common {
     entitle io.netty.common.. to threads.create;
     entitle io.netty.common.. to network.outbound;
 }

    • getExternalPoliciesOutputDir

      public abstract org.gradle.api.file.DirectoryProperty getExternalPoliciesOutputDir()
      The output directory for compiled external policy .bin files.

      This directory is automatically included in the JAR at META-INF/jguard/external/. The agent discovers these policies alongside embedded policies.

      Default: build/jguard-policy/META-INF/jguard/external/

    • getExternalPoliciesIncludeJson

      public abstract org.gradle.api.provider.Property<Boolean> getExternalPoliciesIncludeJson()
      Whether to generate JSON alongside binary for external policies (for debugging).

      Default: false

    • getTestPoliciesSourceDir

      public abstract org.gradle.api.file.DirectoryProperty getTestPoliciesSourceDir()
      The source directory containing test-specific policy .jguard files.

      Test policies extend embedded policies with additional permissions needed during testing (e.g., temp file access, thread creation for test frameworks). These policies are only applied when running tests, not in production.

      All *.jguard files in this directory will be compiled to binary format and passed to the agent during test execution.

      Default: src/test/jguard

      Example usage: 

       // File: src/test/jguard/io.mymodule.jguard
 security module io.mymodule {
     entitle io.mymodule.. to fs.write("/tmp", "**");
     entitle io.mymodule.. to threads.create;
 }

    • getTestPoliciesOutputDir

      public abstract org.gradle.api.file.DirectoryProperty getTestPoliciesOutputDir()
      The output directory for compiled test policy .bin files.

      Default: build/test-policies/

    • getAllowTrusted

      public abstract org.gradle.api.provider.Property<Boolean> getAllowTrusted()
      Whether to allow trusted modules.

      Trusted modules bypass ALL capability checks. This is intended for native libraries (e.g., PyTorch, TensorFlow) that require unrestricted access and cannot be modified.

      Security Warning: Only enable this in controlled environments where you trust the policy override files. Trusted modules can perform any operation without restriction.

      To mark a module as trusted, create an override policy file: 

       // File: policies-src/ai.djl.pytorch.jguard
 security module ai.djl.pytorch {
     trusted;
 }

      Default: false

    • getHotReload

      public abstract org.gradle.api.provider.Property<Boolean> getHotReload()
      Whether to enable policy hot reload.

      When enabled, the agent watches for policy file changes and reloads them without requiring a JVM restart. This is useful for:

      • Development: quickly iterate on policy definitions
      • Operations: adjust permissions without service restarts
      • Emergency response: rapidly restrict compromised modules

      In discovery mode, hot reload watches the external policy override directory. In explicit policy mode, it watches both the policy file and override directory.

      Default: false

    • getHotReloadInterval

      public abstract org.gradle.api.provider.Property<Integer> getHotReloadInterval()
      The interval in seconds between policy file checks when hot reload is enabled.

      Lower values provide faster response to changes but increase overhead. Higher values reduce overhead but delay detection of changes.

      Default: 5 seconds