go-jdenticon/SECURITY.md

Security Policy

Supported Versions

We provide security updates for the following versions of go-jdenticon:

Version	Supported
1.2.x	✅
1.1.x	✅
1.0.x	❌ (EOL)
< 1.0	❌ (Pre-release)

Reporting a Vulnerability

Please do NOT report security vulnerabilities through public GitHub issues.

If you discover a security vulnerability in go-jdenticon, please report it to us responsibly:

Preferred Method: GitHub Private Vulnerability Reporting

1. Go to the Security tab of this repository
2. Click "Report a vulnerability"
3. Fill out the vulnerability report form with as much detail as possible

Alternative Method: Email

If GitHub private reporting is not available, you can email the maintainer at: kev@kev.codes

What to Include

Please include the following information in your report:

• Description: Clear description of the vulnerability
• Version: Affected version(s) of go-jdenticon
• Component: Which part of the library is affected (core API, CLI tool, specific renderer, etc.)
• Impact: Your assessment of the potential impact and severity
• Reproduction: Step-by-step instructions to reproduce the issue
• Proof of Concept: If applicable, minimal code example demonstrating the vulnerability
• Suggested Fix: If you have ideas for how to address the issue

Our Commitment

• Initial Response: We will acknowledge your report within 48 hours
• Progress Updates: We will provide status updates every 7 days until resolution
• Verification: We will work with you to understand and verify the issue
• Timeline: We aim to release security patches within 30 days for critical issues, 90 days for lower severity issues
• Credit: We will credit you in our security advisory unless you prefer to remain anonymous

Disclosure Timeline

We follow responsible disclosure practices:

1. Day 0: Vulnerability reported privately
2. Days 1-7: Initial triage and verification
3. Days 8-30: Development and testing of fix (for critical issues)
4. Day of Release: Security advisory published with fixed version
5. 30 days post-release: Full technical details may be shared publicly

Scope

This security policy covers:

• Core Library: The main go-jdenticon Go API (jdenticon package)
• CLI Tool: The command-line interface (cmd/jdenticon)
• Internal Components: Engine, renderers, and utilities
• Documentation: If documentation could lead users to implement insecure patterns

Out of Scope

The following are generally considered out of scope:

• Vulnerabilities in third-party dependencies (please report these upstream)
• Issues that require physical access to the system
• Social engineering attacks
• Issues in example code that is clearly marked as "example only"

---

Security Guide

Overview

The go-jdenticon library generates deterministic identicons (geometric avatar images) from input strings. This guide provides comprehensive security information for developers, operators, and security teams integrating or deploying the library.

⚠️ Important: This library is designed for generating visual representations of data, not for cryptographic or authentication purposes. The output should never be used for security-critical decisions.

Security Features

go-jdenticon includes several built-in security protections:

• Resource Limits: Configurable limits on input size, icon size, and complexity
• Input Validation: Comprehensive validation of all user inputs
• Path Traversal Protection: CLI tool prevents writing files outside intended directories
• Memory Protection: Built-in protections against memory exhaustion attacks
• Defense in Depth: Multiple layers of validation throughout the system

Threat Model

Primary Security Concerns

The main security risks for an identicon generation library are related to resource availability rather than data confidentiality:

1. Denial of Service (DoS) Attacks

• CPU Exhaustion: Malicious inputs designed to consume excessive processing time
• Memory Exhaustion: Requests for extremely large images that exhaust available memory
• Disk Exhaustion: (CLI only) Repeated generation of large files filling storage

2. Input Validation Vulnerabilities

• Malformed Inputs: Invalid color strings, non-UTF8 characters, or edge cases in parsers
• Path Traversal: (CLI only) Attempts to write files outside intended directories

3. Resource Consumption Attacks

• Large Input Strings: Extremely long input strings that consume CPU during processing
• Complex Generation: Inputs that trigger computationally expensive generation paths

Built-in Protections

go-jdenticon includes comprehensive protections against these threats:

• ✅ Configurable Resource Limits: Input size, image dimensions, and complexity limits
• ✅ Robust Input Validation: All inputs are validated before processing
• ✅ Path Traversal Protection: CLI tool sanitizes output paths
• ✅ Memory Bounds Checking: Internal limits prevent memory exhaustion
• ✅ Defense in Depth: Multiple validation layers throughout the system

Secure Usage Guidelines

For Go API Consumers

1. Treat All Inputs as Untrusted

Always validate and sanitize user-provided data before passing it to the library:

// ❌ DANGEROUS: Direct use of user input
userInput := getUserInput() // Could be malicious
icon, err := jdenticon.Generate(ctx, userInput, 256)

// ✅ SECURE: Validate and sanitize first
userInput := strings.TrimSpace(getUserInput())
if len(userInput) > 100 { // Your application limit
    return errors.New("input too long")
}
if !isValidInput(userInput) { // Your validation logic
    return errors.New("invalid input")
}
icon, err := jdenticon.Generate(ctx, userInput, 256)

2. Never Use Sensitive Data as Input

Do not use PII, passwords, or secrets as identicon input:

// ❌ DANGEROUS: Using sensitive data
email := "user@example.com"
password := "secret123"
icon, _ := jdenticon.Generate(ctx, password, 256) // DON'T DO THIS

// ✅ SECURE: Use non-sensitive identifiers
userID := "user-12345"
icon, err := jdenticon.Generate(ctx, userID, 256)

3. Always Handle Errors

Check for errors - they may indicate security limit violations:

