Files

GitHub Actions f4ef79def3 chore: repo cleanup by archiving plans / reports

2026-02-19 16:34:10 +00:00

30 KiB

Raw Blame History

SSRF Remediation Plan: settings_handler.go TestPublicURL

Status: Planning - Revised Priority: Critical Affected File: backend/internal/api/handlers/settings_handler.go CodeQL Alert: SSRF vulnerability via user-controlled URL input Date: 2025-12-23 Last Updated: 2025-12-23 (Supervisor Review)

Executive Summary

Key Security Insights

Triple-Layer Defense-in-Depth:
- Layer 1: Format validation (scheme, paths)
- Layer 2: Pre-validation with DNS resolution (blocks private IPs)
- Layer 3: Runtime re-validation at connection time (eliminates TOCTOU)
DNS Rebinding/TOCTOU Protection:
- ssrfSafeDialer() performs second DNS resolution at connection time
- Even if attacker changes DNS between validations, connection is blocked
- Closes the Time-of-Check Time-of-Use (TOCTOU) window
URL Parser Differential Protection:
- ValidateExternalURL() rejects URLs with embedded credentials
- Prevents http://evil.com@127.0.0.1/ bypass attacks
CodeQL Taint Breaking:
- Works because ValidateExternalURL() returns new value (not passthrough)
- Static analysis sees taint chain broken by value transformation
- NOT based on function name recognition
HTTP Status Code Consistency:
- SSRF blocks return 200 OK with reachable: false (existing behavior)
- Only format errors return 400 Bad Request
- Maintains consistent API contract for clients

1. Vulnerability Analysis

1.1 Data Flow

CodeQL has identified the following taint flow:

Source (Line 285): req.URL (user input from TestURLRequest)
    ↓
Step 2-7: utils.ValidateURL() - Format validation only
    ↓
Step 8: normalized URL (still tainted)
    ↓
Step 9-10: utils.TestURLConnectivity() → http.NewRequestWithContext() [SINK]

1.2 Root Cause

Format Validation Only: utils.ValidateURL() performs only superficial format checks:

Validates scheme (http/https)
Rejects paths beyond "/"
Returns warning for HTTP
Does NOT validate for SSRF risks (private IPs, localhost, cloud metadata)

Runtime Protection Not Recognized: While TestURLConnectivity() has SSRF protection via ssrfSafeDialer():

The dialer blocks private IPs at connection time
CodeQL's static analysis cannot detect this runtime protection
The taint chain remains unbroken from the analysis perspective

The Problem: Static analysis sees unvalidated user input flowing directly to a network request sink without explicit SSRF pre-validation.

1.3 Existing Security Infrastructure

We have a comprehensive SSRF validator already implemented:

File: backend/internal/security/url_validator.go

