Class YmlSecurity

java.lang.Object
cloud.opencode.base.yml.security.YmlSecurity
public final class YmlSecurity extends Object
YML Security - Security utilities for YAML processing YML 安全 - YAML 处理的安全工具

Features | 主要功能:

  • Prevention of YAML bomb attacks (billion laughs) - 防止 YAML 炸弹攻击（十亿笑声）
  • Alias expansion limits - 别名展开限制
  • Document size limits - 文档大小限制
  • Safe type restrictions - 安全类型限制
  • Dangerous pattern detection and sanitization - 危险模式检测和净化

Usage Examples | 使用示例:

// Validate YAML before parsing
YmlSecurity.validate(yamlContent);

// Check for dangerous patterns
if (YmlSecurity.containsDangerousPatterns(yamlContent)) {
    throw new YmlSecurityException("Unsafe YAML content");
}

// Get safe config
YmlConfig safeConfig = YmlSecurity.createSafeConfig();

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
  • Null-safe: Yes (null input is handled gracefully) - 空值安全: 是（空输入被优雅处理）
Since:
JDK 25, opencode-base-yml V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_ALIASES
    Default maximum alias count 默认最大别名数量
    static final int
    DEFAULT_MAX_DEPTH
    Default maximum nesting depth 默认最大嵌套深度
    static final long
    DEFAULT_MAX_DOCUMENT_SIZE
    Default maximum document size (10 MB) 默认最大文档大小（10 MB）

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    containsDangerousPatterns(String yamlContent)
    Checks if YAML content contains dangerous patterns 检查 YAML 内容是否包含危险模式
    static int
    countAliases(String yamlContent)
    Counts aliases in YAML content.
    static int
    countAnchors(String yamlContent)
    Counts anchors in YAML content.
    static YmlConfig
    createSafeConfig()
    Creates a safe YAML configuration 创建安全的 YAML 配置
    static YmlConfig
    createSafeConfig(long maxSize, int maxAliases)
    Creates a safe YAML configuration with custom limits 使用自定义限制创建安全的 YAML 配置
    static boolean
    isSafeType(String typeName)
    Checks if a type is safe for deserialization 检查类型是否可以安全反序列化
    static String
    sanitize(String yamlContent)
    Sanitizes YAML content by removing dangerous patterns 通过移除危险模式净化 YAML 内容
    static void
    validate(String yamlContent)
    Validates YAML content for security issues 验证 YAML 内容的安全问题
    static void
    validate(String yamlContent, long maxSize, int maxAliases)
    Validates YAML content with custom limits 使用自定义限制验证 YAML 内容

    Methods inherited from class Object

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

  • Field Details

    • DEFAULT_MAX_DOCUMENT_SIZE

      public static final long DEFAULT_MAX_DOCUMENT_SIZE
      Default maximum document size (10 MB) 默认最大文档大小（10 MB）
      See Also:

    • DEFAULT_MAX_ALIASES

      public static final int DEFAULT_MAX_ALIASES
      Default maximum alias count 默认最大别名数量
      See Also:

    • DEFAULT_MAX_DEPTH

      public static final int DEFAULT_MAX_DEPTH
      Default maximum nesting depth 默认最大嵌套深度
      See Also:

  • Method Details

    • validate

      public static void validate(String yamlContent)
      Validates YAML content for security issues 验证 YAML 内容的安全问题
      Parameters:
      yamlContent - YAML content | YAML 内容
      Throws:
      YmlSecurityException - if security issue found | 如果发现安全问题

    • validate

      public static void validate(String yamlContent, long maxSize, int maxAliases)
      Validates YAML content with custom limits 使用自定义限制验证 YAML 内容
      Parameters:
      yamlContent - YAML content | YAML 内容
      maxSize - maximum document size | 最大文档大小
      maxAliases - maximum alias count | 最大别名数量
      Throws:
      YmlSecurityException - if security issue found | 如果发现安全问题

    • containsDangerousPatterns

      public static boolean containsDangerousPatterns(String yamlContent)
      Checks if YAML content contains dangerous patterns 检查 YAML 内容是否包含危险模式
      Parameters:
      yamlContent - YAML content | YAML 内容
      Returns:
      true if dangerous | 如果危险返回 true

    • countAliases

      public static int countAliases(String yamlContent)
      Counts aliases in YAML content. V1.0.4 sec round-4 P2: skips * characters that appear inside double-quoted ("...") or single-quoted ('...') strings, since those are literal text not alias references. Pre-fix the counter incremented for every raw * including those inside quoted URL-like values ('https://example.com/path*'); a legitimate document with 51+ such strings would be falsely rejected by the DEFAULT_MAX_ALIASES = 50 guard, while a real BillionLaughs amplification attack with 49 actual aliases plus one stray * in a string could still slip under the cap. 计算 YAML 内容中的别名数量。V1.0.4 sec round-4 P2：跳过双引号 ("...") 与单引号 ('...') 字符串内的 *（那是字面量不是别名引用）。修复前计数器对每个原始 * 都自增（包括 quoted URL 风格值 'https://example.com/path*' 内的）； 含 51+ 此类字符串的合法文档会被 DEFAULT_MAX_ALIASES = 50 误拒，而 49 个真别名 + 字符串内 1 个 * 的真 BillionLaughs 攻击仍可绕过阈值。
      Parameters:
      yamlContent - YAML content | YAML 内容
      Returns:
      alias count | 别名数量

    • countAnchors

      public static int countAnchors(String yamlContent)
      Counts anchors in YAML content. Aligned with countAliases(String) as of V1.0.4 sec round-6 P1: skips & characters inside quoted strings and uses the same backslash-parity escape detection. Pre-fix countAnchors used the round-4 logic (raw character scan + simple prev != '\\' check), so its over-count vs countAliases's under-count meant the two cooperating limits could disagree: documents legitimately exceeding the anchor cap could pass the alias cap and vice versa. Symmetric algorithms keep the two security invariants aligned. 计算 YAML 内容中的锚点数量。V1.0.4 sec round-6 P1 起与 countAliases(String) 对齐： 跳过 quoted string 内的 &，使用同样的反斜杠奇偶性转义识别。修复前 countAnchors 用 round-4 旧逻辑（原始字符扫描 + 简单的 prev != '\\' 检查），过度计数与 countAliases 的欠计数相对，两个上限可不一致：合法文档 超 anchor 上限却通过 alias 上限，反之亦然。对称算法让两个安全不变量对齐。
      Parameters:
      yamlContent - YAML content | YAML 内容
      Returns:
      anchor count | 锚点数量

    • createSafeConfig

      public static YmlConfig createSafeConfig()
      Creates a safe YAML configuration 创建安全的 YAML 配置
      Returns:
      safe configuration | 安全配置

    • createSafeConfig

      public static YmlConfig createSafeConfig(long maxSize, int maxAliases)
      Creates a safe YAML configuration with custom limits 使用自定义限制创建安全的 YAML 配置
      Parameters:
      maxSize - maximum document size | 最大文档大小
      maxAliases - maximum alias count | 最大别名数量
      Returns:
      safe configuration | 安全配置

    • sanitize

      public static String sanitize(String yamlContent)
      Sanitizes YAML content by removing dangerous patterns 通过移除危险模式净化 YAML 内容
      Parameters:
      yamlContent - YAML content | YAML 内容
      Returns:
      sanitized content | 净化后的内容

    • isSafeType

      public static boolean isSafeType(String typeName)
      Checks if a type is safe for deserialization 检查类型是否可以安全反序列化
      Parameters:
      typeName - the type name | 类型名称
      Returns:
      true if safe | 如果安全返回 true