NBT Validation

Protect your server from NBT-based exploits in signs, books, and item data.

What is NBT?

NBT (Named Binary Tag) is Minecraft's data format for storing complex information like item properties, block data, and entity attributes. Players can send NBT data through various packets, creating opportunities for exploits.

Why NBT Validation Matters

Without proper validation, malicious NBT data can:

  • Crash the server - Deeply nested or circular NBT structures cause stack overflow errors
  • Lag the server - Extremely large NBT payloads consume CPU and memory during deserialization
  • Exploit bugs - Malformed NBT can trigger unhandled exceptions in Minecraft's code
  • Inject commands - NBT in books and signs can contain hidden commands or clickable exploits
  • Duplicate items - Crafted NBT structures can trick inventory systems

What GAPE Validates

Sign Data

Signs are a common attack vector because players can create them easily:

  • Line length - Ensures each line doesn't exceed Minecraft's limits
  • Total size - Validates the entire NBT payload size
  • Nesting depth - Prevents deeply nested NBT structures
  • Special characters - Detects exploit attempts using Unicode or control characters
  • Command injection - Blocks hidden clickEvent or hoverEvent exploits

Book Data

Written books contain rich NBT data and are heavily exploited:

  • Page count - Limits maximum number of pages
  • Page size - Validates each page's character count
  • Total book size - Prevents massive book payloads
  • JSON validation - Ensures book JSON is well-formed
  • Click events - Validates clickEvent and hoverEvent actions
  • Nesting depth - Prevents nested JSON exploits

Item NBT

Items can contain custom NBT data:

  • Attribute limits - Validates item attribute counts and values
  • Enchantment levels - Checks for impossible enchantment combinations
  • Display names - Validates custom name length and content
  • Lore text - Ensures lore lines are within limits
  • Custom model data - Validates custom model data values

Configuration Options

Validation Strictness

Choose between strict, normal, or lenient validation modes:

  • Strict - Reject any NBT that exceeds vanilla Minecraft limits
  • Normal - Allow slightly larger NBT for plugin compatibility (recommended)
  • Lenient - Only block obviously malicious NBT

Size Limits

Set maximum sizes for different NBT types:

  • Max sign NBT size - Total bytes allowed in sign packet NBT
  • Max book NBT size - Total bytes allowed in book NBT
  • Max item NBT size - Total bytes allowed in item NBT
  • Max nesting depth - How many levels deep NBT structures can be

Content Validation

Enable or disable specific content checks:

  • Validate JSON - Parse and validate JSON in books and signs
  • Block click events - Prevent clickEvent exploits entirely
  • Sanitize text - Remove dangerous characters and formatting
  • Check Unicode - Detect exploits using special Unicode characters

Common NBT Exploits

Sign Crash Exploit

Attackers send signs with extremely long lines or deeply nested formatting codes. When the server tries to process this data, it crashes or freezes.

Book Lag Exploit

Books with hundreds of pages or pages containing thousands of characters. Opening these books causes severe lag as the server parses and renders the data.

NBT Injection

Specially crafted NBT that includes clickEvents to run commands, execute arbitrary text, or trigger unintended game behaviors.

Item Duplication

Malformed item NBT that confuses inventory systems, allowing items to be duplicated when moved or combined.

Performance Impact

NBT validation has minimal overhead:

  • Sign packets: ~50-100ns validation time
  • Book packets: ~200-500ns depending on page count
  • Item NBT: ~100-300ns per item

Validation only occurs when players send relevant packets (placing signs, editing books, etc.), not during normal gameplay.

Best Practices

  • Use Normal strictness for most servers - balances security and compatibility
  • Set size limits slightly above vanilla limits to allow plugin items while blocking exploits
  • Enable JSON validation to catch formatted text exploits
  • Monitor violation logs to identify players attempting NBT exploits
  • Whitelist trusted players if they need to create large books or complex items
Warning: Setting limits too low may break vanilla Minecraft features or plugin items. Test thoroughly when adjusting NBT validation settings.