ValidateExternalURL(): Full SSRF protection with DNS resolution
Blocks private IPs, loopback, link-local, cloud metadata endpoints
Rejects URLs with embedded credentials (prevents parser differentials like http://evil.com@127.0.0.1/)
Configurable options (WithAllowLocalhost, WithAllowHTTP, WithTimeout)
Well-tested and production-ready

File: backend/internal/utils/url_testing.go

TestURLConnectivity(): Has runtime SSRF protection via ssrfSafeDialer()
DNS Rebinding/TOCTOU Protection: ssrfSafeDialer() performs second DNS resolution and IP validation at connection time
isPrivateIP(): Comprehensive IP blocking logic
Already protects against SSRF at connection time

Defense-in-Depth Architecture:

Handler Validation → ValidateExternalURL() - Pre-validates URL and resolves DNS
TestURLConnectivity Re-Validation → ssrfSafeDialer() - Validates IP again at connection time
This eliminates DNS rebinding/TOCTOU vulnerabilities (attacker can't change DNS between validations)

2. Fix Options

Option A: Add Explicit Pre-Validation in Handler (RECOMMENDED)

Description: Insert explicit SSRF validation in TestPublicURL handler before calling TestURLConnectivity().

Implementation:

func (h *SettingsHandler) TestPublicURL(c *gin.Context) {
 // ... existing auth check ...

 var req TestURLRequest
 if err := c.ShouldBindJSON(&req); err != nil {
  c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
  return
 }

 // Step 1: Format validation
 normalized, _, err := utils.ValidateURL(req.URL)
 if err != nil {
  c.JSON(http.StatusBadRequest, gin.H{
   "reachable": false,
   "error":     "Invalid URL format",
  })
  return
 }

 // Step 2: SSRF validation (BREAKS TAINT CHAIN)
 validatedURL, err := security.ValidateExternalURL(normalized,
  security.WithAllowHTTP())
 if err != nil {
  c.JSON(http.StatusOK, gin.H{
   "reachable": false,
   "error":     err.Error(),
  })
  return
 }

 // Step 3: Connectivity test (now using validated URL)
 reachable, latency, err := utils.TestURLConnectivity(validatedURL)
 // ... rest of handler ...
}

Pros:

✅ Minimal code changes (localized to one handler)
✅ Explicitly breaks taint chain for CodeQL
✅ Uses existing, well-tested security.ValidateExternalURL()
✅ Clear separation of concerns (format → security → connectivity)
✅ Easy to audit and understand

Cons:

❌ Requires adding security package import to handler
❌ Two-step validation might seem redundant (but is defense-in-depth)

Option B: Enhance ValidateURL() with SSRF Checks

Description: Modify utils.ValidateURL() to include SSRF validation.

Implementation:

// In utils/url.go
func ValidateURL(rawURL string, options ...security.ValidationOption) (normalized string, warning string, err error) {
 // Parse URL
 parsed, parseErr := url.Parse(rawURL)
 if parseErr != nil {
  return "", "", parseErr
 }

 // Validate scheme
 if parsed.Scheme != "http" && parsed.Scheme != "https" {
  return "", "", &url.Error{Op: "parse", URL: rawURL, Err: nil}
 }

 // Warn if HTTP
 if parsed.Scheme == "http" {
  warning = "Using HTTP is not recommended. Consider using HTTPS for security."
 }

 // Reject URLs with path components
 if parsed.Path != "" && parsed.Path != "/" {
  return "", "", &url.Error{Op: "validate", URL: rawURL, Err: nil}
 }

 // SSRF validation (NEW)
 normalized = strings.TrimSuffix(rawURL, "/")
 validatedURL, err := security.ValidateExternalURL(normalized,
  security.WithAllowHTTP())
 if err != nil {
  return "", "", fmt.Errorf("SSRF validation failed: %w", err)
 }

 return validatedURL, warning, nil
}

Pros:

✅ Single validation point
✅ All callers of ValidateURL() automatically get SSRF protection
✅ No changes needed in handlers

Cons:

❌ Changes signature/behavior of widely-used function
❌ Mixes concerns (format validation + security validation)
❌ May break existing tests that expect ValidateURL() to accept localhost
❌ Adds cross-package dependency (utils → security)
❌ Could impact other callers unexpectedly

Option C: Create Dedicated ValidateURLForTesting() Wrapper

Description: Create a new function specifically for the test endpoint that combines all validations.

Implementation:

// In utils/url.go or security/url_validator.go
func ValidateURLForTesting(rawURL string) (normalized string, warning string, err error) {
 // Step 1: Format validation
 normalized, warning, err = ValidateURL(rawURL)
 if err != nil {
  return "", "", err
 }

 // Step 2: SSRF validation
 validatedURL, err := security.ValidateExternalURL(normalized,
  security.WithAllowHTTP())
 if err != nil {
  return "", warning, fmt.Errorf("security validation failed: %w", err)
 }

 return validatedURL, warning, nil
}

Handler Usage:

func (h *SettingsHandler) TestPublicURL(c *gin.Context) {
 // ... auth check ...

 var req TestURLRequest
 if err := c.ShouldBindJSON(&req); err != nil {
  c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
  return
 }

 // Combined validation
 normalized, _, err := utils.ValidateURLForTesting(req.URL)
 if err != nil {
  c.JSON(http.StatusBadRequest, gin.H{
   "reachable": false,
   "error":     err.Error(),
  })
  return
 }

 // Connectivity test
 reachable, latency, err := utils.TestURLConnectivity(normalized)
 // ... rest of handler ...
}

Pros:

✅ Clean API for the specific use case
✅ Doesn't modify existing ValidateURL() behavior
✅ Self-documenting function name
✅ Encapsulates the two-step validation

Cons:

❌ Adds another function to maintain
❌ Possible confusion about when to use ValidateURL() vs ValidateURLForTesting()

3. Recommended Approach: Option A (Explicit Pre-Validation)

Rationale:

Minimal Risk: Localized change to a single handler
Clear Intent: The two-step validation makes security concerns explicit
Defense in Depth: Format validation + SSRF validation + runtime protection
Static Analysis Friendly: CodeQL can clearly see the taint break
Reuses Battle-Tested Code: Leverages existing security.ValidateExternalURL()
No Breaking Changes: Doesn't modify shared utility functions

4. Implementation Plan

4.0 HTTP Status Code Strategy

Existing Behavior (from settings_handler_test.go:605):

SSRF blocks return 200 OK with reachable: false and error message
This maintains consistent API contract: endpoint always returns structured JSON
Only format validation errors return 400 Bad Request

Rationale:

SSRF validation is a connectivity constraint, not a request format error
Returning 200 allows clients to distinguish between "URL malformed" vs "URL blocked by security policy"
Consistent with existing test: TestSettingsHandler_TestPublicURL_PrivateIPBlocked expects StatusOK

Implementation Rule:

400 Bad Request → Format errors (invalid scheme, paths, malformed JSON)
200 OK → All SSRF/connectivity failures (return reachable: false with error details)

4.1 Code Changes

File: backend/internal/api/handlers/settings_handler.go

Add import:

import (
    // ... existing imports ...
    "github.com/Wikid82/charon/backend/internal/security"
)

Modify TestPublicURL handler (lines 269-316):

func (h *SettingsHandler) TestPublicURL(c *gin.Context) {
    // Admin-only access check
    role, exists := c.Get("role")
    if !exists || role != "admin" {
        c.JSON(http.StatusForbidden, gin.H{"error": "Admin access required"})
        return
    }

    // Parse request body
    type TestURLRequest struct {
        URL string `json:"url" binding:"required"`
    }

    var req TestURLRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    // Step 1: Validate URL format (scheme, no paths)
    normalized, _, err := utils.ValidateURL(req.URL)
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "reachable": false,
            "error":     "Invalid URL format",
        })
        return
    }

    // Step 2: SSRF validation (DNS resolution + IP blocking)
    // This explicitly validates against private IPs, loopback, link-local,
    // and cloud metadata endpoints, breaking the taint chain for static analysis.
    validatedURL, err := security.ValidateExternalURL(normalized,
        security.WithAllowHTTP())
    if err != nil {
        c.JSON(http.StatusOK, gin.H{
            "reachable": false,
            "error":     err.Error(),
        })
        return
    }

    // Step 3: Perform connectivity test with runtime SSRF protection
    reachable, latency, err := utils.TestURLConnectivity(validatedURL)
    if err != nil {
        c.JSON(http.StatusOK, gin.H{
            "reachable": false,
            "error":     err.Error(),
        })
        return
    }

    // Return success response
    c.JSON(http.StatusOK, gin.H{
        "reachable": reachable,
        "latency":   latency,
        "message":   fmt.Sprintf("URL reachable (%.0fms)", latency),
    })
}

