aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-10-30 08:35:46 +0100
committerDennis Fink2026-10-30 08:41:42 +0100
commit4485aeb573ceb37237ea1fbc80665ed6c4136116 (patch)
treebce18a2c7fadd657d9f9809ebbc65d06c6cc4dc4
parent9f093cf07a3531ee4b7d02c20151e21c141a93de (diff)
downloadwebmentions-ssg-4485aeb573ceb37237ea1fbc80665ed6c4136116.tar.gz
webmentions-ssg-4485aeb573ceb37237ea1fbc80665ed6c4136116.zip
fix(core): harden application configuration
Fail production startup when required configuration is missing, normalize allowed hostnames before validation, and move shared request limits into the default configuration so production does not depend on testing-only values. Set secure session cookie defaults while preserving explicit overrides and document the new rate-limit and notification settings in the example config.
-rw-r--r--contrib/webmentions-ssg.example.cfg37
-rw-r--r--tests/test_config.py45
-rw-r--r--tests/test_configuration_hardening.py119
-rw-r--r--webmentions_ssg/__init__.py16
-rw-r--r--webmentions_ssg/config.py31
-rw-r--r--webmentions_ssg/forms/validators.py3
6 files changed, 228 insertions, 23 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg
index d92726e..d214312 100644
--- a/contrib/webmentions-ssg.example.cfg
+++ b/contrib/webmentions-ssg.example.cfg
@@ -15,27 +15,13 @@ BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"
# ---------------------------------------------------------------------------
-# Flask / Security
+# Flask / Security
# ---------------------------------------------------------------------------
-# Generate a persistent random key, e.g.:
+# Generate a persistent random key, e.g.:
# python -c 'import secrets; print(secrets.token_urlsafe(32))'
# Never commit your real key or SMTP password to version control.
SECRET_KEY = "REPLACE_WITH_A_LONG_RANDOM_SECRET"
-# Only transmit session cookies over HTTPS connections.
-# Recommended for production deployments using HTTPS.
-# Set to False only when developing locally over plain HTTP.
-SESSION_COOKIE_SECURE = True
-
-# Prevent JavaScript from accessing session cookies via document.cookie.
-# Helps protect session cookies from theft through XSS attacks.
-SESSION_COOKIE_HTTPONLY = True
-
-# Restrict session cookies to same-site requests to help mitigate CSRF.
-# "Lax" allows normal navigation from external sites while restricting
-# cookies on most cross-site requests.
-SESSION_COOKIE_SAMESITE = "Lax"
-
# ---------------------------------------------------------------------------
# Database and logging
# ---------------------------------------------------------------------------
@@ -64,6 +50,23 @@ MAX_REDIRECTS = 20 # also used for outgoing requests
MAX_SOURCE_BYTES = 1_000_000
# ---------------------------------------------------------------------------
+# Rate limiting
+# ---------------------------------------------------------------------------
+# In-memory storage is for development/testing ONLY. Production requires shared
+# storage, such as Redis, or the application will refuse to start.
+RATELIMIT_STORAGE_URI = "memory://"
+RATELIMIT_HEADERS_ENABLED = True
+
+# Limits per client and across all clients for incoming Webmention submissions.
+ENDPOINT_RATE_LIMIT = "10/minute;100/hour"
+ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour"
+# Minimum seconds between verifications of the same source/target pair.
+ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600
+
+# Limit login POST attempts per client.
+LOGIN_RATE_LIMIT = "5/minute;30/hour"
+
+# ---------------------------------------------------------------------------
# Sending Webmentions from a statically generated site
# ---------------------------------------------------------------------------
# Folder containing generated pages named index.html. Set to None to disable
@@ -92,6 +95,8 @@ HUEY_URL = "redis://127.0.0.1:6379/0"
# ---------------------------------------------------------------------------
# Set NOTIFICATION_EMAIL = None to disable notification emails.
NOTIFICATION_EMAIL = "admin@example.com"
+# Daily notification digest at 08:00 UTC (Huey defaults to UTC).
+NOTIFICATION_SCHEDULE = "0 8 * * *"
# Example SMTP-over-STARTTLS setup; adapt to your mail provider.
MAIL_SERVER = "smtp.example.com"
diff --git a/tests/test_config.py b/tests/test_config.py
new file mode 100644
index 0000000..8d5aa5b
--- /dev/null
+++ b/tests/test_config.py
@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Test built-in session cookie defaults and explicit overrides."""
+
+import pytest
+
+from webmentions_ssg import create_app
+from webmentions_ssg.config import (
+ DefaultConfig,
+ DevelopmentConfig,
+ ProductionConfig,
+ TestingConfig,
+)
+
+
+@pytest.mark.parametrize(
+ ("config_class", "expected_secure"),
+ [
+ (DefaultConfig, True),
+ (ProductionConfig, True),
+ (DevelopmentConfig, False),
+ (TestingConfig, False),
+ ],
+)
+def test_session_cookie_defaults(
+ config_class: type[DefaultConfig], expected_secure: bool
+) -> None:
+ assert config_class.SESSION_COOKIE_SECURE is expected_secure
+ assert config_class.SESSION_COOKIE_HTTPONLY is True
+ assert config_class.SESSION_COOKIE_SAMESITE == "Lax"
+
+
+def test_explicit_config_overrides_session_cookie_defaults() -> None:
+ class CookieOverrideConfig(TestingConfig):
+ SESSION_COOKIE_SECURE = True
+ SESSION_COOKIE_HTTPONLY = False
+ SESSION_COOKIE_SAMESITE = "Strict"
+
+ app = create_app(CookieOverrideConfig)
+
+ assert app.config["SESSION_COOKIE_SECURE"] is True
+ assert app.config["SESSION_COOKIE_HTTPONLY"] is False
+ assert app.config["SESSION_COOKIE_SAMESITE"] == "Strict"
diff --git a/tests/test_configuration_hardening.py b/tests/test_configuration_hardening.py
new file mode 100644
index 0000000..753f4ca
--- /dev/null
+++ b/tests/test_configuration_hardening.py
@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Regression tests for configuration loading and endpoint hostname policy."""
+
+from pathlib import Path
+
+import pytest
+from wtforms import Field, ValidationError
+from wtforms.form import BaseForm
+
+from webmentions_ssg import create_app
+from webmentions_ssg.config import (
+ DefaultConfig,
+ DevelopmentConfig,
+ ProductionConfig,
+ TestingConfig,
+)
+from webmentions_ssg.forms.validators import AllowedHostname
+
+
+def test_missing_production_configuration_is_fatal(tmp_path: Path) -> None:
+ class MissingProductionConfig(ProductionConfig):
+ CONFIG_FILE = str(tmp_path / "missing.cfg")
+
+ with pytest.raises(FileNotFoundError, match="missing.cfg"):
+ create_app(MissingProductionConfig)
+
+
+def test_missing_development_configuration_is_optional(tmp_path: Path) -> None:
+ class LocalDevelopmentConfig(DevelopmentConfig):
+ CONFIG_FILE = str(tmp_path / "missing.cfg")
+ LOG_FILE = str(tmp_path / "development.log")
+
+ app = create_app(LocalDevelopmentConfig)
+ assert app.config["ALLOWED_HOSTNAMES"] == set()
+
+
+def test_endpoint_limits_are_inherited_from_defaults() -> None:
+ for config in (DefaultConfig, DevelopmentConfig, ProductionConfig, TestingConfig):
+ assert config.MAX_REDIRECTS == 20
+ assert config.MAX_SOURCE_BYTES == 1_000_000
+ assert config.REQUEST_TIMEOUT == 5.0
+
+ assert DefaultConfig.ALLOWED_HOSTNAMES == set()
+
+
+def test_allowed_hostnames_are_normalized_at_startup(tmp_path: Path) -> None:
+ class MixedCaseConfig(TestingConfig):
+ LOG_FILE = str(tmp_path / "test.log")
+ ALLOWED_HOSTNAMES = [" DennisFink.Me ", "EXAMPLE.COM", "dennisfink.me"]
+
+ app = create_app(MixedCaseConfig)
+ assert app.config["ALLOWED_HOSTNAMES"] == {"dennisfink.me", "example.com"}
+ assert isinstance(app.config["ALLOWED_HOSTNAMES"], set)
+
+ # The form validator must compare complete hostnames, never substrings.
+ target = Field()
+ validator = AllowedHostname(message="Hostname not allowed")
+ form = BaseForm({})
+ with app.app_context():
+ for url in ("https://dennisfink.me/post", "https://EXAMPLE.com/post"):
+ target.data = url
+ validator(form, target)
+
+ for url in ("https://fink/post", "https://evil-dennisfink.me/post"):
+ target.data = url
+ with pytest.raises(ValidationError, match="Hostname not allowed"):
+ validator(form, target)
+
+
+@pytest.mark.parametrize(
+ "hostnames,expected_exception",
+ [
+ ("dennisfink.me", TypeError),
+ (None, TypeError),
+ ({"dennisfink.me": True}, TypeError),
+ (123, TypeError),
+ (["example.com", None], ValueError),
+ (["example.com", ""], ValueError),
+ (["example.com", " "], ValueError),
+ ],
+)
+def test_invalid_allowed_hostnames_fail_at_startup(
+ tmp_path: Path, hostnames: object, expected_exception: type[Exception]
+) -> None:
+ class InvalidHostnameConfig(TestingConfig):
+ LOG_FILE = str(tmp_path / "test.log")
+ ALLOWED_HOSTNAMES = hostnames
+
+ with pytest.raises(expected_exception, match="ALLOWED_HOSTNAMES"):
+ create_app(InvalidHostnameConfig)
+
+
+def test_production_requires_nonempty_allowed_hostnames(tmp_path: Path) -> None:
+ config_path = tmp_path / "production.cfg"
+ config_path.write_text('RATELIMIT_STORAGE_URI = "redis://localhost:6379"\n')
+
+ class EmptyHostnamesConfig(ProductionConfig):
+ CONFIG_FILE = str(config_path)
+
+ with pytest.raises(RuntimeError, match="ALLOWED_HOSTNAMES"):
+ create_app(EmptyHostnamesConfig)
+
+
+def test_environment_allowed_hostnames_override_config_file(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ config_path = tmp_path / "development.cfg"
+ config_path.write_text('ALLOWED_HOSTNAMES = ["first.example"]\n')
+ monkeypatch.setenv("WEBMENTIONS_SSG_ALLOWED_HOSTNAMES", '["SECOND.EXAMPLE"]')
+
+ class LocalDevelopmentConfig(DevelopmentConfig):
+ CONFIG_FILE = str(config_path)
+ LOG_FILE = str(tmp_path / "development.log")
+
+ app = create_app(LocalDevelopmentConfig)
+ assert app.config["ALLOWED_HOSTNAMES"] == {"second.example"}
diff --git a/webmentions_ssg/__init__.py b/webmentions_ssg/__init__.py
index c4ad4f6..518add0 100644
--- a/webmentions_ssg/__init__.py
+++ b/webmentions_ssg/__init__.py
@@ -20,7 +20,12 @@ from flask_sqlalchemy import SQLAlchemy
from flask_wtf.csrf import CSRFProtect
from sqlalchemy.orm import DeclarativeBase
-from webmentions_ssg.config import DefaultConfig, DevelopmentConfig, ProductionConfig
+from webmentions_ssg.config import (
+ DefaultConfig,
+ DevelopmentConfig,
+ ProductionConfig,
+ normalize_allowed_hostnames,
+)
from .tasks import Huey
from .url_security import is_http_url
@@ -72,10 +77,17 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
app.config.from_object(config_class)
if not app.testing:
- app.config.from_pyfile(app.config["CONFIG_FILE"], silent=True)
+ # Local development may omit its config file; production must not.
+ app.config.from_pyfile(app.config["CONFIG_FILE"], silent=app.debug)
app.config.from_prefixed_env(prefix="FLASK")
app.config.from_prefixed_env(prefix="WEBMENTIONS_SSG")
+ app.config["ALLOWED_HOSTNAMES"] = normalize_allowed_hostnames(
+ app.config["ALLOWED_HOSTNAMES"]
+ )
+ if not app.testing and not app.debug and not app.config["ALLOWED_HOSTNAMES"]:
+ raise RuntimeError("Configure ALLOWED_HOSTNAMES before running in production.")
+
if (
not app.testing
and not app.debug
diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py
index 2661704..8cad51f 100644
--- a/webmentions_ssg/config.py
+++ b/webmentions_ssg/config.py
@@ -8,12 +8,31 @@ import logging
import secrets
+def normalize_allowed_hostnames(value: object) -> set[str]:
+ """Validate and normalize the configured collection of allowed hostnames."""
+ if not isinstance(value, (list, tuple, set, frozenset)):
+ raise TypeError(
+ "ALLOWED_HOSTNAMES must be a list, tuple, or set of hostnames, not a string."
+ )
+
+ hostnames: set[str] = set()
+ for hostname in value:
+ if not isinstance(hostname, str) or not hostname.strip():
+ raise ValueError("ALLOWED_HOSTNAMES must contain non-empty strings only.")
+ hostnames.add(hostname.strip().lower())
+ return hostnames
+
+
class DefaultConfig:
TESTING = False
DEBUG = False
SECRET_KEY = secrets.token_urlsafe()
BOOTSTRAP_SERVE_LOCAL = True
# BOOTSTRAP_BOOTSWATCH_THEME = "Materia"
+ # Secure by default; deployment configuration can override these values.
+ SESSION_COOKIE_SECURE = True
+ SESSION_COOKIE_HTTPONLY = True
+ SESSION_COOKIE_SAMESITE = "Lax"
LOG_FILE = "/var/log/webmentions-ssg.log"
LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s"
LOG_LEVEL = logging.INFO
@@ -21,6 +40,12 @@ class DefaultConfig:
LOGFILE_BACKUP_COUNT = 10
SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db"
+ # Empty by default: no target hostnames are accepted until configured.
+ ALLOWED_HOSTNAMES = set()
+ MAX_REDIRECTS = 20
+ MAX_SOURCE_BYTES = 1_000_000
+ REQUEST_TIMEOUT = 5.0
+
SOURCE_DIRECTORY = None
SOURCE_BASE_URL = None
SCANNER_SCHEDULE = "0 * * * *"
@@ -48,6 +73,7 @@ class DefaultConfig:
class DevelopmentConfig(DefaultConfig):
DEBUG = True
+ SESSION_COOKIE_SECURE = False
LOG_FILE = "testing/webmentions-ssg.log"
LOG_LEVEL = logging.DEBUG
CONFIG_FILE = "testing/webmentions-ssg.cfg"
@@ -59,6 +85,7 @@ class ProductionConfig(DefaultConfig):
class TestingConfig(DefaultConfig):
TESTING = True
+ SESSION_COOKIE_SECURE = False
SECRET_KEY = "testing-secret-key"
WTF_CSRF_ENABLED = False
@@ -72,7 +99,3 @@ class TestingConfig(DefaultConfig):
HUEY_URL = "memory://"
ALLOWED_HOSTNAMES = {"dennisfink.me"}
-
- MAX_REDIRECTS = 20
- MAX_SOURCE_BYTES = 1_000_000
- REQUEST_TIMEOUT = 5.0
diff --git a/webmentions_ssg/forms/validators.py b/webmentions_ssg/forms/validators.py
index 67ab9c0..dd0ee9b 100644
--- a/webmentions_ssg/forms/validators.py
+++ b/webmentions_ssg/forms/validators.py
@@ -85,7 +85,8 @@ class AllowedHostname:
:param field: Field containing the URL to validate.
:raises ValidationError: If the URL hostname is not configured as allowed.
"""
- if urlsplit(field.data).hostname in current_app.config["ALLOWED_HOSTNAMES"]:
+ hostname = urlsplit(field.data).hostname
+ if hostname is not None and hostname in current_app.config["ALLOWED_HOSTNAMES"]:
return
raise ValidationError(self.message or field.gettext("Invalid input."))