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 2630ff0 docs: update AGENTS.md and README.md with new features and
structure (#67)
2630ff0 is described below
commit 2630ff0d5d493934961db85bf80e6a92325ba235
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 11:09:42 2026 +0200
docs: update AGENTS.md and README.md with new features and structure (#67)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 20 ++++++++++++++++----
README.md | 19 +++++++++++++++----
2 files changed, 31 insertions(+), 8 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 04177ba..a1b6cfb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-OSGi bundle providing XSS protection for Apache Sling. Exposes `XSSAPI` and
`XSSFilter` services backed by OWASP AntiSamy (via a custom XML policy parser),
OWASP Java Encoder, and owasp-java-html-sanitizer. The bundle embeds ESAPI,
Batik CSS, and the HTML sanitizer as private packages (see `bnd.bnd`) to avoid
OSGi import conflicts. Requires Java 11+.
+OSGi bundle providing XSS protection for Apache Sling. Exposes `XSSAPI` and
`XSSFilter` services backed by OWASP AntiSamy (via a custom XML policy parser),
OWASP Java Encoder, and `owasp-java-html-sanitizer`. The bundle embeds ESAPI,
Batik CSS, and HTML sanitizer packages as private bundle packages (see
`bnd.bnd`) to avoid OSGi import conflicts. It also provides optional
invalid-href metrics integration via Sling Commons Metrics. Requires Java 11+
(and is CI-tested with newer JDKs, inclu [...]
# Core Commands
@@ -20,6 +20,9 @@ mvn test -Dtest=XSSAPIImplTest
# Run a single test method
mvn test -Dtest=XSSAPIImplTest#testGetValidHref
+# Run policy parser/sanitizer regression tests
+mvn test -Dtest=AntiSamyPolicyWithAdditionalGlobalAndDynamicConditionsTest
+
# Apply Spotless formatting (inherited from sling-bundle-parent)
mvn spotless:apply
@@ -38,9 +41,13 @@ mvn verify jacoco:report
```
src/
main/
+ appended-resources/
+ META-INF/
+ LICENSE
+ NOTICE
java/
org/apache/sling/xss/ # Public API: XSSAPI, XSSFilter,
ProtectionContext
- org/apache/sling/xss/impl/ # OSGi service implementations
(XSSAPIImpl, XSSFilterImpl, HtmlSanitizer…)
+ org/apache/sling/xss/impl/ # OSGi service implementations
(XSSAPIImpl, XSSFilterImpl, HtmlSanitizer, XSSMetricsService…)
org/apache/sling/xss/impl/xml/ # Custom AntiSamy XML policy parser
(Jackson-based)
org/apache/sling/xss/impl/style/ # CSS validation via Batik
org/apache/sling/xss/impl/status/ # Web console status service
@@ -50,8 +57,10 @@ src/
ESAPI.properties # ESAPI config (excluded from RAT)
validation.properties # ESAPI validation rules (excluded from
RAT)
SLING-INF/ # Sling resource definitions
+ webconsole/ # Web console static assets
test/
- java/org/apache/sling/xss/impl/ # JUnit 5 tests, one class per impl class
+ java/org/apache/sling/xss/impl/ # JUnit 5 tests for XSS
API/filter/sanitizer behavior
+ java/org/apache/sling/xss/impl/xml/ # XML policy parser tests
resources/ # AntiSamy XML config fixtures used by
tests
bnd.bnd # OSGi bundle manifest overrides (private
package embedding)
pom.xml
@@ -64,6 +73,7 @@ pom.xml
- All impl classes are in `org.apache.sling.xss.impl` and must stay in the
`Private-Package` declared in `bnd.bnd`.
- Public API (`org.apache.sling.xss`) is versioned via `@Version` in
`package-info.java`; increment according to OSGi semantic versioning when
changing interfaces.
- 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).
- 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).
@@ -79,7 +89,8 @@ pom.xml
- Framework: JUnit 5 (`junit-jupiter` 5.8.2) + Mockito 4 + Sling Mock
(`sling-mock.junit5`).
- Test files live in `src/test/java/org/apache/sling/xss/impl/`.
-- AntiSamy XML policy fixtures live in `src/test/resources/` (e.g.,
`configWithoutHref.xml`).
+- 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`).
- 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`.
@@ -89,4 +100,5 @@ pom.xml
- `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 `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.
- OSGi baseline comparison runs against the last released artifact. A
binary-incompatible change without a version bump will fail `mvn verify
-Pbaseline`.
diff --git a/README.md b/README.md
index a7b06f0..1c044d4 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ See the JavaDoc of each service for the complete API surface.
- Uses OWASP Java Encoder and a custom 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.
- Excludes legacy/conflicting transitive logging dependencies such as
`commons-logging` and does not depend on Log4j 1.x.
## Build and test
@@ -40,12 +41,18 @@ 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
@@ -54,19 +61,23 @@ mvn verify -Pbaseline
src/
main/
appended-resources/
+ META-INF/
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/
- org/apache/sling/xss/impl/status/
- org/apache/sling/xss/impl/webconsole/
+ org/apache/sling/xss/impl/style/ # CSS validation via Batik
+ org/apache/sling/xss/impl/status/ # Runtime 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/
- resources/
+ 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
```