4.2 Test Cases

File: backend/internal/api/handlers/settings_handler_test.go

Add comprehensive test cases:

func TestTestPublicURL_SSRFProtection(t *testing.T) {
 tests := []struct {
  name           string
  url            string
  expectedStatus int
  expectReachable bool
  expectError    string
 }{
  {
   name:           "Valid public URL",
   url:            "https://example.com",
   expectedStatus: http.StatusOK,
   expectReachable: true,
  },
  {
   name:           "Private IP blocked - 10.0.0.1",
   url:            "http://10.0.0.1",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Localhost blocked - 127.0.0.1",
   url:            "http://127.0.0.1",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Localhost blocked - localhost",
   url:            "http://localhost:8080",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Cloud metadata blocked - 169.254.169.254",
   url:            "http://169.254.169.254",
   expectedStatus: http.StatusOK,
   expectError:    "cloud metadata",
  },
  {
   name:           "Link-local blocked - 169.254.1.1",
   url:            "http://169.254.1.1",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Private IPv4 blocked - 192.168.1.1",
   url:            "http://192.168.1.1",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Private IPv4 blocked - 172.16.0.1",
   url:            "http://172.16.0.1",
   expectedStatus: http.StatusOK,
   expectError:    "private ip",
  },
  {
   name:           "Invalid scheme rejected",
   url:            "ftp://example.com",
   expectedStatus: http.StatusBadRequest,
   expectError:    "Invalid URL format",
  },
  {
   name:           "Path component rejected",
   url:            "https://example.com/path",
   expectedStatus: http.StatusBadRequest,
   expectError:    "Invalid URL format",
  },
  {
   name:           "Empty URL field",
   url:            "",
   expectedStatus: http.StatusBadRequest,
   expectError:    "required",
  },
  {
   name:           "URL with embedded credentials blocked",
   url:            "http://user:pass@example.com",
   expectedStatus: http.StatusOK,
   expectError:    "credentials",
  },
  {
   name:           "HTTP URL allowed with WithAllowHTTP option",
   url:            "http://example.com",
   expectedStatus: http.StatusOK,
   expectReachable: true, // Should succeed if example.com is reachable
  },
 }

 for _, tt := range tests {
  t.Run(tt.name, func(t *testing.T) {
   // Setup test environment
   db := setupTestDB(t)
   handler := NewSettingsHandler(db)
   router := gin.New()
   router.Use(func(c *gin.Context) {
    c.Set("role", "admin")
   })
   router.POST("/api/settings/test-url", handler.TestPublicURL)

   // Create request
   body := fmt.Sprintf(`{"url": "%s"}`, tt.url)
   req, _ := http.NewRequest("POST", "/api/settings/test-url",
    strings.NewReader(body))
   req.Header.Set("Content-Type", "application/json")

   // Execute request
   w := httptest.NewRecorder()
   router.ServeHTTP(w, req)

   // Verify response
   assert.Equal(t, tt.expectedStatus, w.Code)

   var resp map[string]interface{}
   err := json.Unmarshal(w.Body.Bytes(), &resp)
   assert.NoError(t, err)

   if tt.expectError != "" {
    assert.Contains(t,
     strings.ToLower(resp["error"].(string)),
     strings.ToLower(tt.expectError))
   }

   if tt.expectReachable {
    assert.True(t, resp["reachable"].(bool))
   }
  })
 }
}

