Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions THREAT_MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,8 @@ framework, not by the operator. *(documented — `boot/`, `apps/boot-hello/READM
- **Operator** — deploys the WAR, sets `devMode` off, restricts dev-only plugins,
configures the container and JVM. **Trusted.** *(documented.)*
With Boot, the operator still owns the JVM, the host, the network perimeter and the
`struts.boot.*` settings (port, bind address, context path); the container defaults
the starter applies are Struts' (§5).
`struts.boot.*` settings (port, bind address, context path, session cookie
attributes); the container defaults the starter applies are Struts' (§5).

**Component families.**

Expand Down Expand Up @@ -239,7 +239,10 @@ documented anti-pattern is `OUT-OF-MODEL`. *(documented/inferred — §14 Q-defa
- `DefaultServlet` serves only an empty per-run docBase
- Tomcat's base directory is a fresh owner-only temp directory, deleted on shutdown
- session tracking is cookie-only
- the session cookie carries `SameSite=Lax`
- the session cookie carries `SameSite=Lax`, as does any other cookie without a
`SameSite` attribute of its own (override `struts.boot.session.cookie.sameSite`)
- `Secure` is not forced on the session cookie (override
`struts.boot.session.cookie.secure`)
- `devMode` is never switched on

A deviation from these defaults is a Struts finding. Anything the developer adds on
Expand Down
27 changes: 22 additions & 5 deletions apps/boot-hello/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,32 @@ not deployed to Maven repositories; build it from source.

Settings are read from `struts.properties` on the classpath. A `--key=value` argument overrides the file.

| Key | Default | Meaning |
|----------------------------|---------|--------------------------------------------|
| `struts.boot.port` | `8080` | HTTP port; `0` picks a free port |
| `struts.boot.context-path` | `""` | Context path the application is served at |
| `struts.boot.address` | all | Interface to listen on, e.g. `127.0.0.1` |
| Key | Default | Meaning |
|---------------------------------------|---------|------------------------------------------------------------|
| `struts.boot.port` | `8080` | HTTP port; `0` picks a free port |
| `struts.boot.context-path` | `""` | Context path the application is served at |
| `struts.boot.address` | all | Interface to listen on, e.g. `127.0.0.1` |
| `struts.boot.session.cookie.secure` | `false` | `true` marks the session cookie `Secure` |
| `struts.boot.session.cookie.sameSite` | `lax` | `SameSite` attribute: `lax`, `strict`, `none` or `unset` |

The values of the two session cookie settings ignore case and surrounding spaces. Any other value, an empty one
included, stops the application at startup with an error that names the setting and the value. Keys are matched exactly:
a key that is not in this table, `struts.boot.session.cookie.samesite` for example, is ignored, and so is an argument
without `=`.

## Defaults worth knowing

- Tomcat listens on all interfaces, not only on localhost; set `struts.boot.address` to restrict it.
- Sessions are tracked by cookie only. The session cookie carries `SameSite=Lax`, and `Secure` is not forced on it:
over the plain HTTP listener the starter opens, it is sent without `Secure`. Set
`struts.boot.session.cookie.secure=true` when TLS ends in front of the application, at a reverse proxy for example.
- `struts.boot.session.cookie.sameSite` sets the default of Tomcat's cookie processor, so it also applies to every
other cookie the application adds without a `SameSite` attribute of its own. With `unset` the processor adds no
`SameSite` attribute; one the application sets on a cookie itself is kept.
- For `SameSite=None`, the cookie reaching the browser must also carry `Secure`. Set
`struts.boot.session.cookie.secure=true` in Boot, or configure your HTTPS reverse proxy to add the `Secure`
attribute. The starter does not check this combination. The `secure` setting only reaches the session cookie; a
cookie the application adds itself needs its own `Secure`.
- Error pages show the status only, without stack traces or the Tomcat version.
- `struts.devMode` stays off.
- Each start uses a fresh temporary base directory (`struts-boot-<uuid>`) that is deleted on shutdown.
Expand Down
49 changes: 47 additions & 2 deletions boot/src/main/java/org/apache/struts2/boot/BootSettings.java
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@

import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.Locale;
import java.util.Optional;
import java.util.Properties;

Expand All @@ -31,16 +33,23 @@ public final class BootSettings {
private static final String PORT_KEY = PREFIX + "port";
private static final String CONTEXT_PATH_KEY = PREFIX + "context-path";
private static final String ADDRESS_KEY = PREFIX + "address";
private static final String SESSION_COOKIE_SECURE_KEY = PREFIX + "session.cookie.secure";
private static final String SESSION_COOKIE_SAME_SITE_KEY = PREFIX + "session.cookie.sameSite";
private static final List<String> SAME_SITE_VALUES = List.of("lax", "strict", "none", "unset");
private static final String ARGUMENT_PREFIX = "--";

private final int port;
private final String contextPath;
private final String address;
private final boolean sessionCookieSecure;
private final String sessionCookieSameSite;

private BootSettings(int port, String contextPath, String address) {
private BootSettings(int port, String contextPath, String address, boolean sessionCookieSecure, String sessionCookieSameSite) {
this.port = port;
this.contextPath = contextPath;
this.address = address;
this.sessionCookieSecure = sessionCookieSecure;
this.sessionCookieSameSite = sessionCookieSameSite;
}

public static BootSettings load(String[] args) {
Expand All @@ -56,7 +65,9 @@ public static BootSettings load(Properties fileProperties, String[] args) {
return new BootSettings(
parsePort(merged.getProperty(PORT_KEY, "8080")),
normaliseContextPath(merged.getProperty(CONTEXT_PATH_KEY, "")),
blankToNull(merged.getProperty(ADDRESS_KEY)));
blankToNull(merged.getProperty(ADDRESS_KEY)),
parseSecure(merged.getProperty(SESSION_COOKIE_SECURE_KEY, "false")),
parseSameSite(merged.getProperty(SESSION_COOKIE_SAME_SITE_KEY, "lax")));
}

public int port() {
Expand All @@ -71,6 +82,20 @@ public Optional<String> address() {
return Optional.ofNullable(address);
}

/** Whether {@code Secure} is forced on the session cookie; {@code false} unless configured. */
public boolean sessionCookieSecure() {
return sessionCookieSecure;
}

/**
* The {@code SameSite} value, in lower case, the container adds to the session cookie and to any
* other cookie without a {@code SameSite} attribute of its own: {@code lax} (the default),
* {@code strict}, {@code none}, or {@code unset} to add none.
*/
public String sessionCookieSameSite() {
return sessionCookieSameSite;
}

private static void applyArgument(Properties target, String arg) {
if (!arg.startsWith(ARGUMENT_PREFIX + PREFIX)) {
return;
Expand Down Expand Up @@ -105,6 +130,26 @@ private static int parsePort(String value) {
}
}

private static boolean parseSecure(String value) {
String normalised = value.trim().toLowerCase(Locale.ROOT);
if (normalised.equals("true")) {
return true;
}
if (normalised.equals("false")) {
return false;
}
throw new ConfigurationException("Invalid " + SESSION_COOKIE_SECURE_KEY + ": '" + value + "' is not true or false");
}

private static String parseSameSite(String value) {
String normalised = value.trim().toLowerCase(Locale.ROOT);
if (!SAME_SITE_VALUES.contains(normalised)) {
throw new ConfigurationException("Invalid " + SESSION_COOKIE_SAME_SITE_KEY + ": '" + value
+ "' is not one of " + String.join(", ", SAME_SITE_VALUES));
}
return normalised;
}

private static Properties readStrutsProperties() {
Properties properties = new Properties();
try (InputStream in = Thread.currentThread().getContextClassLoader().getResourceAsStream("struts.properties")) {
Expand Down
18 changes: 12 additions & 6 deletions boot/src/main/java/org/apache/struts2/boot/StrutsBootServer.java
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ static StrutsBootServer start(ActionRegistry registry, BootSettings settings) {
hideErrorReportDetails(tomcat);
Path docBase = Files.createDirectory(baseDir.resolve("webapp"));
Context context = tomcat.addContext(settings.contextPath(), docBase.toString());
restrictSessionTracking(context);
restrictSessionTracking(context, settings);
context.addServletContainerInitializer(
(classes, servletContext) -> servletContext.setAttribute(ActionRegistry.SERVLET_CONTEXT_ATTRIBUTE, registry),
null);
Expand Down Expand Up @@ -182,16 +182,22 @@ private static void assertContextStarted(Context context, CapturingStrutsFilter
}

/**
* Restricts the embedded context to cookie-only session tracking with {@code SameSite=Lax};
* Secure is left to the operator's TLS setup.
* Restricts the embedded context to cookie-only session tracking and applies the session cookie
* settings: {@code SameSite=Lax} and no forced {@code Secure} unless configured otherwise, see
* {@link BootSettings#sessionCookieSameSite()} and {@link BootSettings#sessionCookieSecure()}.
* {@code SameSite} is set on the cookie processor, as before, so it stays the default for every
* cookie of the context that has no {@code SameSite} attribute of its own.
*/
private static void restrictSessionTracking(Context context) {
private static void restrictSessionTracking(Context context, BootSettings settings) {
// Tomcat defaults to COOKIE+URL when no web.xml sets <tracking-mode>; keep cookies only.
context.addServletContainerInitializer(
(classes, servletContext) -> servletContext.setSessionTrackingModes(EnumSet.of(SessionTrackingMode.COOKIE)),
(classes, servletContext) -> {
servletContext.setSessionTrackingModes(EnumSet.of(SessionTrackingMode.COOKIE));
servletContext.getSessionCookieConfig().setSecure(settings.sessionCookieSecure());
},
null);
Rfc6265CookieProcessor cookieProcessor = new Rfc6265CookieProcessor();
cookieProcessor.setSameSiteCookies("lax");
cookieProcessor.setSameSiteCookies(settings.sessionCookieSameSite());
context.setCookieProcessor(cookieProcessor);
}

Expand Down
114 changes: 114 additions & 0 deletions boot/src/test/java/org/apache/struts2/boot/BootSettingsTest.java
Original file line number Diff line number Diff line change
Expand Up @@ -119,4 +119,118 @@ public void testNonNumericPortThrows() {
assertThatThrownBy(() -> BootSettings.load(fileProperties, args))
.isInstanceOf(ConfigurationException.class);
}

@Test
public void testSessionCookieDefaults() {
BootSettings settings = BootSettings.load(new Properties(), new String[0]);

assertThat(settings.sessionCookieSecure()).isFalse();
assertThat(settings.sessionCookieSameSite()).isEqualTo("lax");
}

@Test
public void testSessionCookieSecureFromFile() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.secure", "true");

assertThat(BootSettings.load(file, new String[0]).sessionCookieSecure()).isTrue();
}

@Test
public void testSessionCookieSecureArgumentBeatsFile() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.secure", "true");

BootSettings settings = BootSettings.load(file, new String[]{"--struts.boot.session.cookie.secure=false"});

assertThat(settings.sessionCookieSecure()).isFalse();
}

@Test
public void testSessionCookieSecureIgnoresCaseAndSpaces() {
assertThat(sessionCookieSecure(" TRUE ")).isTrue();
assertThat(sessionCookieSecure("False")).isFalse();
}

@Test
public void testSessionCookieSameSiteValues() {
assertThat(sessionCookieSameSite("lax")).isEqualTo("lax");
assertThat(sessionCookieSameSite("strict")).isEqualTo("strict");
assertThat(sessionCookieSameSite("none")).isEqualTo("none");
assertThat(sessionCookieSameSite("unset")).isEqualTo("unset");
assertThat(sessionCookieSameSite(" Strict ")).isEqualTo("strict");
assertThat(sessionCookieSameSite("NONE")).isEqualTo("none");
}

@Test
public void testSessionCookieSameSiteFromFile() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.sameSite", "unset");

assertThat(BootSettings.load(file, new String[0]).sessionCookieSameSite()).isEqualTo("unset");
}

@Test
public void testSessionCookieSameSiteArgumentBeatsFile() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.sameSite", "strict");

BootSettings settings = BootSettings.load(file, new String[]{"--struts.boot.session.cookie.sameSite=none"});

assertThat(settings.sessionCookieSameSite()).isEqualTo("none");
}

private static boolean sessionCookieSecure(String value) {
return BootSettings.load(new Properties(), new String[]{"--struts.boot.session.cookie.secure=" + value})
.sessionCookieSecure();
}

private static String sessionCookieSameSite(String value) {
return BootSettings.load(new Properties(), new String[]{"--struts.boot.session.cookie.sameSite=" + value})
.sessionCookieSameSite();
}

@Test
public void testInvalidSessionCookieSecureThrows() {
for (String value : new String[]{"yes", "1", "", " "}) {
String[] args = {"--struts.boot.session.cookie.secure=" + value};
assertThatThrownBy(() -> BootSettings.load(new Properties(), args))
.isInstanceOf(ConfigurationException.class)
.hasMessageContaining("struts.boot.session.cookie.secure")
.hasMessageContaining("'" + value + "'");
}
}

@Test
public void testInvalidSessionCookieSameSiteThrows() {
for (String value : new String[]{"bogus", "true", "", " "}) {
String[] args = {"--struts.boot.session.cookie.sameSite=" + value};
assertThatThrownBy(() -> BootSettings.load(new Properties(), args))
.isInstanceOf(ConfigurationException.class)
.hasMessageContaining("struts.boot.session.cookie.sameSite")
.hasMessageContaining("'" + value + "'");
}
}

@Test
public void testInvalidSessionCookieSecureFromFileThrows() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.secure", "on");

assertThatThrownBy(() -> BootSettings.load(file, new String[0]))
.isInstanceOf(ConfigurationException.class)
.hasMessageContaining("struts.boot.session.cookie.secure")
.hasMessageContaining("'on'");
}

@Test
public void testInvalidSessionCookieSameSiteFromFileThrows() {
Properties file = new Properties();
file.setProperty("struts.boot.session.cookie.sameSite", "relaxed");

assertThatThrownBy(() -> BootSettings.load(file, new String[0]))
.isInstanceOf(ConfigurationException.class)
.hasMessageContaining("struts.boot.session.cookie.sameSite")
.hasMessageContaining("'relaxed'");
}
}
Loading