Initial release: Go Jdenticon library v0.1.0

- Core library with SVG and PNG generation - CLI tool with generate and batch commands - Cross-platform path handling for Windows compatibility - Comprehensive test suite with integration tests
2026-01-02 23:56:48 -05:00
parent f84b511895
commit d9e84812ff
292 changed files with 19725 additions and 38884 deletions
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -0,0 +1,368 @@
+# Security Policy
+
+## Supported Versions
+
+We provide security updates for the following versions of go-jdenticon:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.2.x   | :white_check_mark: |
+| 1.1.x   | :white_check_mark: |
+| 1.0.x   | :x: (EOL)          |
+| < 1.0   | :x: (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](../../security) 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:
+
+```go
+// ❌ 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:
+
+```go
+// ❌ 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:
+
+```go
+// ✅ 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:
+
+```go
+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:
+
+```html
+<!-- ✅ 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:
+
+```go
+// ✅ 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:
+
+```bash
+# ✅ 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
+
+```bash
+# ✅ 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:
+
+```yaml
+# 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
+
+```go
+// 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