lukas.pupkalipinski/BanGUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add ban management features and update documentation

Browse Source 
- Implement ban model, service, and router endpoints in backend
- Add ban table component and dashboard integration in frontend
- Update ban-related types and API endpoints
- Add comprehensive tests for ban service and dashboard router
- Update documentation (Features, Tasks, Architecture, Web-Design)
- Clean up old fail2ban configuration files
- Update Makefile with new commands
This commit is contained in:
Lukas
2026-03-06 20:33:42 +01:00
parent 06738dbfa5
commit cbad4ea706
20 changed files with 58 additions and 760 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
frontend/src/api/dashboard.ts
View File

@@ -1,13 +1,12 @@
/**
* Dashboard API module.
*
* Wraps `GET /api/dashboard/status`, `GET /api/dashboard/bans`, and
* `GET /api/dashboard/accesses`.
* Wraps `GET /api/dashboard/status` and `GET /api/dashboard/bans`.
*/
import { get } from "./client";
import { ENDPOINTS } from "./endpoints";
import type { AccessListResponse, DashboardBanListResponse, TimeRange } from "../types/ban";
import type { DashboardBanListResponse, TimeRange } from "../types/ban";
import type { ServerStatusResponse } from "../types/server";
/**
@@ -43,26 +42,3 @@ export async function fetchBans(
return get<DashboardBanListResponse>(`${ENDPOINTS.dashboardBans}?${params.toString()}`);
}
/**
* Fetch a paginated access list (individual matched log lines) for the
* selected time window.
*
* @param range - Time-range preset.
* @param page - 1-based page number (default `1`).
* @param pageSize - Items per page (default `100`).
* @returns Paginated {@link AccessListResponse}.
* @throws {ApiError} When the server returns a non-2xx status.
*/
export async function fetchAccesses(
range: TimeRange,
page = 1,
pageSize = 100,
): Promise<AccessListResponse> {
const params = new URLSearchParams({
range,
page: String(page),
page_size: String(pageSize),
});
return get<AccessListResponse>(`${ENDPOINTS.dashboardAccesses}?${params.toString()}`);
}

1
frontend/src/api/endpoints.ts
View File

