This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-xss.git
The following commit(s) were added to refs/heads/master by this push:
new 8ed8083 docs: update AGENTS.md and README.md with dependency and
layout notes (#69)
8ed8083 is described below
commit 8ed8083f0e363c38cf7bd991541da28e14fed0c8
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 16:43:45 2026 +0200
docs: update AGENTS.md and README.md with dependency and layout notes (#69)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 10 ++++++----
README.md | 16 ++++++++++++----
2 files changed, 18 insertions(+), 8 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index ff58921..ff42385 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,9 +59,9 @@ src/
SLING-INF/ # Sling resource definitions
webconsole/ # Web console static assets
test/
- java/org/apache/sling/xss/impl/ # JUnit 5 tests for XSS
API/filter/sanitizer behavior
+ java/org/apache/sling/xss/impl/ # JUnit 5 tests for XSS
API/filter/sanitizer/status behavior
java/org/apache/sling/xss/impl/xml/ # XML policy parser tests
- resources/ # AntiSamy XML config fixtures used by
tests
+ resources/ # AntiSamy XML fixtures + test logging
config
bnd.bnd # OSGi bundle manifest overrides (private
package embedding)
pom.xml
```
@@ -75,6 +75,7 @@ pom.xml
- ESAPI, Batik, and owasp-html-sanitizer are embedded via `bnd.bnd` private
packages — do not add OSGi `Import-Package` for them.
- Invalid href metrics are emitted via `XSSMetricsService` and
`org.apache.sling.commons.metrics` when a `MetricsService` is available
(optional dynamic DS reference).
- In the web console plugin, always HTML-escape request-derived values (for
example `consoleRoot`) before interpolating into markup
(`StringEscapeUtils.escapeHtml4`).
+- Keep optional metrics wiring optional at runtime (`resolution:=optional` in
`bnd.bnd` for Sling metrics packages).
- Formatting is enforced by Spotless (inherited from `sling-bundle-parent`).
Run `mvn spotless:apply` before committing.
- 4-space indentation, no wildcard imports in non-generated code.
- License header required on every source file (enforced by Apache RAT).
@@ -88,10 +89,10 @@ pom.xml
# Testing Guidelines
-- Framework: JUnit 5 (`junit-jupiter` 5.8.2) + Mockito 4 + Sling Mock
(`sling-mock.junit5`).
+- Framework: JUnit 5 (`junit-jupiter` 5.8.2) + Mockito 4.11 + Sling Mock
(`sling-mock.junit5` 3.0.0).
- Test files live in `src/test/java/org/apache/sling/xss/impl/`.
- XML parser tests live in `src/test/java/org/apache/sling/xss/impl/xml/`.
-- AntiSamy XML policy fixtures live in `src/test/resources/` (e.g.,
`configWithoutHref.xml`, `configWithAdditionalGlobalAndDynamicConditions.xml`,
`configWithoutDifferentCaseDuplicateLiterals.xml`).
+- AntiSamy XML policy fixtures live in `src/test/resources/` (e.g.,
`configWithoutHref.xml`, `configWithAdditionalGlobalAndDynamicConditions.xml`,
`configWithoutDifferentCaseDuplicateLiterals.xml`) and test logging config is
in `src/test/resources/logging.properties`.
- JaCoCo coverage is scoped to `org/apache/sling/xss/**` only (excludes
embedded third-party classes).
- Run coverage: `mvn verify` then open `target/site/jacoco/index.html`.
@@ -99,6 +100,7 @@ pom.xml
- ESAPI classes are embedded (unpacked from the ESAPI jar during
`prepare-package`). Changes to the ESAPI version may require updating `bnd.bnd`
private-package exclusions.
- `commons-logging`, `commons-collections`, `commons-lang`, and `xml-apis` are
explicitly excluded from ESAPI/Batik transitive deps to avoid OSGi conflicts —
do not re-introduce them.
+- The runtime intentionally avoids Log4j 1.x; keep transitive logging
dependencies constrained to SLF4J-compatible paths.
- The `sling-org-apache-sling-xss` artifact itself is excluded from
`sling-mock.junit5` in test scope to prevent stale OSGi metadata from older
releases interfering with tests.
- `ESAPI.properties` and `validation.properties` lack Apache license headers
by design; they are RAT-excluded in `pom.xml`.
- `AntiSamyPolicyAdapter` intentionally uses `sun.misc.Unsafe` plus a Java 22+
fallback path to clear html-sanitizer attribute guards across JDK versions;
avoid refactoring this blindly.
diff --git a/README.md b/README.md
index d14d3fd..e0e9d96 100644
--- a/README.md
+++ b/README.md
@@ -6,23 +6,27 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The Apache Sling XSS Bundle provides two services for escaping and filtering
XSS-prone user submitted content:
+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
-See the JavaDoc of each service for the complete API surface.
+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 AntiSamy XML policy parser.
+- 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
@@ -59,16 +63,20 @@ mvn verify jacoco:report
## Repository layout
```text
+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/ # Runtime status service
+ 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/
