diff options
| -rw-r--r-- | contrib/webmentions-ssg.example.cfg | 37 | ||||
| -rw-r--r-- | tests/test_config.py | 45 | ||||
| -rw-r--r-- | tests/test_configuration_hardening.py | 119 | ||||
| -rw-r--r-- | webmentions_ssg/__init__.py | 16 | ||||
| -rw-r--r-- | webmentions_ssg/config.py | 31 | ||||
| -rw-r--r-- | webmentions_ssg/forms/validators.py | 3 |
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.")) |
