This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/commons-xml.git
The following commit(s) were added to refs/heads/main by this push:
new 9b70ab8 Normalize documentation headers.
9b70ab8 is described below
commit 9b70ab81482b3c06956160f619e5d8f01478a67b
Author: Gary Gregory <[email protected]>
AuthorDate: Fri Aug 28 17:02:29 2026 -0400
Normalize documentation headers.
---
src/site/markdown/index.md | 26 +++++++++++++-------------
src/site/markdown/threat_model.md | 22 +++++++++++-----------
2 files changed, 24 insertions(+), 24 deletions(-)
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index d898710..6f89c87 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -64,7 +64,7 @@ it resolves to empty content,
so the parse continues without it
(see Configuration below).
-### Supported runtimes
+### Supported Runtimes
The library requires OpenJDK 8 or later (or a JDK distribution built from it),
or Android API level 26 or later.
@@ -76,14 +76,14 @@ so the library secures the platform's parsers as
best-effort.
Android's `XmlPullParser` API is not supported:
it is not a JAXP API.
-### Supported implementations
+### Supported Implementations
Out of the box the library recognizes the stock JDK JAXP implementations,
Apache Xerces 2.x, Woodstox, and Saxon-HE. If
a factory resolves to an implementation not covered by any bundled hardening
recipe, every `org.apache.commons.xml` factory method throws
`IllegalStateException` with a message naming the unsupported class. Adding
support for a new JAXP implementation
requires a code change to this library.
-**DOM parsing** via `DocumentBuilderFactory`:
+**DOM Parsing** via `DocumentBuilderFactory`:
```java
import org.w3c.dom.Document;
@@ -92,7 +92,7 @@ import org.apache.commons.xml.SecureDocumentBuilderFactory;
Document doc =
HardeningDocumentBuilderFactory.newInstance().newDocumentBuilder().parse(inputStream);
```
-**SAX parsing** via `SAXParserFactory`:
+**SAX Parsing** via `SAXParserFactory`:
```java
import org.apache.commons.xml.SecureSAXParserFactory;
@@ -100,7 +100,7 @@ import org.apache.commons.xml.SecureSAXParserFactory;
HardeningSAXParserFactory.newInstance().newSAXParser().parse(inputStream,
myDefaultHandler);
```
-**Streaming (StAX) parsing** via `XMLInputFactory`:
+**Streaming (StAX) Parsing** via `XMLInputFactory`:
```java
import javax.xml.stream.XMLStreamReader;
@@ -109,7 +109,7 @@ import org.apache.commons.xml.SecureXMLInputFactory;
XMLStreamReader reader =
HardeningXMLInputFactory.newInstance().createXMLStreamReader(inputStream);
```
-**XSLT transforms** via `TransformerFactory`:
+**XSLT Transforms** via `TransformerFactory`:
```java
import javax.xml.transform.stream.StreamSource;
@@ -121,7 +121,7 @@ HardeningTransformerFactory.newInstance()
.transform(new StreamSource(inputStream), new
StreamResult(outputStream));
```
-**XPath queries** via `XPathFactory`:
+**XPath Queries** via `XPathFactory`:
```java
import javax.xml.xpath.XPathConstants;
@@ -133,7 +133,7 @@ NodeList hits = (NodeList)
HardeningXPathFactory.newInstance()
.evaluate("//item", doc, XPathConstants.NODESET);
```
-**W3C XML Schema validation** via `SchemaFactory`:
+**W3C XML Schema Validation** via `SchemaFactory`:
```java
import javax.xml.XMLConstants;
@@ -146,7 +146,7 @@
HardeningSchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI)
.validate(new StreamSource(inputStream));
```
-### Wrappers, not the original factories
+### Wrappers, not the Original Factories
A returned factory is not necessarily an instance of the underlying
implementation.
It might be (and usually is) a wrapper around it,
@@ -167,7 +167,7 @@ and the library respects it:
Whichever parser is selected, it is hardened.
-### Factory methods
+### Factory Methods
Each factory class mirrors every static factory method its JAXP counterpart
offers,
so a hardened factory is a drop-in replacement at any construction site:
@@ -190,7 +190,7 @@ That suits a library with minimal XML requirements,
which can parse with the well-known platform parser
rather than delegate the choice of implementation to the application developer.
-### Stylesheets and schemas
+### Stylesheets and Schemas
The hardening applies to documents parsed through the returned factory.
Stylesheets given to
`TransformerFactory.newTransformer(Source)` and schemas given to
`SchemaFactory.newSchema(Source)` are read by a parser
@@ -202,7 +202,7 @@ the hardening governs reads only,
so restrict output destinations yourself when running an untrusted stylesheet
(see the [Threat Model](threat_model.html)).
-### Transformer handlers and filters
+### Transformer Handlers and Filters
The `SAXTransformerFactory` extension methods, `newTransformerHandler(...)`,
`newTemplatesHandler()` and `newXMLFilter(...)`,
if reachable by casting the factory from
`HardeningTransformerFactory.newInstance()`,
@@ -213,7 +213,7 @@ The SAX events you feed into a handler, and a parent reader
you set on a filter,
are your own configuration, like any caller-supplied parser.
See the [Threat Model](threat_model.html) for the exact scope.
-### Caching and thread-safety
+### Caching and Thread-Safety
There is no caching or pooling inside `org.apache.commons.xml`; callers on a
hot path are responsible for their own caching. The
returned factories inherit the thread-safety properties of the underlying JAXP
implementation, which in practice means
diff --git a/src/site/markdown/threat_model.md
b/src/site/markdown/threat_model.md
index a562ab3..7062c08 100644
--- a/src/site/markdown/threat_model.md
+++ b/src/site/markdown/threat_model.md
@@ -38,7 +38,7 @@ It is versioned with the library: a report against a released
version is triaged
A finding that breaks something listed under [What is in
scope](#what-is-in-scope) should be reported through the channel above;
a finding that falls under [What is out of scope](#what-is-out-of-scope) will
be closed citing this section.
-### Scope and intended use
+### Scope and Intended Use
This library is a helper for **safely creating JAXP factories**. Each
`XxxFactory.newYyy()` method returns a
new, hardened factory whose parsers reject the common XML attacks (external
entity / DTD resolution, XXE, SSRF through
@@ -52,7 +52,7 @@ It governs what those objects read;
what a transform writes is the stylesheet author's capability
(see **Transform output destinations** under [What is out of
scope](#what-is-out-of-scope)).
-### Adversary model and trust boundary
+### Adversary Model and Trust Boundary
The adversary is whoever controls the XML an application parses, together with
any external system an XML
document tries to reach through an entity, DTD, schema, stylesheet, or
XInclude reference. The hardening
@@ -75,7 +75,7 @@ The library hardens what it creates;
it does not re-harden what you built,
because your reader's settings are indistinguishable from configuration you
chose deliberately.
-### What is in scope
+### What is in Scope
- The hardening recipes applied by `org.apache.commons.xml`.
Every implementation of JAXP 1.4 or later is in scope,
@@ -89,7 +89,7 @@ because your reader's settings are indistinguishable from
configuration you chos
provides. The guarantee covers the documented entry points of each returned
factory type,
including the `SAXTransformerFactory` extension methods when the returned
`TransformerFactory` exposes them.
-### Assumptions about the environment
+### Assumptions about the Environment
The library does not open network connections,
spawn processes,
@@ -141,7 +141,7 @@ On the supported runtimes (see **Supported runtimes**
above),
every one of these defaults still bounds entity expansion tightly enough to
reject entity-expansion denial of service
such as Billion Laughs.
-**Reserved settings (must not be loosened)**
+**Reserved Settings (must not be loosened)**
The library MAY rely on the following features, attributes and properties
staying as configured. They are reserved because
they govern external resource access, DTD, entity or schema handling, the
installation of a resolver, or processing
@@ -175,7 +175,7 @@ is reserved on the same terms.
Installing a resolver through the typed `set*Resolver` methods, the
`DefaultHandler` passed to `SAXParser.parse`, or the resolver properties listed
under **Settings you may modify** does not loosen the hardening:
those paths are wrapped by a non-removable floor.
-**Settings you may modify**
+**Settings You May Modify**
The following are security-relevant but safe to change on a returned factory:
the protection they appear to govern is
enforced by the reserved settings above, which a caller cannot lift.
@@ -225,7 +225,7 @@ enforced by the reserved settings above, which a caller
cannot lift.
Whichever parser is selected, it is hardened,
so the setting carries no security weight.
-### What is out of scope
+### What is Out of Scope
A returned factory is hardened as delivered; reconfiguring it is a decision to
take over hardening for that instance,
and reports against a factory reconfigured in any of the ways below are out of
scope.
@@ -266,12 +266,12 @@ and reports against a factory reconfigured in any of the
ways below are out of s
(an output resolver of the implementation, filesystem permissions, or
process sandboxing).
A path-traversal or file-write report through a stylesheet's output
instructions is out of scope.
-### Downstream responsibility
+### Downstream Responsibility
Use the factory as returned. If you reconfigure it, you take over hardening
for that instance and are responsible for
re-establishing any protection you remove.
-### Known non-findings
+### Known Non-Findings
XML-security scanners and static analyzers routinely flag the parsers this
library produces. The following
are **not** vulnerabilities under this model:
@@ -304,7 +304,7 @@ are **not** vulnerabilities under this model:
- Reports in a JAXP implementation that does not respect the contract of the
settings a hardening recipe
requires: `org.apache.commons.xml` factory method throws rather than
returning an unhardened factory, so there is no instance to attack.
-### Triage dispositions
+### Triage Dispositions
A report judged against this model receives exactly one of:
@@ -317,7 +317,7 @@ A report judged against this model receives exactly one of:
| `OUT-OF-SCOPE: unsupported runtime` | The behavior is demonstrated only on a
runtime the guarantees are not defined on, such as Android on any API level
(see **Supported runtimes** under [Assumptions about the
environment](#assumptions-about-the-environment)). |
| `MODEL-GAP` | The report fits none of the above. The model is then
incomplete: revise it rather than making an ad-hoc call. |
-### Conditions that would change this model
+### Conditions That Would Change This Model
Revise this model when any of the following change:
a new `org.apache.commons.xml` factory or other public surface;
