Apache Sling XSS Protection

This module is part of the Apache Sling project.

The Apache Sling XSS Bundle provides two services for escaping and filtering XSS-prone user-submitted content:

1. org.apache.sling.xss.XSSAPI
2. org.apache.sling.xss.XSSFilter

It also exposes ProtectionContext for context-aware escaping behavior.

See the JavaDoc for the complete API surface.

Runtime and implementation notes

• Requires Java 11+ (the project is also built in CI with newer JDKs, including Java 25).
• Uses OSGi R7 Declarative Services.
• Uses OWASP Java Encoder and a custom Jackson-based AntiSamy XML policy parser.
• Uses owasp-java-html-sanitizer for HTML sanitization.
• Embeds ESAPI, Batik CSS, and HTML sanitizer packages as private bundle packages to avoid OSGi import conflicts.
• Includes optional invalid-href metrics integration via Sling Commons Metrics.
• Keeps Sling metrics package imports optional at runtime.
• Web console rendering escapes request-derived values (for example consoleRoot) before interpolation to prevent XSS in the plugin UI.
• Excludes legacy/conflicting transitive logging dependencies such as commons-logging and does not depend on Log4j 1.x.
• Uses a JDK-version-aware sanitizer adapter path to support both legacy and newer JDK behavior.

Build and test

# Build and package (skip tests)
mvn clean package -DskipTests

# Full build with tests
mvn clean verify

# Run all tests
mvn test

# Run a single test class
mvn test -Dtest=XSSAPIImplTest

# Run a single test method
mvn test -Dtest=XSSAPIImplTest#testGetValidHref

# Run policy parser / sanitizer regression tests
mvn test -Dtest=AntiSamyPolicyWithAdditionalGlobalAndDynamicConditionsTest

# Check / apply formatting
mvn spotless:check
mvn spotless:apply

# OSGi baseline check
mvn verify -Pbaseline

# Generate coverage report
mvn verify jacoco:report

Repository layout

bnd.bnd                               # OSGi bundle manifest overrides (private package embedding)
pom.xml
src/
  main/
    appended-resources/
      META-INF/
        LICENSE
        NOTICE
    java/
      org/apache/sling/xss/          # Public API
      org/apache/sling/xss/impl/     # OSGi service implementations
      org/apache/sling/xss/impl/xml/ # AntiSamy XML policy parser
      org/apache/sling/xss/impl/style/      # CSS validation via Batik
      org/apache/sling/xss/impl/status/     # Web console status service
      org/apache/sling/xss/impl/webconsole/ # Web console plugin
      org/owasp/html/                # Sanitizer extensions
    resources/
      ESAPI.properties
      validation.properties
      SLING-INF/
      webconsole/
  test/
    java/
      org/apache/sling/xss/impl/     # XSS API/filter/sanitizer tests
      org/apache/sling/xss/impl/xml/ # XML policy parser tests
    resources/                       # AntiSamy XML fixtures and test logging config