Security hardening (v0.3.0)

- Breaking: admin panel is fail-closed; requests denied with 401 when no auth callable is configured (CWE-306)
- Detail view renders detail_fields() so hidden columns no longer leak (CWE-200)
- Extended sensitive/authorization field detection; matched fields forced read-only to prevent mass-assignment (CWE-915)
- CSRF cookie sets HttpOnly and Max-Age (CWE-1004)
- Security headers + CSP on admin HTML responses (CWE-1021)
- Non-integer page no longer 500s; page clamped (CWE-20)
- Security events logged (CWE-778)

Author: Berik Ashimov

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0 — 2026-06-10
+
+Security hardening — **breaking**.
+
+- **Breaking:** the admin panel is now fail-closed — when no `auth` callable is configured, all requests are denied with HTTP 401 (previously they were silently allowed) (CWE-306). Pass an `auth` callable to enable access.
+- Detail views render only `detail_fields()` (derived from `list_display` when configured), so columns hidden from the list no longer leak on the detail page (CWE-200).
+- Sensitive/authorization field detection extended to `role`/`admin`/`superuser`/`permission`/`privilege`/`staff`/`scope`; matched fields are forced read-only unless explicitly opted into `form_fields`, preventing mass-assignment privilege escalation (CWE-915).
+- CSRF cookie now sets `HttpOnly` and `Max-Age` (CWE-1004).
+- Admin HTML responses carry `X-Frame-Options`, `X-Content-Type-Options`, `Referrer-Policy`, and a restrictive `Content-Security-Policy` (CWE-1021).
+- Non-integer `?page=` values no longer cause a 500; page is clamped to a maximum (CWE-20).
+- Security events (auth/CSRF failures, blocked mutations) are now logged (CWE-778).
+
 ## 0.2.0 — 2026-05-16
 
 Security hardening — **breaking**.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hawkapi-admin"
-version = "0.2.0"
+version = "0.3.0"
 description = "Auto-generated admin UI for HawkAPI + SQLAlchemy — list, detail, create, edit, delete with no boilerplate"
 readme = "README.md"
 license = { file = "LICENSE" }

src/hawkapi_admin/_admin.py

@@ -15,6 +15,13 @@
 AuthCallable = Callable[[Any], Awaitable[None]]
 
 
+async def _deny_all_auth(_request: Any) -> None:
+    """Default fail-closed auth: deny every request when no auth is configured."""
+    from hawkapi import HTTPException
+
+    raise HTTPException(401, detail="Admin authentication is not configured")
+
+
 class Admin:
     """Top-level admin object. Build one per HawkAPI app and register resources."""
 
