Skip to main content
Version: Next 🚧

Your First Policy

This guide teaches you the jGuard policy language through practical examples.

Policy Structure​

A jGuard policy defines which packages can perform which operations:

security module <module-name> {
    entitle <subject> to <capability>;
    entitle <subject> to <capability>;
    ...
}

Subject Patterns​

Subjects determine who receives a capability:

PatternMatchesExample
moduleAll packages in the moduleAny code in the module
com.exampleExactly that packageOnly classes in com.example
com.example.*Direct subpackages onlycom.example.foo, not com.example.foo.bar
com.example..Package and all descendantscom.example.foo.bar.baz and deeper

Examples​

security module com.example.app {
    // Entire module can read system properties
    entitle module to system.property.read;

    // Only the http package can make network connections
    entitle com.example.app.http to network.outbound;

    // The http package and all subpackages can create threads
    entitle com.example.app.http.. to threads.create;

    // Direct children of worker package can read files
    entitle com.example.app.worker.* to fs.read(data, "**");
}

Capabilities​

Filesystem​

// Read files matching a glob pattern under a root
entitle module to fs.read(config, "*.properties");
entitle module to fs.read(data, "**/*.json");

// Write files
entitle module to fs.write(logs, "*.log");
entitle module to fs.write(output, "**");

Network​

// Any outbound connection
entitle module to network.outbound;

// Filtered by host pattern
entitle module to network.outbound("*.example.com");

// Filtered by host and port
entitle module to network.outbound("api.example.com", 443);

// Filtered by host pattern and port range
entitle module to network.outbound("*.example.com", "80-443");

// Listen on any port
entitle module to network.listen;

// Listen on specific port
entitle module to network.listen(8080);

// Listen on port range
entitle module to network.listen("8080-8090");

Threads​

// Create new threads
entitle module to threads.create;

Native Libraries​

// Load any native library
entitle module to native.load;

// Load specific library
entitle module to native.load("mylib");

Environment Variables​

// Read any environment variable
entitle module to env.read;

// Read specific variable
entitle module to env.read("HOME");

System Properties​

// Read any system property
entitle module to system.property.read;

// Read specific property
entitle module to system.property.read("java.home");

// Read properties matching pattern
entitle module to system.property.read("app.**");

// Write properties
entitle module to system.property.write("app.**");

Complete Example​

Here's a realistic policy for a web application:

security module com.example.webapp {
    // JDK initialization needs system property access
    entitle module to system.property.read;

    // Configuration layer can read config files
    entitle com.example.webapp.config.. to fs.read(config, "**");
    entitle com.example.webapp.config.. to env.read;

    // HTTP client layer can make outbound connections
    entitle com.example.webapp.http.. to network.outbound;

    // Server layer can bind ports
    entitle com.example.webapp.server.. to network.listen("8080-8443");

    // Worker threads need thread creation
    entitle com.example.webapp.worker.. to threads.create;

    // Logging layer can write logs
    entitle com.example.webapp.logging.. to fs.write(logs, "**/*.log");
}

Deny Statements​

External policies can deny capabilities to restrict overly permissive libraries:

security module com.vendor.library {
    // Remove network access from embedded policy
    deny module to network.outbound;

    // Defensive deny - suppress warning if not granted
    deny(defensive) module to native.load;
}

Best Practices​

  1. Start with audit mode - See what your application actually needs
  2. Use specific packages - Don't grant capabilities to module unless necessary
  3. Use the .. pattern carefully - It grants to all descendant packages
  4. Review third-party policies - Use jguard inspect to see embedded policies

Next Steps​