func TestTestPublicURL_RequiresAdmin(t *testing.T) {
 db := setupTestDB(t)
 handler := NewSettingsHandler(db)
 router := gin.New()

 // Non-admin user
 router.Use(func(c *gin.Context) {
  c.Set("role", "user")
 })
 router.POST("/api/settings/test-url", handler.TestPublicURL)

 body := `{"url": "https://example.com"}`
 req, _ := http.NewRequest("POST", "/api/settings/test-url",
  strings.NewReader(body))
 req.Header.Set("Content-Type", "application/json")

 w := httptest.NewRecorder()
 router.ServeHTTP(w, req)

 assert.Equal(t, http.StatusForbidden, w.Code)
}

4.3 Documentation

Add inline comment in the handler explaining the multi-layer protection:

// TestPublicURL performs a server-side connectivity test with comprehensive SSRF protection.
// This endpoint implements defense-in-depth security:
// 1. Format validation: Ensures valid HTTP/HTTPS URLs without path components
// 2. SSRF validation: Pre-validates DNS resolution and blocks private/reserved IPs
// 3. Runtime protection: ssrfSafeDialer validates IPs again at connection time
// This multi-layer approach satisfies both static analysis (CodeQL) and runtime security.

5. Similar Issues in Codebase

5.1 Other Handlers Using User URLs

Search Results: No other handlers currently accept user-provided URLs for outbound requests.

Checked Files:

remote_server_handler.go: Uses net.DialTimeout() for TCP, not HTTP requests
proxy_host_handler.go: Manages proxy configs but doesn't make outbound requests
Other handlers: No URL input parameters

Conclusion: This is an isolated instance. The TestPublicURL handler is the only place where user-supplied URLs are used for outbound HTTP requests.

5.2 Preventive Measures

To prevent similar issues in the future:

Code Review Checklist: Add SSRF check for any handler accepting URLs
Linting Rule: Consider adding a custom linter rule to detect http.NewRequest*() calls with untainted strings
Documentation: Update security guidelines to require SSRF validation for URL inputs

6. CodeQL Satisfaction Strategy

6.1 Why CodeQL Flags This

CodeQL's taint analysis tracks data flow from sources (user input) to sinks (network operations). It flags this because:

Source: req.URL is user-controlled
No Explicit Barrier: ValidateURL() doesn't signal to CodeQL that it performs security checks
Sink: The tainted string reaches http.NewRequestWithContext()