@@ -29,14 +36,17 @@ def __init__(
         self.title = title
         self.url_prefix = url_prefix.rstrip("/") or "/admin"
         self.resources: dict[str, ModelResource] = {}
-        self.auth: AuthCallable | None = auth
         self.csrf_enabled: bool = csrf_enabled
         if auth is None:
             warnings.warn(
-                "hawkapi-admin: no auth configured; all admin endpoints are publicly accessible",
+                "hawkapi-admin: no auth configured; all admin endpoints will deny "
+                "access (fail-closed). Pass an `auth` callable to enable the panel.",
                 UserWarning,
                 stacklevel=2,
             )
+            self.auth: AuthCallable = _deny_all_auth
+        else:
+            self.auth = auth
 
     def register(self, resource: ModelResource | type[Any], **kwargs: Any) -> ModelResource:
         """Register ``resource`` with the admin. Accepts a SQLAlchemy model class
@@ -57,16 +67,15 @@ def register(self, resource: ModelResource | type[Any], **kwargs: Any) -> ModelR
         return resource
 
     async def _check_auth(self, request: Any) -> None:
-        if self.auth is not None:
-            await self.auth(request)
+        await self.auth(request)
 
     def attach(self, app: Any) -> None:
         """Wire the admin routes onto ``app``."""
         prefix = self.url_prefix
         admin = self
-        if self.auth is None:
+        if self.auth is _deny_all_auth:
             _logger.warning(
-                "hawkapi-admin: no auth configured; all admin endpoints are publicly accessible"
+                "hawkapi-admin: no auth configured; all admin endpoints deny access (fail-closed)"
             )
 
         async def _index(request: Any) -> Any:

src/hawkapi_admin/_csrf.py

@@ -6,11 +6,10 @@
   * Templates render the same token as a hidden ``<input name="_csrf">``.
   * POST handlers compare cookie and form value via ``hmac.compare_digest``.
 
-The cookie is intentionally NOT ``HttpOnly`` so Jinja-rendered server-side
-templates can echo it back without needing JavaScript — but the template
-reads it from the request scope, not the cookie itself, so the lack of
-HttpOnly is purely a defense-in-depth concern (an attacker who can run JS
-on the admin origin has already lost).
+The cookie is ``HttpOnly``: templates echo the token from the request scope
+(server-side), not from the cookie via JavaScript, so there is no reason to
+expose it to client scripts. The cookie is also short-lived (``Max-Age``) so
+tokens rotate rather than living indefinitely.
 """
 
 from __future__ import annotations
@@ -51,7 +50,7 @@ def ensure_csrf_token(request: Any) -> str:
 
 def build_set_cookie_header(token: str, *, path: str) -> str:
     """Build a Set-Cookie header value for the CSRF cookie."""
-    return f"{COOKIE_NAME}={token}; Path={path}; Secure; SameSite=Lax"
+    return f"{COOKIE_NAME}={token}; Path={path}; Max-Age=86400; Secure; HttpOnly; SameSite=Lax"
 
 
 def validate_csrf(request: Any, form: Any) -> None:

src/hawkapi_admin/_resource.py

@@ -11,7 +11,11 @@
 
 from ._inspect import FieldSpec, list_fields, primary_key_column
 
-_SENSITIVE_NAME_RE = re.compile(r"(password|secret|token|key|hash)$", re.IGNORECASE)
+_SENSITIVE_NAME_RE = re.compile(
+    r"(password|secret|token|key|hash"
+    r"|role|admin|superuser|permission|privilege|staff|scope)$",
+    re.IGNORECASE,
+)
 
 
 @dataclass
@@ -54,6 +58,7 @@ class ModelResource:
 
     _fields: list[FieldSpec] = field(default_factory=list, init=False)
     _pk_name: str = field(default="", init=False)
+    _list_display_explicit: bool = field(default=False, init=False)
 
     def __post_init__(self) -> None:
         if not self.name:
@@ -64,20 +69,35 @@ def __post_init__(self) -> None:
             self.label_plural = self.label + "s"
         self._fields = list_fields(self.model)
         self._pk_name = primary_key_column(self.model)
+        # Remember whether the developer explicitly opted a field into the form,
+        # so enforcement below doesn't override a deliberate choice.
+        explicit_form_fields = set(self.form_fields)
+        self._list_display_explicit = bool(self.list_display)
         if not self.list_display:
             self.list_display = tuple(f.name for f in self._fields)
         if not self.form_fields:
             self.form_fields = tuple(f.name for f in self._fields if not f.primary_key)
+        # Enforce: sensitive / authorization-bearing fields are made read-only
+        # (and thus excluded from editable_fields) unless the developer explicitly
+        # listed them in form_fields. This prevents mass-assignment of fields like
+        # is_admin / role / password_hash via the edit form.
+        readonly = list(self.readonly_fields)
         for name in self.form_fields:
             if name in self.readonly_fields:
                 continue
             if _SENSITIVE_NAME_RE.search(name):
                 warnings.warn(
                     f"hawkapi-admin: field {self.model.__name__}.{name} looks "
+                    f"sensitive; forcing it read-only to prevent mass-assignment"
+                    if name not in explicit_form_fields
+                    else f"hawkapi-admin: field {self.model.__name__}.{name} looks "
                     f"sensitive but is not in readonly_fields",
                     UserWarning,
                     stacklevel=2,
                 )
+                if name not in explicit_form_fields and name not in readonly:
+                    readonly.append(name)
+        self.readonly_fields = tuple(readonly)
 
     @property
     def fields(self) -> list[FieldSpec]:
@@ -96,6 +116,18 @@ def primary_key(self) -> str:
     def display_fields(self) -> list[FieldSpec]:
         return [self.field(n) for n in self.list_display]
 
+    def detail_fields(self) -> list[FieldSpec]:
+        """Fields shown on the detail page.
+
+        Mirrors the configured ``list_display`` so that columns deliberately
+        hidden from the list (e.g. ``password_hash``) are not exposed on the
+        detail view either. Falls back to every mapped column only when no
+        ``list_display`` was configured.
+        """
+        if self._list_display_explicit:
+            return self.display_fields()
+        return list(self._fields)
+
     def editable_fields(self) -> list[FieldSpec]:
         return [self.field(n) for n in self.form_fields if n not in self.readonly_fields]
 

src/hawkapi_admin/_routes.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from pathlib import Path
 from typing import Any
 
@@ -24,6 +25,8 @@
 from ._resource import ModelResource
 
 _TEMPLATES_DIR = Path(__file__).parent / "templates"
+_MAX_PAGE = 10_000
+_logger = logging.getLogger("hawkapi_admin")
 
 
 def _build_env() -> Environment:
@@ -87,9 +90,25 @@ async def _render(
     tpl = _env.get_template(template)
     body = await tpl.render_async(csrf_token=csrf_token, **context)
     resp = HTMLResponse(body, status_code=status_code)
+    _apply_security_headers(resp)
     return _attach_csrf_cookie(request, resp, _admin)
 
 
+# Inline styles (a <style> block plus a handful of style="" attrs) and one
+# inline onclick confirm dialog require 'unsafe-inline'; everything else is
+# locked down to the admin origin.
+_CSP = "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'unsafe-inline'"
+
+
+def _apply_security_headers(response: Response) -> None:
+    """Stamp hardening headers on every admin HTML response."""
+    headers = response.headers
+    headers["X-Frame-Options"] = "DENY"
+    headers["X-Content-Type-Options"] = "nosniff"
+    headers["Referrer-Policy"] = "same-origin"
+    headers["Content-Security-Policy"] = _CSP
+
+
 async def index(request: Request, *, admin: Any) -> Response:
     return await _render(
         request,
@@ -104,7 +123,11 @@ async def list_resource(request: Request, *, admin: Any) -> Response:
     name = str(request.path_params["resource"])
     res = _resource(admin, name)
     q = request.query_params.get("q", "")
-    page = max(1, int(request.query_params.get("page", "1") or 1))
+    try:
+        page = max(1, int(request.query_params.get("page", "1") or 1))
+    except (ValueError, TypeError):
+        page = 1
+    page = min(page, _MAX_PAGE)
     sessions = _session_factory(request)
 
     stmt = select(res.model)
@@ -156,13 +179,17 @@ async def edit_form(request: Request, *, admin: Any) -> Response:
     obj = None
     if pk is not None:
         if not res.can_update:
+            _logger.warning(
+                "admin blocked edit form on resource %r pk=%r (can_update=False)", name, pk
+            )
             raise HTTPException(403)
         async with sessions(commit=False) as sess:
             obj = await sess.get(res.model, pk)
             if obj is None:
                 raise HTTPException(404)
     else:
         if not res.can_create:
+            _logger.warning("admin blocked new form on resource %r (can_create=False)", name)
             raise HTTPException(403)
     values: dict[str, Any] = (
         {f.name: getattr(obj, f.name, "") for f in res.editable_fields()} if obj else {}
@@ -212,12 +239,18 @@ async def save(request: Request, *, admin: Any) -> Response:
     sessions = _session_factory(request)
     form = await request.form()
     if getattr(admin, "csrf_enabled", True):
-        validate_csrf(request, form)
+        try:
+            validate_csrf(request, form)
+        except HTTPException:
+            _logger.warning("admin CSRF validation failed for save on resource %r", name)
+            raise
 
     # Authorization first — fail fast.
     if pk is None and not res.can_create:
+        _logger.warning("admin blocked create on resource %r (can_create=False)", name)
         raise HTTPException(403)
     if pk is not None and not res.can_update:
+        _logger.warning("admin blocked update on resource %r pk=%r (can_update=False)", name, pk)
         raise HTTPException(403)
 
     creating = pk is None
@@ -266,6 +299,12 @@ async def save(request: Request, *, admin: Any) -> Response:
             values=values,
             errors={"_form": detail_msg},
         )
+    _logger.info(
+        "admin %s on resource %r pk=%r succeeded",
+        "create" if creating else "update",
+        name,
+        new_pk,
+    )
     return RedirectResponse(f"{admin.url_prefix}/{name}/{new_pk}", status_code=303)
 
 
@@ -283,17 +322,23 @@ async def delete(request: Request, *, admin: Any) -> Response:
     name = str(request.path_params["resource"])
     res = _resource(admin, name)
     if not res.can_delete:
+        _logger.warning("admin blocked delete on resource %r (can_delete=False)", name)
         raise HTTPException(403)
     if getattr(admin, "csrf_enabled", True):
         form = await request.form()
-        validate_csrf(request, form)
+        try:
+            validate_csrf(request, form)
+        except HTTPException:
+            _logger.warning("admin CSRF validation failed for delete on resource %r", name)
+            raise
     pk = request.path_params["pk"]
     sessions = _session_factory(request)
     async with sessions() as sess:
         obj = await sess.get(res.model, pk)
         if obj is None:
             raise HTTPException(404)
         await sess.delete(obj)
+    _logger.info("admin delete on resource %r pk=%r succeeded", name, pk)
     return RedirectResponse(f"{admin.url_prefix}/{name}", status_code=303)
 
 

src/hawkapi_admin/templates/detail.html

@@ -9,7 +9,7 @@
 <h2>{{ resource.label }} #{{ obj | attr(resource.primary_key) }}</h2>
 
 <div>
-  {% for fs in resource.fields %}
+  {% for fs in resource.detail_fields() %}
   <div class="field-row">
     <div class="muted">{{ fs.name }}</div>
     <div>{{ resource.render_value(obj, fs.name) }}</div>

tests/test_resource.py

@@ -65,6 +65,37 @@ def test_sensitive_field_in_readonly_does_not_warn() -> None:
         ModelResource(model=Secret, readonly_fields=("password_hash",))
 
 
+def test_sensitive_field_forced_readonly() -> None:
+    # password_hash is not explicitly in form_fields, so it must be auto-added
+    # to readonly_fields and excluded from the editable form (mass-assignment guard).
+    with pytest.warns(UserWarning, match="looks sensitive"):
+        r = ModelResource(model=Secret)
+    assert "password_hash" in r.readonly_fields
+    assert "password_hash" not in [f.name for f in r.editable_fields()]
+
+
+def test_sensitive_field_explicit_form_field_stays_editable() -> None:
+    # If the developer explicitly opts the field into the form, honor it (still warns).
+    with pytest.warns(UserWarning, match="looks sensitive"):
+        r = ModelResource(model=Secret, form_fields=("password_hash",))
+    assert "password_hash" not in r.readonly_fields
+    assert "password_hash" in [f.name for f in r.editable_fields()]
+
+
+def test_detail_fields_hides_columns_not_in_list_display() -> None:
+    # Detail view must respect list_display so sensitive columns stay hidden.
+    r = ModelResource(model=User, list_display=("id", "email"))
+    names = [f.name for f in r.detail_fields()]
+    assert names == ["id", "email"]
+    assert "name" not in names
+
+
+def test_detail_fields_defaults_to_all_when_unconfigured() -> None:
+    r = ModelResource(model=User)
+    names = [f.name for f in r.detail_fields()]
+    assert "email" in names and "name" in names
+
+
 def test_duplicate_register_raises() -> None:
     a = Admin(title="t", auth=_noop_auth, csrf_enabled=False)
     a.register(ModelResource(model=User))