Security

Security mode provides dangerous pattern detection functionality to prevent JSON injection attacks, prototype pollution, and other security threats.

DangerousPattern Struct

DangerousPattern represents a security risk pattern. It is a struct type.

type DangerousPattern struct {
    Pattern string       // Substring to detect in input
    Name    string       // Descriptive name of the pattern
    Level   PatternLevel // Severity level determining how to handle the pattern
}

Field Descriptions

Field	Type	Description
`Pattern`	`string`	Substring to detect in input
`Name`	`string`	Descriptive name of the pattern
`Level`	`PatternLevel`	Severity level determining how to handle the pattern

PatternLevel Type

PatternLevel represents the severity level of a dangerous pattern.

type PatternLevel int

Constants

const (
    // PatternLevelCritical always blocks the operation
    // Used for patterns that pose an immediate security risk (e.g., prototype pollution)
    PatternLevelCritical PatternLevel = iota

    // PatternLevelWarning blocks in strict mode, logs a warning in permissive mode
    // Used for patterns that may indicate malicious intent but have legitimate uses
    PatternLevelWarning

    // PatternLevelInfo only logs, never blocks
    // Used for audit/tracking purposes without interrupting operations
    PatternLevelInfo
)

String Method

func (pl PatternLevel) String() string

Returns the string representation of PatternLevel.

Built-in Dangerous Patterns

Default Patterns

Internal API

The built-in pattern list is managed by internal functions and is no longer exported as a public API. Custom patterns can be managed via the Config's AdditionalDangerousPatterns field.

The following are built-in dangerous patterns, all at Critical level:

Pattern	Name	Category
`__proto__`	prototype pollution	Prototype Pollution
`constructor[`	constructor access	Constructor Access
`prototype.`	prototype manipulation	Prototype Manipulation
`<script`	script tag injection	HTML Injection
`<iframe`	iframe injection	HTML Injection
`<object`	object injection	HTML Injection
`<embed`	embed injection	HTML Injection
`<svg`	svg injection	HTML Injection
`javascript:`	javascript protocol	Protocol Injection
`vbscript:`	vbscript protocol	Protocol Injection
`eval(`	dynamic code execution	Code Execution
`setTimeout(`	timer manipulation	Code Execution
`setInterval(`	interval manipulation	Code Execution
`require(`	code injection	Code Execution
`new function(`	dynamic function creation	Code Execution
`document.cookie`	cookie access	DOM Access
`window.location`	redirect manipulation	DOM Access
`innerhtml`	DOM manipulation	DOM Access
`onerror`, `onload`, `onclick`, `onmouseover`, `onfocus`	event handler injection	Event Handlers
`fromcharcode(`	character encoding bypass	Encoding Bypass
`atob(`	base64 decoding	Encoding Bypass
`expression(`	CSS expression injection	CSS Injection
`__defineGetter__`	getter definition	Prototype Pollution
`__defineSetter__`	setter definition	Prototype Pollution

Critical Patterns

Internal API

GetCriticalPatterns has been converted to an internal function and is no longer exported as a public API. Critical patterns (__proto__, constructor[, prototype.) are always enforced and cannot be disabled.

The following critical patterns are always fully scanned regardless of JSON size:

Pattern	Description
`__proto__`	prototype pollution
`constructor[`	constructor access
`prototype.`	prototype manipulation

Pattern Registration Methods

Dangerous patterns are configured via the Config struct rather than global registration functions.

Config.AddDangerousPattern

Signature: func (c *Config) AddDangerousPattern(pattern DangerousPattern)

Adds a custom dangerous pattern to the configuration.

cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "malicious_keyword",
    Name:    "Custom dangerous pattern",
    Level:   json.PatternLevelCritical,
})

processor, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer processor.Close()

Config.AdditionalDangerousPatterns

You can also directly set the Config.AdditionalDangerousPatterns field:

cfg := json.DefaultConfig()
cfg.AdditionalDangerousPatterns = []json.DangerousPattern{
    {Pattern: "eval(", Name: "eval-call", Level: json.PatternLevelCritical},
    {Pattern: "exec(", Name: "exec-call", Level: json.PatternLevelWarning},
}

Config Configuration Methods

AddDangerousPattern

Adds a security pattern to the configuration.

func (c *Config) AddDangerousPattern(pattern DangerousPattern)

cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "custom_dangerous_string",
    Name:    "Custom dangerous string",
    Level:   json.PatternLevelWarning,
})

Configuration Fields

type Config struct {
    // ... other fields ...

    // AdditionalDangerousPatterns adds security patterns beyond the defaults
    AdditionalDangerousPatterns []DangerousPattern

    // DisableDefaultPatterns disables built-in default security patterns (except critical ones)
    // When true, only AdditionalDangerousPatterns are used
    // Note: Critical patterns (__proto__, constructor[, prototype.) are always enforced and cannot be disabled
    DisableDefaultPatterns bool
}