6.2 How Our Fix Satisfies CodeQL

By inserting security.ValidateExternalURL():

Returns New Value (Breaks Taint Chain): The function performs DNS resolution and IP validation, then returns a new string value. From static analysis perspective, this new return value is not the same tainted input—it's a validated, sanitized result. CodeQL's taint tracking stops here because the data flow breaks.
Technical Explanation: Static analysis tools like CodeQL track data flow through variables. When a function takes tainted input and returns a different value (not just a passthrough), the analysis must assume the return value could be untainted. Since ValidateExternalURL() performs validation logic (DNS resolution, IP checks) before returning, CodeQL treats the output as clean.
Defense-in-Depth Signal: Using a dedicated security validation function makes the security boundary explicit, making code review and auditing easier.

Important: CodeQL does NOT recognize ValidateExternalURL() by name alone. It works because the function returns a new value that breaks the taint chain. Any validation function that transforms input into a new output would have the same effect.

6.3 Expected Result

After implementation:

✅ CodeQL should recognize the taint chain is broken
✅ Alert should resolve or downgrade to "False Positive"
✅ Future scans should not flag this pattern

6.5 DNS Rebinding/TOCTOU Protection Architecture

The TOCTOU Problem

A classic SSRF bypass technique is DNS rebinding, also known as Time-of-Check Time-of-Use (TOCTOU):

Check Time: Handler calls ValidateExternalURL() which resolves attacker.com to public IP 1.2.3.4 ✅ Allowed
Use Time: Milliseconds later, TestURLConnectivity() resolves attacker.com again but attacker has changed DNS to 127.0.0.1 ❌ SSRF!

Our Defense-in-Depth Solution

Triple-Layer Protection:

Layer 1: Format Validation (utils.ValidateURL())
- Validates URL scheme (http/https only)
- Blocks URLs with paths (prevents bypasses like http://example.com/../internal)
- Rejects invalid URL formats
Layer 2: Pre-Validation (security.ValidateExternalURL())
- Performs DNS resolution
- Validates resolved IPs against block list
- Blocks embedded credentials (prevents http://evil.com@127.0.0.1/ parser differentials)
- Purpose: Breaks CodeQL taint chain and provides early fail-fast behavior
Layer 3: Runtime Validation (TestURLConnectivity() → ssrfSafeDialer())
- Second DNS resolution at connection time
- Validates ALL resolved IPs before connecting
- Uses first valid IP for connection (prevents IP hopping)
- Purpose: Eliminates DNS rebinding/TOCTOU window

From backend/internal/utils/url_testing.go:

// ssrfSafeDialer creates a custom dialer that validates IP addresses at connection time.
// This prevents DNS rebinding attacks by validating the IP just before connecting.
func ssrfSafeDialer() func(ctx context.Context, network, addr string) (net.Conn, error) {
 return func(ctx context.Context, network, addr string) (net.Conn, error) {
  // Resolve DNS with context timeout
  ips, err := net.DefaultResolver.LookupIPAddr(ctx, host)
  if err != nil {
   return nil, fmt.Errorf("DNS resolution failed: %w", err)
  }

  // Validate ALL resolved IPs - if any are private, reject immediately
  for _, ip := range ips {
   if isPrivateIP(ip.IP) {
    return nil, fmt.Errorf("access to private IP addresses is blocked (resolved to %s)", ip.IP)
   }
  }

  // Connect to the first valid IP (prevents DNS rebinding)
  dialer := &net.Dialer{Timeout: 5 * time.Second}
  return dialer.DialContext(ctx, network, net.JoinHostPort(ips[0].IP.String(), port))
 }
}

Why This Eliminates TOCTOU

Even if an attacker changes DNS between Layer 2 and Layer 3:

Layer 2 validates at time T1: attacker.com → 1.2.3.4 ✅
Attacker changes DNS
Layer 3 resolves again at time T2: attacker.com → 127.0.0.1 ❌ BLOCKED by ssrfSafeDialer

The second validation happens inside the HTTP client's dialer, at the moment of connection. This closes the TOCTOU window.

6.6 URL Parser Differential Protection

The Attack Vector

Some SSRF bypasses exploit differences in how various URL parsers interpret URLs:

http://evil.com@127.0.0.1/

Vulnerable Parser interprets as:

User: evil.com
Host: 127.0.0.1 ← SSRF target

Strict Parser interprets as:

User: evil.com
Host: 127.0.0.1
But rejects due to embedded credentials

Our Protection

security.ValidateExternalURL() (in url_validator.go) rejects URLs with embedded credentials:

if parsed.User != nil {
    return "", fmt.Errorf("URL must not contain embedded credentials")
}

This prevents parser differential attacks where credentials are used to disguise the real target.

6.7 Pattern Comparison: Why This Handler Uses Simple Validation

Our Pattern (TestPublicURL)

// Step 1: Format validation
normalized, _, err := utils.ValidateURL(req.URL)

// Step 2: SSRF pre-validation
validatedURL, err := security.ValidateExternalURL(normalized, security.WithAllowHTTP())

// Step 3: Test connectivity
reachable, latency, err := utils.TestURLConnectivity(validatedURL)

Characteristics:

Two-step validation (format → security)
Uses ValidateExternalURL() for simplicity
Relies on ssrfSafeDialer() for runtime protection
Use Case: Simple connectivity test, no custom IP selection needed

Security Notifications Pattern

Reference: backend/internal/api/handlers/security_notifications.go (lines 50-65)

if config.WebhookURL != "" {
    if _, err := security.ValidateExternalURL(config.WebhookURL,
        security.WithAllowLocalhost(),
        security.WithAllowHTTP(),
    ); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{
            "error": fmt.Sprintf("Invalid webhook URL: %v", err),
        })
        return
    }
}

