Lukas
100fd47c4b
Models in app/models/ are now pure data classes with no cross-layer dependencies. This ensures the models layer remains a true leaf node in the dependency graph. Changes: - Create app/models/_common.py with shared types (TimeRange, bucket_count, constants) - Move TimeRange and time-range constants from ban.py to _common.py - Update history.py, routers, and services to import from _common.py - Remove imports from app.config and app.utils from config.py models - Move field validators from models to router layer: - Add log_target validation in config_misc router - Add log_path validation in jail_config router - Update test_models.py to reflect validators moved to router layer - Update documentation (Architekture.md, Backend-Development.md) with model layering rules - Fix import ordering and type annotations in affected files Model layering rule: Models may only import from: ✓ Standard library and third-party packages (Pydantic, typing) ✓ Other models in app/models/ (sibling models) ✓ app.models.response (response envelopes) ✗ app.services, app.config, app.utils, or any application layer Validation requiring app-level state (settings, allowed directories) now happens at the router or service layer, not in model validators. Fixes: Models were not true leaf nodes due to circular imports and app-layer dependencies Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
245 lines
8.9 KiB
Python
245 lines
8.9 KiB
Python
"""Ban management Pydantic models.
|
|
|
|
Request, response, and domain models used by the ban router and service.
|
|
"""
|
|
|
|
from typing import Literal
|
|
|
|
from pydantic import Field
|
|
|
|
from app.models.response import BanGuiBaseModel, CollectionResponse, PaginatedListResponse
|
|
|
|
|
|
class BanRequest(BanGuiBaseModel):
|
|
"""Payload for ``POST /api/bans`` (ban an IP)."""
|
|
|
|
ip: str = Field(..., description="IP address to ban.")
|
|
jail: str = Field(..., description="Jail in which to apply the ban.")
|
|
|
|
class UnbanRequest(BanGuiBaseModel):
|
|
"""Payload for ``DELETE /api/bans`` (unban an IP)."""
|
|
|
|
ip: str = Field(..., description="IP address to unban.")
|
|
jail: str | None = Field(
|
|
default=None,
|
|
description="Jail to remove the ban from. ``null`` means all jails.",
|
|
)
|
|
unban_all: bool = Field(
|
|
default=False,
|
|
description="When ``true`` the IP is unbanned from every jail.",
|
|
)
|
|
|
|
#: Discriminator literal for the origin of a ban.
|
|
BanOrigin = Literal["blocklist", "selfblock"]
|
|
|
|
#: Jail name used by the blocklist import service.
|
|
BLOCKLIST_JAIL: str = "blocklist-import"
|
|
|
|
def _derive_origin(jail: str) -> BanOrigin:
|
|
"""Derive the ban origin from the jail name.
|
|
|
|
Args:
|
|
jail: The jail that issued the ban.
|
|
|
|
Returns:
|
|
``"blocklist"`` when the jail is the dedicated blocklist-import
|
|
jail, ``"selfblock"`` otherwise.
|
|
"""
|
|
return "blocklist" if jail == BLOCKLIST_JAIL else "selfblock"
|
|
|
|
class Ban(BanGuiBaseModel):
|
|
"""Domain model representing a single active or historical ban record."""
|
|
|
|
ip: str = Field(..., description="Banned IP address.")
|
|
jail: str = Field(..., description="Jail that issued the ban.")
|
|
banned_at: str = Field(..., description="ISO 8601 UTC timestamp of the ban.")
|
|
expires_at: str | None = Field(
|
|
default=None,
|
|
description="ISO 8601 UTC expiry timestamp, or ``null`` if permanent.",
|
|
)
|
|
ban_count: int = Field(..., ge=1, description="Number of times this IP was banned.")
|
|
country: str | None = Field(
|
|
default=None,
|
|
description="ISO 3166-1 alpha-2 country code resolved from the IP.",
|
|
)
|
|
origin: BanOrigin = Field(
|
|
...,
|
|
description="Whether this ban came from a blocklist import or fail2ban itself.",
|
|
)
|
|
|
|
class BanResponse(BanGuiBaseModel):
|
|
"""Response containing a single ban record."""
|
|
|
|
ban: Ban
|
|
|
|
class BanListResponse(PaginatedListResponse[Ban]):
|
|
"""Paginated list of ban records.
|
|
|
|
Request: `GET /api/bans` with optional pagination and filter parameters.
|
|
Response: Paginated collection of ban records with total count.
|
|
|
|
Note: Unlike most list endpoints, this endpoint uses `page` and `page_size`
|
|
for pagination. When using this response, ensure the router provides these fields.
|
|
"""
|
|
|
|
pass
|
|
|
|
class ActiveBan(BanGuiBaseModel):
|
|
"""A currently active ban entry returned by ``GET /api/bans/active``."""
|
|
|
|
ip: str = Field(..., description="Banned IP address.")
|
|
jail: str = Field(..., description="Jail holding the ban.")
|
|
banned_at: str | None = Field(default=None, description="ISO 8601 UTC start of the ban.")
|
|
expires_at: str | None = Field(
|
|
default=None,
|
|
description="ISO 8601 UTC expiry, or ``null`` if permanent.",
|
|
)
|
|
ban_count: int = Field(default=1, ge=1, description="Running ban count for this IP.")
|
|
country: str | None = Field(default=None, description="ISO 3166-1 alpha-2 country code.")
|
|
|
|
class ActiveBanListResponse(CollectionResponse[ActiveBan]):
|
|
"""List of all currently active bans across all jails.
|
|
|
|
Request: `GET /api/bans/active` with optional filter parameters.
|
|
Response: Non-paginated collection of currently active bans with total count.
|
|
|
|
Note: This endpoint does not support pagination. All matching bans are returned.
|
|
For paginated results, use individual jail endpoints or the dashboard ban-list view.
|
|
"""
|
|
|
|
pass
|
|
|
|
class UnbanAllResponse(BanGuiBaseModel):
|
|
"""Response for ``DELETE /api/bans/all``."""
|
|
|
|
message: str = Field(..., description="Human-readable summary of the operation.")
|
|
count: int = Field(..., ge=0, description="Number of IPs that were unbanned.")
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Dashboard ban-list view models
|
|
# ---------------------------------------------------------------------------
|
|
|
|
class DashboardBanItem(BanGuiBaseModel):
|
|
"""A single row in the dashboard ban-list table.
|
|
|
|
Populated from the fail2ban database and enriched with geo data.
|
|
"""
|
|
|
|
ip: str = Field(..., description="Banned IP address.")
|
|
jail: str = Field(..., description="Jail that issued the ban.")
|
|
banned_at: str = Field(..., description="ISO 8601 UTC timestamp of the ban.")
|
|
service: str | None = Field(
|
|
default=None,
|
|
description="First matched log line — used as context for the ban.",
|
|
)
|
|
country_code: str | None = Field(
|
|
default=None,
|
|
description="ISO 3166-1 alpha-2 country code, or ``null`` if unknown.",
|
|
)
|
|
country_name: str | None = Field(
|
|
default=None,
|
|
description="Human-readable country name, or ``null`` if unknown.",
|
|
)
|
|
asn: str | None = Field(
|
|
default=None,
|
|
description="Autonomous System Number string (e.g. ``'AS3320'``).",
|
|
)
|
|
org: str | None = Field(
|
|
default=None,
|
|
description="Organisation name associated with the IP.",
|
|
)
|
|
ban_count: int = Field(..., ge=1, description="How many times this IP was banned.")
|
|
origin: BanOrigin = Field(
|
|
...,
|
|
description="Whether this ban came from a blocklist import or fail2ban itself.",
|
|
)
|
|
|
|
class DashboardBanListResponse(PaginatedListResponse[DashboardBanItem]):
|
|
"""Paginated dashboard ban-list response.
|
|
|
|
Request: `GET /api/dashboard/bans` with time range, page, and filter parameters.
|
|
Response: Paginated collection of dashboard ban items with geo-enrichment.
|
|
"""
|
|
|
|
pass
|
|
|
|
class BansByCountryResponse(BanGuiBaseModel):
|
|
"""Response for the bans-by-country aggregation endpoint.
|
|
|
|
Contains a per-country ban count, a human-readable country name map, and
|
|
the full (un-paginated) ban list for the selected time window so the
|
|
frontend can render both the world map and its companion table from a
|
|
single request.
|
|
"""
|
|
|
|
countries: dict[str, int] = Field(
|
|
default_factory=dict,
|
|
description="ISO 3166-1 alpha-2 country code → ban count.",
|
|
)
|
|
country_names: dict[str, str] = Field(
|
|
default_factory=dict,
|
|
description="ISO 3166-1 alpha-2 country code → human-readable country name.",
|
|
)
|
|
bans: list[DashboardBanItem] = Field(
|
|
default_factory=list,
|
|
description="All bans in the selected time window (up to the server limit).",
|
|
)
|
|
total: int = Field(..., ge=0, description="Total ban count in the window.")
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Trend endpoint models
|
|
|
|
|
|
class BanTrendBucket(BanGuiBaseModel):
|
|
"""A single time bucket in the ban trend series."""
|
|
|
|
timestamp: str = Field(..., description="ISO 8601 UTC start of the bucket.")
|
|
count: int = Field(..., ge=0, description="Number of bans that started in this bucket.")
|
|
|
|
class BanTrendResponse(BanGuiBaseModel):
|
|
"""Response for the ``GET /api/dashboard/bans/trend`` endpoint."""
|
|
|
|
buckets: list[BanTrendBucket] = Field(
|
|
default_factory=list,
|
|
description="Time-ordered list of ban-count buckets covering the full window.",
|
|
)
|
|
bucket_size: str = Field(
|
|
...,
|
|
description="Human-readable bucket size label (e.g. '1h', '6h', '1d', '7d').",
|
|
)
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# By-jail endpoint models
|
|
# ---------------------------------------------------------------------------
|
|
|
|
class JailBanCount(BanGuiBaseModel):
|
|
"""A single jail entry in the bans-by-jail aggregation."""
|
|
|
|
jail: str = Field(..., description="Jail name.")
|
|
count: int = Field(..., ge=0, description="Number of bans recorded in this jail.")
|
|
|
|
class BansByJailResponse(BanGuiBaseModel):
|
|
"""Response for the ``GET /api/dashboard/bans/by-jail`` endpoint."""
|
|
|
|
jails: list[JailBanCount] = Field(
|
|
default_factory=list,
|
|
description="Jails ordered by ban count descending.",
|
|
)
|
|
total: int = Field(..., ge=0, description="Total ban count in the selected window.")
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Jail-specific paginated bans
|
|
# ---------------------------------------------------------------------------
|
|
|
|
class JailBannedIpsResponse(PaginatedListResponse[ActiveBan]):
|
|
"""Paginated response for ``GET /api/jails/{name}/banned``.
|
|
|
|
Contains only the current page of active ban entries for a single jail,
|
|
geo-enriched exclusively for the page slice to avoid rate-limit issues.
|
|
|
|
Request: `GET /api/jails/{name}/banned` with page and page_size parameters.
|
|
Response: Paginated collection of active bans for the specified jail.
|
|
"""
|
|
|
|
pass
|