TinyRuleKit

Expression Security Measures

Expression security is configured through a public package for consumers: org.tinyrulekit.api.expression.security.

Use these components when rule JSON can be edited outside the application build, loaded from configuration files, or reviewed by non-engine authors.

Public Package

JAVA

import org.tinyrulekit.api.expression.security.ExpressionSecurityPolicy;
import org.tinyrulekit.api.expression.security.ExpressionValidators;

Minimum Protection

When expression security is enabled, TinyRuleKit always applies its minimum validator before the configured policy or custom validator. This minimum layer blocks critical expression fragments related to runtime execution, classloader access, reflection-like access, imports, and package-qualified Java access.

If this layer rejects an expression, the exception message names the minimum policy:

TEXT

Expression blocked by TinyRuleKit minimum expression security policy. Token: getClass

That message tells the consumer that the expression failed a framework safety baseline, not only a project-specific rule.

Public Components

ExpressionSecurityPolicy defines token-based checks:

JAVA

ExpressionSecurityPolicy policy = ExpressionSecurityPolicy.defaults()
        .withMaxLength(200)
        .withAdditionalBlockedTokens(Set.of("delete", "projectSecret"));

ExpressionValidators creates reusable validators:

JAVA

ExpressionValidator validator = ExpressionValidators.chain(
        ExpressionValidators.fromPolicy(policy),
        expression -> {
            if (expression.contains("projectOnly")) {
                throw new IllegalArgumentException("Expression is not allowed");
            }
        }
);

Builder Behavior

Passing a policy or validator to the builder keeps the minimum layer active:

JAVA

RuleEngine<GameContext> engine = RuleEngine.builder(GameContext.class)
        .expressionSecurityPolicy(policy)
        .buildFromJson(json);

The effective order is: TinyRuleKit minimum validator, configured policy or validator, then configured ExpressionEngine compilation.

Use ExpressionValidators.withMinimum(validator) only when a validator is reused outside the TinyRuleKit builder. The builder already applies it.

Replacing Tokens

withAdditionalBlockedTokens is the usual extension point. It keeps the default project-level tokens and adds more.

Use withBlockedTokens only when you intentionally want to replace the project-level token set:

JAVA

ExpressionSecurityPolicy policy = ExpressionSecurityPolicy.defaults()
        .withBlockedTokens(Set.of("projectSecret"));

Even then, TinyRuleKit still applies the minimum validator while expression security is enabled.

Disabling Security

expressionSecurityDisabled() disables both the minimum layer and the configured policy or validator. Use it only for fully trusted rule documents:

JAVA

RuleEngine<GameContext> engine = RuleEngine.builder(GameContext.class)
        .expressionSecurityDisabled()
        .buildFromJson(json);

Do not disable expression security for player-authored, user-authored, network-loaded, plugin-loaded, or administration-panel rule documents.