Class DefaultSandbox

java.lang.Object
cloud.opencode.base.expression.sandbox.DefaultSandbox
All Implemented Interfaces:
Sandbox
public class DefaultSandbox extends Object implements Sandbox
Default Security Sandbox 默认安全沙箱

Provides configurable security constraints for expression evaluation.

为表达式求值提供可配置的安全约束。

Features | 主要功能:

  • Class-level and package-level allow/deny lists - 类级别和包级别的允许/拒绝列表
  • Method-level allow/deny lists - 方法级别的允许/拒绝列表
  • Configurable expression length, evaluation depth, and time limits - 可配置表达式长度、求值深度和时间限制
  • Preset configurations: permissive, restrictive, standard - 预设配置: 宽松、限制、标准
  • Builder pattern for custom configurations - 构建器模式用于自定义配置

Usage Examples | 使用示例:

// Use standard sandbox
Sandbox sandbox = DefaultSandbox.standard();

// Custom sandbox
Sandbox custom = DefaultSandbox.builder()
    .allowAllByDefault(true)
    .addDeniedClass("java.lang.Runtime")
    .addDeniedMethod("exec")
    .maxEvaluationTime(3000)
    .build();

Security | 安全性:

  • Thread-safe: Yes, immutable after construction with defensive copies - 线程安全: 是，构造后不可变，使用防御性拷贝
  • Null-safe: Yes, null class/method/property returns false - 空值安全: 是，null类/方法/属性返回false
  • Deny takes priority over allow - 拒绝优先于允许
Since:
JDK 25, opencode-base-expression V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • permissive

      public static DefaultSandbox permissive()
      Create a permissive sandbox that allows everything 创建允许所有操作的宽松沙箱
      Returns:
      the permissive sandbox | 宽松沙箱

    • restrictive

      public static DefaultSandbox restrictive()
      Create a restrictive sandbox that denies by default 创建默认拒绝的限制性沙箱
      Returns:
      the restrictive sandbox | 限制性沙箱

    • standard

      public static DefaultSandbox standard()
      Create a "standard" sandbox with denylist semantics (allowAllByDefault=true). 创建以"拒绝列表"语义为基础（allowAllByDefault=true）的"标准"沙箱。

      V1.0.4 sec round-4 P2 — security caveat: standard() uses a denylist, which means any class or method NOT explicitly listed is allowed. The deny set blocks Runtime/ProcessBuilder/System/Thread/ClassLoader and a handful of reflection methods, but it does NOT block:

      • Subclasses of denied types (e.g. MyClassLoader extends ClassLoader is allowed)
      • Methods with the same names defined on undenied classes
      • Static methods invoked via undenied wrapper classes
      • JNI / native methods on third-party classes

      For untrusted input, prefer restrictive() which uses allowAllByDefault =false (allowlist semantics) — only explicitly permitted classes/methods are reachable. standard() is appropriate ONLY when the expression source is fully trusted (e.g. developer-authored config templates) and you want a defense-in-depth net for typos.

      V1.0.4 sec round-4 P2 安全提示：standard() 用拒绝列表， 即任何未显式列出的类/方法都允许。拒绝集封堵了 Runtime/ProcessBuilder/System/Thread/ClassLoader 和少数反射方法，但**不**封堵：被拒类的子类（如 MyClassLoader extends ClassLoader）、 同名方法定义在未被拒类上的情况、未被拒包装类的静态方法、第三方类的 JNI/native 方法。

      面对不可信输入请用 restrictive()（allowAllByDefault=false，允许列表语义）， 仅显式允许的类/方法可达。standard() 仅适合表达式来源完全可信（如开发者编写的配置 模板），并希望对拼写错误等情况有 defense-in-depth 兜底的场景。

      Returns:
      the standard sandbox | 标准沙箱
      See Also:

    • isClassAllowed

      public boolean isClassAllowed(Class<?> clazz)
      Description copied from interface: Sandbox
      Check if a class is allowed 检查是否允许访问类
      Specified by:
      isClassAllowed in interface Sandbox
      Parameters:
      clazz - the class | 类
      Returns:
      true if allowed | 如果允许返回true

    • isMethodAllowed

      public boolean isMethodAllowed(Object target, Method method)
      Description copied from interface: Sandbox
      Check if a method call is allowed 检查是否允许调用方法
      Specified by:
      isMethodAllowed in interface Sandbox
      Parameters:
      target - the target object | 目标对象
      method - the method | 方法
      Returns:
      true if allowed | 如果允许返回true

    • isPropertyAllowed

      public boolean isPropertyAllowed(Object target, String property)
      Description copied from interface: Sandbox
      Check if a property access is allowed 检查是否允许访问属性
      Specified by:
      isPropertyAllowed in interface Sandbox
      Parameters:
      target - the target object | 目标对象
      property - the property name | 属性名
      Returns:
      true if allowed | 如果允许返回true

    • getMaxExpressionLength

      public int getMaxExpressionLength()
      Description copied from interface: Sandbox
      Get the maximum expression length 获取最大表达式长度
      Specified by:
      getMaxExpressionLength in interface Sandbox
      Returns:
      the max length, -1 for unlimited | 最大长度，-1表示无限

    • getMaxEvaluationDepth

      public int getMaxEvaluationDepth()
      Description copied from interface: Sandbox
      Get the maximum evaluation depth 获取最大求值深度
      Specified by:
      getMaxEvaluationDepth in interface Sandbox
      Returns:
      the max depth, -1 for unlimited | 最大深度，-1表示无限

    • getMaxEvaluationTime

      public long getMaxEvaluationTime()
      Description copied from interface: Sandbox
      Get the maximum evaluation time in milliseconds 获取最大求值时间（毫秒）
      Specified by:
      getMaxEvaluationTime in interface Sandbox
      Returns:
      the max time, -1 for unlimited | 最大时间，-1表示无限

    • builder

      public static DefaultSandbox.Builder builder()
      Create a builder 创建构建器
      Returns:
      the builder | 构建器