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-security.git
The following commit(s) were added to refs/heads/master by this push:
new c9274ed docs: improve AGENTS.md and README.md with filter details and
commands (#14)
c9274ed is described below
commit c9274edb80d4e1748d2afed7a9b8a309f117d035
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 15:05:03 2026 +0200
docs: improve AGENTS.md and README.md with filter details and commands (#14)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 11 ++++++++---
README.md | 8 ++++++--
2 files changed, 14 insertions(+), 5 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 0c764a1..7d43136 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,16 @@
# Project Overview
-Apache Sling Security is an OSGi bundle for Apache Sling that provides two
servlet filters: `ReferrerFilter` (a `Preprocessor` that blocks requests with
missing or untrusted `Referer` headers to prevent CSRF) and
`ContentDispositionFilter` (a Sling request/forward filter that forces
`Content-Disposition: attachment` on responses for configured paths/content
types). Components use OSGi R6/R7 declarative services annotations
(`org.osgi.service.component.annotations`) with metatype configur [...]
+Apache Sling Security is an OSGi bundle for Apache Sling that provides two
servlet filters: `ReferrerFilter` (an OSGi HTTP Whiteboard `Preprocessor` that
blocks requests with missing or untrusted `Referer`/`Origin` headers to prevent
CSRF) and `ContentDispositionFilter` (a Sling request/forward filter that
forces `Content-Disposition: attachment` on responses for configured
paths/content types). Components use OSGi R6/R7 declarative services
annotations (`org.osgi.service.component.annot [...]
+
+This bundle can run outside Apache Sling; in that setup only `ReferrerFilter`
is applicable because `ContentDispositionFilter` depends on Sling API/resource
model types.
# Core Commands
- **Build:** `mvn clean install`
- **Build (skip tests):** `mvn clean install -DskipTests`
- **Run full test suite:** `mvn test`
-- **Run a single test class:** `mvn test -Dtest=ReferrerFilterTest`
+- **Run ReferrerFilter tests:** `mvn test -Dtest=ReferrerFilterTest`
+- **Run ContentDispositionFilter tests:** `mvn test
-Dtest=ContentDispositionFilterTest`
- **Run a single test method:** `mvn test
-Dtest=ReferrerFilterTest#testMethodName`
- **Lint / format check (Spotless via parent POM):** `mvn spotless:check`
- **Apply formatting:** `mvn spotless:apply`
@@ -40,6 +43,7 @@ All production code lives under
`org.apache.sling.security.impl`. There are no p
# Development Patterns & Constraints
- **Java version:** 11 (source and target)
+- **Parent POM:** `org.apache.sling:sling-bundle-parent:66` controls shared
plugin/version management.
- **OSGi components:** Use `org.osgi.service.component.annotations`
(`@Component`, `@Reference`, `@Activate`). Do NOT use Felix SCR annotations.
- **Metatype config:** Define configuration interfaces with
`@ObjectClassDefinition` / `@AttributeDefinition` in the same file as or
alongside the component.
- **Indentation:** 4 spaces (no tabs). Follow existing code style.
@@ -71,8 +75,10 @@ All production code lives under
`org.apache.sling.security.impl`. There are no p
# Gotchas
- `ReferrerFilter` is registered as an OSGi `Preprocessor` (HTTP Whiteboard),
not a standard Sling filter — it runs before Sling servlet resolution.
+- `ReferrerFilter` validates `referer` and falls back to `origin` when
`referer` is missing.
- The `bnd.bnd` sets `Require-Capability` for `osgi.http` version 1.x;
updating the HTTP Whiteboard spec version requires updating this too.
- `org.apache.sling.*` imports are marked `resolution:=optional` so the bundle
can load even when Sling API is absent — keep this in mind when adding Sling
API usage.
+- `ContentDispositionFilter` only adds the header for resources containing
`jcr:data` directly or under `jcr:content/jcr:data`.
- OSGi metatype XML descriptors are generated at compile time by annotation
processing into `target/classes/OSGI-INF/`. Never edit them manually.
- The parent POM (`sling-bundle-parent`) controls Spotless, RAT, baseline, and
other plugin versions. Do not override plugin versions locally unless necessary.
- `junit-addons:1.4` is a transitive test dependency with old Xerces — it is
pulled in by JMock; avoid adding more dependencies on it.
@@ -82,4 +88,3 @@ All production code lives under
`org.apache.sling.security.impl`. There are no p
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index de8e32d..a8a409f 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,9 @@ The project inherits build plugins and checks from Sling
parent POM `66`.
- Build: `mvn clean install`
- Build without tests: `mvn clean install -DskipTests`
- Run tests: `mvn test`
+- Run ReferrerFilter tests: `mvn test -Dtest=ReferrerFilterTest`
+- Run ContentDispositionFilter tests: `mvn test
-Dtest=ContentDispositionFilterTest`
+- Run a single test method: `mvn test -Dtest=ReferrerFilterTest#testMethodName`
- Run Spotless check: `mvn spotless:check`
- Apply Spotless formatting: `mvn spotless:apply`
- Run RAT license checks: `mvn rat:check`
@@ -34,6 +37,7 @@ The project inherits build plugins and checks from Sling
parent POM `66`.
The Referrer Filter is registered as an OSGi HTTP Whiteboard `Preprocessor`
and checks browser-originated modification requests.
It validates the `referer` header and falls back to `origin` when `referer` is
not present.
+The filter is applied to configured modification methods and supports path and
user-agent based exclusions.
Configuration PID: `org.apache.sling.security.impl.ReferrerFilter`
@@ -76,9 +80,9 @@ It is also possible to amend this configuration with factory
configurations for:
## Content Disposition Filter
-The Content Disposition Filter is a Sling request/forward filter that adds
`Content-Disposition: attachment` for configured resource paths on `GET` and
`HEAD` requests. It supports explicit path includes, prefix includes (`*`
suffix), exclusions, and optional all-path mode.
+The Content Disposition Filter is a Sling request/forward filter that adds
`Content-Disposition: attachment` for configured resource paths on `GET` and
`HEAD` requests. It supports exact path includes, prefix includes (`*` suffix),
exclusions, and optional all-path mode.
-The header is only added for resources that contain `jcr:data` directly or
below `jcr:content/jcr:data`.
+The header is only added for resources that contain `jcr:data` directly or
below `jcr:content/jcr:data`. Per-path content type lists are interpreted as
excluded content types for that path.
Configuration PID: `org.apache.sling.security.impl.ContentDispositionFilter`