@@ -30,7 +30,6 @@ export const ENDPOINTS = {
dashboardStatus: "/dashboard/status",
dashboardBans: "/dashboard/bans",
dashboardBansByCountry: "/dashboard/bans/by-country",
dashboardAccesses: "/dashboard/accesses",
// -------------------------------------------------------------------------
// Jails

146
frontend/src/components/BanTable.tsx
View File

@@ -1,13 +1,11 @@
/**
* `BanTable` component.
*
* Renders a Fluent UI v9 `DataGrid` for the dashboard ban-list and
* access-list views. Uses the {@link useBans} hook to fetch and manage
* paginated data from the backend.
* Renders a Fluent UI v9 `DataGrid` for the dashboard ban-list view.
* Uses the {@link useBans} hook to fetch and manage paginated data from
* the backend.
*
* Columns differ between modes:
* - `"bans"` — Time, IP, Service, Country, Jail, Ban Count.
* - `"accesses"` — Time, IP, Log Line, Country, Jail.
* Columns: Time, IP, Service, Country, Jail, Ban Count.
*/
import {
@@ -28,8 +26,8 @@ import {
} from "@fluentui/react-components";
import { PageEmpty, PageError, PageLoading } from "./PageFeedback";
import { ChevronLeftRegular, ChevronRightRegular } from "@fluentui/react-icons";
import { useBans, type BanTableMode } from "../hooks/useBans";
import type { AccessListItem, DashboardBanItem, TimeRange } from "../types/ban";
import { useBans } from "../hooks/useBans";
import type { DashboardBanItem, TimeRange } from "../types/ban";
// ---------------------------------------------------------------------------
// Types
@@ -37,8 +35,6 @@ import type { AccessListItem, DashboardBanItem, TimeRange } from "../types/ban";
/** Props for the {@link BanTable} component. */
interface BanTableProps {
/** Whether to render ban records or individual access events. */
mode: BanTableMode;
/**
* Active time-range preset — controlled by the parent `DashboardPage`.
* Changing this value triggers a re-fetch.
@@ -179,68 +175,20 @@ function buildBanColumns(styles: ReturnType<typeof useStyles>): TableColumnDefin
];
}
/** Columns for the access-list view (`mode === "accesses"`). */
function buildAccessColumns(styles: ReturnType<typeof useStyles>): TableColumnDefinition<AccessListItem>[] {
return [
createTableColumn<AccessListItem>({
columnId: "timestamp",
renderHeaderCell: () => "Timestamp",
renderCell: (item) => (
<Text size={200}>{formatTimestamp(item.timestamp)}</Text>
),
}),
createTableColumn<AccessListItem>({
columnId: "ip",
renderHeaderCell: () => "IP Address",
renderCell: (item) => (
<span className={styles.mono}>{item.ip}</span>
),
}),
createTableColumn<AccessListItem>({
columnId: "line",
renderHeaderCell: () => "Log Line",
renderCell: (item) => (
<Tooltip content={item.line} relationship="description">
<span className={`${styles.mono} ${styles.truncate}`}>{item.line}</span>
</Tooltip>
),
}),
createTableColumn<AccessListItem>({
columnId: "country",
renderHeaderCell: () => "Country",
renderCell: (item) => (
<Text size={200}>
{item.country_name ?? item.country_code ?? "—"}
</Text>
),
}),
createTableColumn<AccessListItem>({
columnId: "jail",
renderHeaderCell: () => "Jail",
renderCell: (item) => <Text size={200}>{item.jail}</Text>,
}),
];
}
// ---------------------------------------------------------------------------
// Component
// ---------------------------------------------------------------------------
/**
* Data table for the dashboard ban-list and access-list views.
* Data table for the dashboard ban-list view.
*
* @param props.mode - `"bans"` or `"accesses"`.
* @param props.timeRange - Active time-range preset from the parent page.
*/
export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element {
export function BanTable({ timeRange }: BanTableProps): React.JSX.Element {
const styles = useStyles();
const { banItems, accessItems, total, page, setPage, loading, error, refresh } = useBans(
mode,
timeRange,
);
const { banItems, total, page, setPage, loading, error, refresh } = useBans(timeRange);
const banColumns = buildBanColumns(styles);
const accessColumns = buildAccessColumns(styles);
// --------------------------------------------------------------------------
// Loading state
@@ -259,15 +207,8 @@ export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element
// --------------------------------------------------------------------------
// Empty state
// --------------------------------------------------------------------------
const isEmpty = mode === "bans" ? banItems.length === 0 : accessItems.length === 0;
if (isEmpty) {
return (
<PageEmpty
message={`No ${
mode === "bans" ? "bans" : "accesses"
} recorded in the selected time window.`}
/>
);
if (banItems.length === 0) {
return <PageEmpty message="No bans recorded in the selected time window." />;
}
// --------------------------------------------------------------------------
@@ -279,68 +220,15 @@ export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element
const hasNext = page < totalPages;
// --------------------------------------------------------------------------
// Render — bans mode
// --------------------------------------------------------------------------
if (mode === "bans") {
return (
<div className={styles.root}>
<div className={styles.tableWrapper}>
<DataGrid
items={banItems}
columns={banColumns}
getRowId={(item: DashboardBanItem) => `${item.ip}:${item.jail}:${item.banned_at}`}
>
<DataGridHeader>
<DataGridRow>
{({ renderHeaderCell }) => (
<DataGridHeaderCell>{renderHeaderCell()}</DataGridHeaderCell>
)}
</DataGridRow>
</DataGridHeader>
<DataGridBody<DashboardBanItem>>
{({ item, rowId }) => (
<DataGridRow<DashboardBanItem> key={rowId}>
{({ renderCell }) => (
<DataGridCell>{renderCell(item)}</DataGridCell>
)}
</DataGridRow>
)}
</DataGridBody>
</DataGrid>
</div>
<div className={styles.pagination}>
<Text size={200} style={{ color: tokens.colorNeutralForeground3 }}>
{total} total · Page {page} of {totalPages}
</Text>
<Button
icon={<ChevronLeftRegular />}
appearance="subtle"
disabled={!hasPrev}
onClick={() => { setPage(page - 1); }}
aria-label="Previous page"
/>
<Button
icon={<ChevronRightRegular />}
appearance="subtle"
disabled={!hasNext}
onClick={() => { setPage(page + 1); }}
aria-label="Next page"
/>
</div>
</div>
);
}
// --------------------------------------------------------------------------
// Render — accesses mode
// Render
// --------------------------------------------------------------------------
return (
<div className={styles.root}>
<div className={styles.tableWrapper}>
<DataGrid
items={accessItems}
columns={accessColumns}
getRowId={(item: AccessListItem) => `${item.ip}:${item.jail}:${item.timestamp}:${item.line.slice(0, 40)}`}
items={banItems}
columns={banColumns}
getRowId={(item: DashboardBanItem) => `${item.ip}:${item.jail}:${item.banned_at}`}
>
<DataGridHeader>
<DataGridRow>
@@ -349,9 +237,9 @@ export function BanTable({ mode, timeRange }: BanTableProps): React.JSX.Element
)}
</DataGridRow>
</DataGridHeader>
<DataGridBody<AccessListItem>>
<DataGridBody<DashboardBanItem>>
{({ item, rowId }) => (
<DataGridRow<AccessListItem> key={rowId}>
<DataGridRow<DashboardBanItem> key={rowId}>
{({ renderCell }) => (
<DataGridCell>{renderCell(item)}</DataGridCell>
)}

48
frontend/src/hooks/useBans.ts
View File

@@ -1,27 +1,21 @@
/**
* `useBans` hook.
*
* Fetches and manages paginated ban-list or access-list data from the
* dashboard endpoints. Re-fetches automatically when `timeRange` or `page`
* changes.
* Fetches and manages paginated ban-list data from the dashboard endpoint.
* Re-fetches automatically when `timeRange` or `page` changes.
*/
import { useCallback, useEffect, useRef, useState } from "react";
import { fetchAccesses, fetchBans } from "../api/dashboard";
import type { AccessListItem, DashboardBanItem, TimeRange } from "../types/ban";
import { fetchBans } from "../api/dashboard";
import type { DashboardBanItem, TimeRange } from "../types/ban";
/** The dashboard view mode: aggregate bans or individual access events. */
export type BanTableMode = "bans" | "accesses";
/** Items per page for the ban/access tables. */
/** Items per page for the ban table. */
const PAGE_SIZE = 100;
/** Return value shape for {@link useBans}. */
export interface UseBansResult {
/** Ban items — populated when `mode === "bans"`, otherwise empty. */
/** Ban items for the current page. */
banItems: DashboardBanItem[];
/** Access items — populated when `mode === "accesses"`, otherwise empty. */
accessItems: AccessListItem[];
/** Total records in the selected time window (for pagination). */
total: number;
/** Current 1-based page number. */
@@ -37,50 +31,39 @@ export interface UseBansResult {
}
/**
* Fetch and manage dashboard ban-list or access-list data.
* Fetch and manage dashboard ban-list data.
*
* Automatically re-fetches when `mode`, `timeRange`, or `page` changes.
* Automatically re-fetches when `timeRange` or `page` changes.
*
* @param mode - `"bans"` for the ban-list view; `"accesses"` for the
* access-list view.
* @param timeRange - Time-range preset that controls how far back to look.
* @returns Current data, pagination state, loading flag, and a `refresh`
* callback.
*/
export function useBans(mode: BanTableMode, timeRange: TimeRange): UseBansResult {
export function useBans(timeRange: TimeRange): UseBansResult {
const [banItems, setBanItems] = useState<DashboardBanItem[]>([]);
const [accessItems, setAccessItems] = useState<AccessListItem[]>([]);
const [total, setTotal] = useState<number>(0);
const [page, setPage] = useState<number>(1);
const [loading, setLoading] = useState<boolean>(true);
const [error, setError] = useState<string | null>(null);
// Reset page when mode or time range changes.
// Reset page when time range changes.
useEffect(() => {
setPage(1);
}, [mode, timeRange]);
}, [timeRange]);
const doFetch = useCallback(async (): Promise<void> => {
setLoading(true);
setError(null);
try {
if (mode === "bans") {
const data = await fetchBans(timeRange, page, PAGE_SIZE);
setBanItems(data.items);
setAccessItems([]);
setTotal(data.total);
} else {
const data = await fetchAccesses(timeRange, page, PAGE_SIZE);
setAccessItems(data.items);
setBanItems([]);
setTotal(data.total);
}
const data = await fetchBans(timeRange, page, PAGE_SIZE);
setBanItems(data.items);
setTotal(data.total);
} catch (err: unknown) {
setError(err instanceof Error ? err.message : "Failed to fetch data");
} finally {
setLoading(false);
}
}, [mode, timeRange, page]);
}, [timeRange, page]);
// Stable ref to the latest doFetch so the refresh callback is always current.
const doFetchRef = useRef(doFetch);
@@ -96,7 +79,6 @@ export function useBans(mode: BanTableMode, timeRange: TimeRange): UseBansResult
return {
banItems,
accessItems,
total,
page,
setPage,

36
frontend/src/pages/DashboardPage.tsx
View File

@@ -2,15 +2,12 @@
* Dashboard page.
*
* Composes the fail2ban server status bar at the top, a shared time-range
* selector, and two tabs: "Ban List" (aggregate bans) and "Access List"
* (individual matched log lines). The time-range selection is shared
* between both tabs so users can compare data for the same period.
* selector, and the ban list showing aggregate bans from the fail2ban
* database. The time-range selection controls how far back to look.
*/
import { useState } from "react";
import {
Tab,
TabList,
Text,
ToggleButton,
Toolbar,
@@ -21,7 +18,7 @@ import { BanTable } from "../components/BanTable";
import { ServerStatusBar } from "../components/ServerStatusBar";
import type { TimeRange } from "../types/ban";
import { TIME_RANGE_LABELS } from "../types/ban";
import type { BanTableMode } from "../hooks/useBans";
// ---------------------------------------------------------------------------
// Styles
@@ -83,13 +80,12 @@ const TIME_RANGES: TimeRange[] = ["24h", "7d", "30d", "365d"];
/**
* Main dashboard landing page.
*
* Displays the fail2ban server status, a time-range selector, and a
* tabbed view toggling between the ban list and the access list.
* Displays the fail2ban server status, a time-range selector, and the
* ban list table.
*/
export function DashboardPage(): React.JSX.Element {
const styles = useStyles();
const [timeRange, setTimeRange] = useState<TimeRange>("24h");
const [activeTab, setActiveTab] = useState<BanTableMode>("bans");
return (
<div className={styles.root}>
@@ -99,15 +95,15 @@ export function DashboardPage(): React.JSX.Element {
<ServerStatusBar />
{/* ------------------------------------------------------------------ */}
{/* Ban / access list section */}
{/* Ban list section */}
{/* ------------------------------------------------------------------ */}
<div className={styles.section}>
<div className={styles.sectionHeader}>
<Text as="h2" size={500} weight="semibold">
{activeTab === "bans" ? "Ban List" : "Access List"}
Ban List
</Text>
{/* Shared time-range selector */}
{/* Time-range selector */}
<Toolbar aria-label="Time range" size="small">
{TIME_RANGES.map((r) => (
<ToggleButton
@@ -125,21 +121,9 @@ export function DashboardPage(): React.JSX.Element {
</Toolbar>
</div>
{/* Tab switcher */}
<TabList
selectedValue={activeTab}
onTabSelect={(_, data) => {
setActiveTab(data.value as BanTableMode);
}}
size="small"
>
<Tab value="bans">Ban List</Tab>
<Tab value="accesses">Access List</Tab>
</TabList>
{/* Active tab content */}
{/* Ban table */}
<div className={styles.tabContent}>
<BanTable mode={activeTab} timeRange={timeRange} />
<BanTable timeRange={timeRange} />
</div>
</div>
</div>

47
frontend/src/types/ban.ts
View File

@@ -64,50 +64,3 @@ export interface DashboardBanListResponse {
/** Maximum items per page. */
page_size: number;
}
// ---------------------------------------------------------------------------
// Access-list table item
// ---------------------------------------------------------------------------
/**
* A single row in the dashboard access-list table.
*
* Each row represents one matched log line (failure attempt) that
* contributed to a ban.
*
* Mirrors `AccessListItem` from `backend/app/models/ban.py`.
*/
export interface AccessListItem {
/** IP address of the access event. */
ip: string;
/** Jail that recorded the access. */
jail: string;
/** ISO 8601 UTC timestamp of the ban that captured this access. */
timestamp: string;
/** Raw matched log line. */
line: string;
/** ISO 3166-1 alpha-2 country code, or null. */
country_code: string | null;
/** Human-readable country name, or null. */
country_name: string | null;
/** ASN string, or null. */
asn: string | null;
/** Organisation name, or null. */
org: string | null;
}
/**
* Paginated access-list response from `GET /api/dashboard/accesses`.
*
* Mirrors `AccessListResponse` from `backend/app/models/ban.py`.
*/
export interface AccessListResponse {
/** Access items for the current page. */
items: AccessListItem[];
/** Total number of access events in the selected window. */
total: number;
/** Current 1-based page number. */
page: number;
/** Maximum items per page. */
page_size: number;
}