Characteristics:

Single validation step
Uses WithAllowLocalhost() option (allows testing webhooks locally)
No connectivity test required (URL is stored, not immediately used)
Use Case: Configuration storage, not immediate outbound request

Why The Difference?

Aspect	TestPublicURL	Security Notifications
Immediate Use	Yes, tests connectivity now	No, stores for later use
Localhost	Blocked (security risk)	Allowed (dev convenience)
HTTP Allowed	Yes (some APIs are HTTP-only)	Yes (same reason)
Runtime Protection	Yes (ssrfSafeDialer)	N/A (no immediate request)

Both handlers use the same ValidateExternalURL() function but with different options based on their use case.

7. Testing Strategy

7.1 Unit Tests

✅ Test all SSRF scenarios (private IPs, localhost, cloud metadata)
✅ Test valid public URLs (ensure functionality still works)
✅ Test authorization (admin-only requirement)
✅ Test format validation errors
✅ Test connectivity failures (unreachable URLs)

7.2 Integration Tests

Deploy fix to staging environment
Test with real DNS resolution (ensure no false positives)
Verify error messages are user-friendly
Confirm public URLs are still testable

Future Work: Add DNS rebinding integration test:

Set up test DNS server that changes responses dynamically
Verify that ssrfSafeDialer() blocks the rebind attempt
Test sequence: Initial DNS → Public IP (allowed) → DNS change → Private IP (blocked)
This requires test infrastructure not currently available but should be prioritized for comprehensive security validation

7.3 Security Validation

Run CodeQL scan after implementation
Verify alert is resolved
Test with OWASP ZAP or Burp Suite to confirm SSRF protection
Penetration test with DNS rebinding attacks

8. Rollout Plan

Phase 1: Implementation (Day 1)

Implement code changes in settings_handler.go
Add comprehensive unit tests
Verify existing tests still pass

Phase 2: Validation (Day 1-2)

Run CodeQL scan locally
Manual security testing
Code review with security focus

Phase 3: Deployment (Day 2-3)

Merge to main branch
Deploy to staging
Run automated security scan
Deploy to production

Phase 4: Verification (Day 3+)

Monitor logs for validation errors
Verify CodeQL alert closure
Update security documentation

9. Risk Assessment

Security Risks (PRE-FIX)

Critical: Admins could test internal endpoints (localhost, metadata services)
High: Potential information disclosure about internal network topology
Medium: DNS rebinding attack surface

Security Risks (POST-FIX)

None: Comprehensive SSRF protection at multiple layers

Functional Risks

Low: Error messages might be too restrictive if users try to test localhost
- Mitigation: Clear error message explaining security rationale
Low: Public URL testing might fail due to DNS issues
- Mitigation: Existing timeout and error handling remains in place

10. Success Criteria

✅ Security:

CodeQL SSRF alert resolved
All SSRF test vectors blocked (localhost, private IPs, cloud metadata)
No regression in other security scans

