aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-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."))