From bdc02a45e0cb112b1622be409399a2ef98ba56c6 Mon Sep 17 00:00:00 2001 From: Mario Heiderich Date: Fri, 19 Jun 2026 14:50:37 +0200 Subject: [PATCH] chore: updated README with wiki links --- README.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 67b4c2b..4eaafe3 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,12 @@ XSS. **Ship the policy, and the browser routes every HTML sink through DOMPurify (or any sanitizer you give it) on its way into the DOM.** +New here? The [wiki](https://github.com/cure53/DOMFortify/wiki) has the deeper docs: +[Installation and Usage](https://github.com/cure53/DOMFortify/wiki/Installation-and-Usage), +[How It Works](https://github.com/cure53/DOMFortify/wiki/How-It-Works) with data-flow diagrams, the +[Security Goals and Threat Model](https://github.com/cure53/DOMFortify/wiki/Security-Goals-and-Threat-Model), +and [Risks and Footguns](https://github.com/cure53/DOMFortify/wiki/Risks-and-Footguns). + ## Is there a demo? Of course. [Play with DOMFortify](https://cure53.de/fortify) - throw payloads at a deliberately broken @@ -29,9 +35,11 @@ HTML goes through [DOMPurify](https://github.com/cure53/DOMPurify) (or any sanit sinks like `eval` and `script.src` are refused outright, because there is no safe way to sanitize executable code. -It does two jobs and no more: own the `default` policy, and route sinks. Whether enforcement is even on -is a CSP's job, not the library's - so DOMFortify reports honestly, through `status()`, whether the page -is actually protected. +It does two jobs and no more: own the `default` policy, and route sinks. Whether enforcement is on comes +from a CSP - a response header, a parse-time ``, or DOMFortify's opt-in `INJECT_META` - and either +way DOMFortify reports honestly, through `status()`, whether the page is actually protected. For the full +mental model with data-flow diagrams, see +[How It Works](https://github.com/cure53/DOMFortify/wiki/How-It-Works) in the wiki. ## Quick start (CDN) @@ -248,9 +256,11 @@ passed its smoke test. `reason` explains the current state in one line. Demo: [s ## What it won't do -It's a retrofit, not magic. Know the edges: +It's a retrofit, not magic. Know the edges (the +[Risks and Footguns](https://github.com/cure53/DOMFortify/wiki/Risks-and-Footguns) wiki page goes deeper): -- **It needs the CSP.** No enforcement, no protection - and it'll tell you so via `status()`. +- **Enforcement has to be on.** No enforcement, no protection, and it'll tell you so via `status()`. Turn + it on with a header, a parse-time ``, or `INJECT_META` (next bullet). A header is sturdiest. - **`INJECT_META` is best-effort.** A script-inserted `` CSP is ignored unless the parser inserts it during the initial parse. Don't rely on it where a header or hand-placed `` is an option; check `status()` to see whether enforcement actually took. @@ -269,6 +279,10 @@ It's a retrofit, not magic. Know the edges: ## Security +For what DOMFortify defends, what it assumes, and what stays out of scope, see the +[Security Goals and Threat Model](https://github.com/cure53/DOMFortify/wiki/Security-Goals-and-Threat-Model) +in the wiki. + Found a hole? Please report it privately - see [SECURITY.md](SECURITY.md). Don't open a public issue. ---