Expand the security policy now that private reporting is enabled

README.md

@@ -59,6 +59,11 @@ Please look at the javadoc for Encode to see the variety of contexts for which y
 
 Happy Encoding!
 
+Security
+--------
+Please report suspected vulnerabilities privately. See [SECURITY.md](SECURITY.md) for
+the reporting channels, supported versions, and scope.
+
 Building
 --------
 
@@ -141,6 +146,7 @@ mvn clean deploy -DperformRelease=true
 When changing the version, update the root `pom.xml`, the `<parent>` version in each
 module POM, and `encoder.version` in `jakarta-test/pom.xml`. CI fails if
 `jakarta-test` would test a different `encoder-jakarta-jsp` version than the one being built.
+When publishing a release, also update the supported versions in `SECURITY.md`.
 
 
 News

SECURITY.md

@@ -2,13 +2,61 @@
 
 ## Supported Versions
 
-Only the currently released version of the OWASP Java Encoder is supported.
+Only the latest 1.x release receives security fixes. Fixes ship in a new release;
+older release lines are not patched.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.4.0   | :white_check_mark: |
-| < 1.4.0 | :x:                |
+| Maven coordinate                        | Supported | Not supported |
+| --------------------------------------- | --------- | ------------- |
+| `org.owasp.encoder:encoder`             | 1.4.0     | < 1.4.0       |
+| `org.owasp.encoder:encoder-jsp`         | 1.4.0     | < 1.4.0       |
+| `org.owasp.encoder:encoder-jakarta-jsp` | 1.4.0     | < 1.4.0       |
+| `org.owasp.encoder:encoder-esapi`       | 1.4.0     | < 1.4.0       |
+
+Upgrading the core `encoder` artifact to the latest 1.x release needs no code changes:
+no public API was removed between 1.2.3 and 1.4.0. It does need Java 8 or later;
+1.2.3 and earlier also ran on Java 5 through 7.
 
 ## Reporting a Vulnerability
 
-If you suspect that there is a vulnerability, please report it privately using GitHub's [Security Advisories](https://github.com/OWASP/owasp-java-encoder/security/advisories/new).
+Please report suspected vulnerabilities privately, not in public issues or pull requests.
+
+Use the **Report a vulnerability** button on the repository's
+[Security Advisories](https://github.com/OWASP/owasp-java-encoder/security/advisories)
+page. The form requires a GitHub account. If you cannot use it, email the project
+leaders at jeremy.long@owasp.org and jim@owasp.org.
+
+A useful report includes:
+
+- the affected artifact and version
+- the `Encode` method, tag, or EL function involved
+- the input, the encoded output, and the output you expected
+- where the output was used (for example, an HTML attribute or a JavaScript string)
+  and the browser or parser that interpreted it
+- a minimal reproduction, if you have one
+
+## Scope
+
+In scope:
+
+- input that passes through a documented `Encode.forXxx` method (or the matching tag
+  or EL function), is used in the context that method documents, and is then
+  interpreted as code or markup by a current mainstream parser for that context
+- a crash, or unbounded CPU or memory use, on any input
+- output that contradicts the encoder's documented contract
+
+Out of scope:
+
+- using an encoder in a context it does not document (for example, `forHtml` output
+  placed in a JavaScript string)
+- canonicalization, decoding, or input validation, which this library does not perform
+- vulnerabilities in ESAPI, Spring, or servlet containers; report ESAPI issues through
+  the [ESAPI security policy](https://github.com/ESAPI/esapi-java-legacy/security)
+- the unpublished `jakarta-test` application
+
+## Response
+
+These are goals for a volunteer-run project, not guarantees:
+
+- acknowledge a report within about a week
+- coordinate disclosure with the reporter, publishing a fix and advisory within
+  90 days where possible