✅ Functionality:

Public URLs can still be tested successfully
Appropriate error messages for invalid/blocked URLs
Latency measurements remain accurate

✅ Code Quality:

100% test coverage for new code paths
No breaking changes to existing functionality
Clear documentation and inline comments

11. References

OWASP SSRF: https://owasp.org/www-community/attacks/Server_Side_Request_Forgery
CWE-918 (SSRF): https://cwe.mitre.org/data/definitions/918.html
DNS Rebinding Attacks: https://en.wikipedia.org/wiki/DNS_rebinding
TOCTOU Vulnerabilities: https://cwe.mitre.org/data/definitions/367.html
URL Parser Confusion: https://claroty.com/team82/research/exploiting-url-parsing-confusion
Existing Implementation: backend/internal/security/url_validator.go
Runtime Protection: backend/internal/utils/url_testing.go::ssrfSafeDialer()
Comparison Pattern: backend/internal/api/handlers/security_notifications.go

Appendix: Alternative Mitigations Considered

A. Whitelist-Only Approach

Description: Only allow testing URLs from a pre-configured whitelist. Rejected: Too restrictive for legitimate admin use cases.

B. Remove Test Endpoint

Description: Remove the TestPublicURL endpoint entirely. Rejected: Legitimate functionality for validating public URL configuration.

C. Client-Side Testing Only

Description: Move connectivity testing to the frontend. Rejected: Cannot validate server-side reachability from client.

Plan Status: ✅ Revised and Ready for Implementation Revision Date: 2025-12-23 (Post-Supervisor Review) Next Steps:

Backend_Dev to implement Option A following this revised specification
Ensure HTTP status codes match existing test behavior (200 OK for SSRF blocks)
Use err.Error() directly without wrapping
Verify triple-layer protection works end-to-end

Key Changes from Original Plan:

Fixed CodeQL taint analysis explanation (value transformation, not name recognition)
Documented DNS rebinding/TOCTOU protection via ssrfSafeDialer
Changed HTTP status codes to 200 OK for SSRF blocks (matches existing tests)
Fixed error message handling (no wrapper prefix)
Added URL parser differential protection documentation
Added pattern comparison with security_notifications.go
Added comprehensive architecture documentation for TestURLConnectivity
Added missing test cases (empty URL, embedded credentials, WithAllowHTTP)

30 KiB Raw Blame History

SSRF Remediation Plan: settings_handler.go TestPublicURL

Executive Summary

Key Security Insights

1. Vulnerability Analysis

1.1 Data Flow

1.2 Root Cause

1.3 Existing Security Infrastructure

2. Fix Options

Option A: Add Explicit Pre-Validation in Handler (RECOMMENDED)

Option B: Enhance ValidateURL() with SSRF Checks

Option C: Create Dedicated ValidateURLForTesting() Wrapper

3. Recommended Approach: Option A (Explicit Pre-Validation)

4. Implementation Plan

4.0 HTTP Status Code Strategy

4.1 Code Changes

4.2 Test Cases

4.3 Documentation

5. Similar Issues in Codebase

5.1 Other Handlers Using User URLs

5.2 Preventive Measures

6. CodeQL Satisfaction Strategy

6.1 Why CodeQL Flags This

6.2 How Our Fix Satisfies CodeQL

6.3 Expected Result

6.5 DNS Rebinding/TOCTOU Protection Architecture

The TOCTOU Problem

Our Defense-in-Depth Solution

Why This Eliminates TOCTOU

6.6 URL Parser Differential Protection

The Attack Vector

Our Protection

6.7 Pattern Comparison: Why This Handler Uses Simple Validation

Our Pattern (TestPublicURL)

Security Notifications Pattern

Why The Difference?

7. Testing Strategy

7.1 Unit Tests

7.2 Integration Tests

7.3 Security Validation

8. Rollout Plan

Phase 1: Implementation (Day 1)

Phase 2: Validation (Day 1-2)

Phase 3: Deployment (Day 2-3)

Phase 4: Verification (Day 3+)

9. Risk Assessment

Security Risks (PRE-FIX)

Security Risks (POST-FIX)

Functional Risks

10. Success Criteria

11. References

Appendix: Alternative Mitigations Considered

A. Whitelist-Only Approach

B. Remove Test Endpoint

C. Client-Side Testing Only

30 KiB

Raw Blame History