CUI-HTTP

Table of Contents

• 1. Status
• 2. What is it?
• 3. Maven Coordinates
• 4. Components
  • 4.1. HTTP Security Validation
  • 4.2. HTTP Client Handlers
  • 4.3. Forwarded / Reverse-Proxy Header Resolution
  • 4.4. Security Testing
• 5. Usage Example
• 6. Build Commands
• 7. Documentation
  • 7.1. Component Documentation
  • 7.2. Specifications
  • 7.3. Analysis
• 8. Dependencies

1. Status

Performance Benchmarks

Generated Documentation on github-pages

2. What is it?

Security-focused HTTP utilities library providing validation pipelines, SSL/TLS context management, and HTTP client handlers with comprehensive attack pattern detection.

3. Maven Coordinates

<dependency>
    <groupId>de.cuioss</groupId>
    <artifactId>cui-http</artifactId>
</dependency>

Test artifact:

<dependency>
    <groupId>de.cuioss</groupId>
    <artifactId>cui-http</artifactId>
    <classifier>generators</classifier>
    <scope>test</scope>
</dependency>

4. Components

4.1. HTTP Security Validation

Security Validation Framework:

• Validation pipelines for paths, parameters, headers

• Attack pattern detection (path traversal, parameter injection, protocol violations)

• Configuration via SecurityConfigurationBuilder

4.2. HTTP Client Handlers

HTTP Client Handlers:

• HttpHandler - Builder-based HTTP client with SSL defaults

• SecureSSLContextProvider - TLS 1.2+ SSL context

• HttpStatusFamily - RFC 7231 status classification

4.3. Forwarded / Reverse-Proxy Header Resolution

Forwarded Header Resolution:

• Resolves X-Forwarded-, RFC 7239 Forwarded, and NiFi X-Proxy into one sanitized result

• Scheme / host / port / context-path / client-IP with configurable per-field precedence

• Secure-by-default trust model (allowlist, trustAll, trusted-proxy CIDR walk)

• Built-in sanitization via the security pipelines; transport-agnostic Function<String,String> accessor

4.4. Security Testing

Test Generators:

• Attack databases with CVE patterns and OWASP vectors

• Test data generators for security validation

• JUnit 5 integration with ArgumentsProvider

5. Usage Example

// HTTP Client
HttpHandler handler = HttpHandler.builder()
    .uri("https://api.example.com/data")
    .connectionTimeoutSeconds(10)
    .build();

HttpClient client = handler.createHttpClient();
HttpRequest request = handler.requestBuilder()
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

// Security Validation
SecurityConfiguration config = SecurityConfiguration.builder()
    .maxPathLength(2048)
    .build();

URLPathValidationPipeline pipeline = new URLPathValidationPipeline(
    config, new SecurityEventCounter());

String validated = pipeline.validate("/api/users/123").orElseThrow();

6. Build Commands

The following standard Maven commands are provided for human contributors:

./mvnw clean install          # Build and install
./mvnw test                   # Run tests
./mvnw -Ppre-commit clean verify  # Pre-commit checks (MANDATORY)
./mvnw -Pcoverage clean verify    # Coverage report

Note	AI coding agents must not hard-code ./mvnw/mvn; they invoke builds via the canonical build-executor commands documented in the "Build Commands" section of CLAUDE.md.

7. Documentation

7.1. Component Documentation

• HTTP Client Handlers

• Forwarded / Reverse-Proxy Header Resolution

• Security Validation Framework

• Security Testing Framework

7.2. Specifications

• HTTP Security Overview

• Requirements Documentation

• Architecture Specification

• Pipeline Standards

• Testing Framework

7.3. Analysis

• OWASP Best Practices

• CVE Analysis

• HTTP/1.x Protocol Vulnerabilities

• Cookie Security Analysis

8. Dependencies

• Java 21+

• cui-java-tools

• JSpecify (null-safety)

• Lombok (code generation)

• JUnit 5 (test only)