// ✅ SECURE: Proper error handling
icon, err := jdenticon.Generate(ctx, input, size)
if err != nil {
    // Log the error - could indicate attack attempt
    log.Printf("Icon generation failed: %v", err)
    
    // Handle gracefully based on error type
    var sizeErr *jdenticon.ErrValueTooLarge
    if errors.As(err, &sizeErr) {
        return handleResourceLimitError(sizeErr)
    }
    
    return handleGeneralError(err)
}

4. Configure Resource Limits Explicitly

Don't rely on defaults - set limits appropriate for your environment:

config := jdenticon.Config{
    MaxIconSize: 1024,    // Maximum 1024×1024 pixels
    MaxInputLength: 256,  // Maximum 256 byte input strings
    MaxComplexity: 50,    // Reduce computational complexity
    // ... other config options
}

// Use 0 for default limits, positive values for custom limits, -1 to disable
icon, err := jdenticon.ToSVGWithConfig(ctx, "user@example.com", 512, config)

Default Security Limits:

• Icon Size: 4096×4096 pixels maximum (~64MB memory usage)
• Input Length: 1MB maximum input string length
• Complexity: 100 maximum computational complexity score

For Web Applications

1. Content Security Policy for SVG Output

When serving SVG identicons, use proper Content-Security-Policy:

<!-- ✅ SECURE: Restrict SVG capabilities -->
<meta http-equiv="Content-Security-Policy" 
      content="img-src 'self' data:; object-src 'none';">

<img src="data:image/svg+xml;base64,..." alt="User Avatar">

2. Cache Generated Icons

Avoid regenerating identical icons to prevent resource exhaustion:

// ✅ SECURE: Use generator with caching
generator, err := jdenticon.NewGeneratorWithCacheSize(1000)
if err != nil {
    return err
}

// Icons with same input will be cached
icon1, _ := generator.Generate(ctx, "user123", 64)
icon2, _ := generator.Generate(ctx, "user123", 64) // Served from cache

For CLI Tool Users

1. Validate Output Paths

The CLI tool includes path traversal protection, but you should still validate:

# ✅ SECURE: Use absolute paths in trusted directories
jdenticon generate "user123" --output /var/www/avatars/user123.svg

# ❌ POTENTIALLY RISKY: Don't use user-controlled paths
# jdenticon generate "$USER_INPUT" --output "$USER_PATH"

2. Run with Minimal Privileges

# ✅ SECURE: Create dedicated user for CLI operations
sudo useradd -r -s /bin/false jdenticon-user
sudo -u jdenticon-user jdenticon generate "user123" --output avatar.svg

Deployment Security

Container Security

When deploying in containers, apply resource limits:

# docker-compose.yml or Kubernetes deployment
resources:
  limits:
    memory: "512Mi"
    cpu: "500m"
  requests:
    memory: "256Mi"
    cpu: "250m"

Monitoring and Alerting

Monitor these metrics for security:

• Generation error rates (potential attack indicators)
• Resource limit violations
• Unusual input patterns or sizes
• Memory/CPU usage spikes

// Example monitoring code
func monitorGeneration(input string, size int, err error) {
    if err != nil {
        securityLog.Printf("Generation failed: input_len=%d, size=%d, error=%v", 
            len(input), size, err)
        
        // Check for potential attack patterns
        if len(input) > 1000 || size > 2048 {
            alertSecurityTeam("Suspicious identicon generation attempt", input, size, err)
        }
    }
}

Platform-Specific Considerations

32-bit Systems

• Integer overflow protections are in place for hash parsing
• Memory limits may need adjustment for smaller address space

Container Environments

• Apply CPU and memory limits as defense in depth
• Monitor for container escape attempts through resource exhaustion

Security Limitations & Known Issues

1. Cryptographic Attacks: The output is deterministic and predictable - not suitable for security purposes
2. Information Leakage: Identical inputs produce identical outputs - avoid using sensitive data
3. Side-Channel Attacks: Processing time may vary based on input complexity
4. Dependency Vulnerabilities: Keep Go toolchain and any external dependencies updated

Security Updates

Security updates are distributed through:

• GitHub Releases: All security fixes are released as new versions
• GitHub Security Advisories: Critical issues are published as security advisories
• Go Module Proxy: Updates are automatically available through go get -u

Emergency Response

If You Suspect an Attack

1. Monitor: Check logs for patterns of failed generations or resource limit violations
2. Investigate: Look for common source IPs or unusual input patterns
3. Respond: Apply rate limiting, blocking, or input filtering as appropriate
4. Document: Keep records for potential security team review

Security Best Practices Summary

For Developers ✅

• Always validate inputs before passing to the library
• Handle all errors returned by library functions
• Never use sensitive data as identicon input
• Configure resource limits explicitly for your environment
• Use proper Content-Security-Policy when serving SVGs

For Operators ✅

• Apply container-level resource limits as defense in depth
• Monitor generation metrics and error rates
• Keep dependencies updated with vulnerability scanning
• Run CLI tools with minimal privileges
• Set up alerting for suspicious patterns

For Security Teams ✅

• Review configuration limits match threat model
• Include go-jdenticon in vulnerability scanning processes
• Monitor for new security advisories
• Test disaster recovery procedures for DoS scenarios
• Validate secure coding practices in applications using the library

---

Questions?

If you have questions about this security policy or need clarification on whether an issue should be reported as a security vulnerability, please open a regular GitHub issue with the tag "security-question" (this is for questions about the policy, not for reporting actual vulnerabilities).

---

Last Updated: 2025-06-24
Policy Version: 1.0