Global Pattern Registration

In addition to instance-level patterns configured via Config, you can manage global pattern registries via package-level functions. Patterns in the global registry are effective across all Processor instances.

RegisterDangerousPattern

Signature: func RegisterDangerousPattern(pattern DangerousPattern)

Adds a custom dangerous pattern to the global registry. Registered patterns are effective across all Processor instances.

json.RegisterDangerousPattern(json.DangerousPattern{
    Pattern: "malicious_keyword",
    Name:    "Custom dangerous pattern",
    Level:   json.PatternLevelCritical,
})

UnregisterDangerousPattern

Signature: func UnregisterDangerousPattern(pattern string)

Removes the specified pattern from the global registry.

json.UnregisterDangerousPattern("malicious_keyword")

ListDangerousPatterns

Signature: func ListDangerousPatterns() []DangerousPattern

Returns all custom patterns in the global registry.

patterns := json.ListDangerousPatterns()
for _, p := range patterns {
    fmt.Printf("Pattern: %s, Name: %s, Level: %s\n", p.Pattern, p.Name, p.Level)
}

Global Patterns vs Config Patterns

Global patterns (RegisterDangerousPattern): Shared across all Processor instances, suitable for application-level security policies
Config patterns (Config.AddDangerousPattern): Only affect Processors using that Config, suitable for instance-level customization

Complete Example

Custom Security Policy

package main

import (
    "fmt"
    "github.com/cybergodev/json"
)

func main() {
    // Method 1: Via config field
    cfg := json.DefaultConfig()
    cfg.AdditionalDangerousPatterns = []json.DangerousPattern{
        {Pattern: "company_secret", Name: "Company sensitive information", Level: json.PatternLevelCritical},
    }

    // Method 2: Via config method
    cfg.AddDangerousPattern(json.DangerousPattern{
        Pattern: "internal_api",
        Name:    "Internal API reference",
        Level:   json.PatternLevelWarning,
    })

    p, err := json.New(cfg)
    if err != nil {
        panic(err)
    }
    defer p.Close()

    // Test dangerous pattern detection
    _, err = p.Get(`{"data": "company_secret_info"}`, "data")
    if err != nil {
        fmt.Println("Dangerous pattern detected:", err)
    }

    // View registered patterns
    fmt.Printf("Custom pattern count: %d\n", len(cfg.AdditionalDangerousPatterns))
}

Disabling Default Patterns

cfg := json.DefaultConfig()

// Disable built-in default patterns (except critical ones), use only custom patterns
// Note: Critical patterns (__proto__, constructor[, prototype.) are always enforced
cfg.DisableDefaultPatterns = true

// Add custom patterns
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "xss_payload",
    Name:    "XSS attack payload",
    Level:   json.PatternLevelCritical,
})

p, err := json.New(cfg)
if err != nil {
    panic(err)
}
defer p.Close()

Handling Patterns by Level

// Register patterns at different levels
cfg := json.DefaultConfig()
cfg.AddDangerousPattern(json.DangerousPattern{
    Pattern: "suspicious_but_allowed",
    Name:    "Suspicious but allowed",
    Level:   json.PatternLevelInfo, // Only log, do not block
})

// View registered custom patterns
for _, p := range cfg.AdditionalDangerousPatterns {
    fmt.Printf("Pattern: %s, Name: %s, Level: %s\n", p.Pattern, p.Name, p.Level)
}

Security Scanning Strategy

Small JSON (< 4KB)

Always performs a full security scan, checking each dangerous pattern one by one.

Larger JSON (≥ 4KB)

Uses a multi-level optimized scan that guarantees 100% coverage (no sampling blind spots):

Critical patterns (__proto__, constructor[, prototype.) are always fully scanned
An indicator-character check is performed first: if no dangerous characters are present, the scan is skipped quickly
Suspicious character density is detected: when the density is too high, a full scan is performed to prevent attackers from hiding malicious content in dense regions
The remaining patterns use a 32KB sliding window scan (with overlap) to ensure cross-boundary patterns are not missed

Config - Configuration options
Validator - Validator
Hook System - Operation interception

Security ​

DangerousPattern Struct ​

Field Descriptions ​

PatternLevel Type ​

Constants ​

String Method ​

Built-in Dangerous Patterns ​

Default Patterns ​

Critical Patterns ​

Pattern Registration Methods ​

Config.AddDangerousPattern ​

Config.AdditionalDangerousPatterns ​

Config Configuration Methods ​

AddDangerousPattern ​

Configuration Fields ​

Global Pattern Registration ​

RegisterDangerousPattern ​

UnregisterDangerousPattern ​

ListDangerousPatterns ​

Complete Example ​

Custom Security Policy ​

Disabling Default Patterns ​

Handling Patterns by Level ​

Security Scanning Strategy ​

Small JSON (< 4KB) ​

Larger JSON (≥ 4KB) ​

Related ​