# huxynsys/bruteforceguard architecture

> Architecture diagram of the GitHub repository huxynsys/bruteforceguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huxynsys/bruteforceguard
- Repository: https://github.com/huxynsys/bruteforceguard

## Overview

BruteForceGuard is an authentication-threat monitoring platform: host collectors normalize authentication logs and send events to a FastAPI backend, which detects attack patterns, creates alerts, correlates them into sessions, and enriches risk context. The frontend presents events, alerts, sessions, dashboards, and intelligence details. The README is empty, and several API and service implementations were not sampled; the graph therefore omits uncertain internal wiring while retaining the major product areas indicated by the source tree.

Main entry points: [`backend/app/main.py`](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/main.py) (FastAPI application), [`collectors/common/models.py`](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/common/models.py) (Event model), [`frontend/src/pages`](https://github.com/huxynsys/bruteforceguard/tree/main/frontend/src/pages) (Analyst pages), [`frontend/src/api/client.ts`](https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/api/client.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Event collection"]
  node_linux["Linux SSH parser<br/>[ssh_auth_parser.py]"]
  node_windows["Windows parser<br/>[security_parser.py]"]
  node_json["JSON collector<br/>[json_collector.py]"]
  node_normalizer["Event model<br/>[models.py]"]
  node_sender["Event sender<br/>[sender.py]"]
end

subgraph group_backend["Detection backend"]
  node_api["FastAPI application<br/>[main.py]"]
  node_events_api["Event endpoints<br/>[events.py]"]
  node_detection["Pattern detection"]
  node_event_service["Event processing<br/>[event_service.py]"]
  node_attack_sessions["Session correlation"]
  node_session_service["Session lifecycle<br/>[session_service.py]"]
  node_alerts_api["Alert endpoints<br/>[alerts.py]"]
  node_sessions_api["Session endpoints<br/>[attack_sessions.py]"]
  node_dashboard_api["Dashboard endpoints<br/>[dashboard.py]"]
  node_blacklist["Blacklist endpoints<br/>[blacklist.py]"]
end

subgraph group_intel["Threat intelligence"]
  node_intel_service["Enrichment and scoring<br/>[service.py]"]
  node_intel_provider["Local intel provider<br/>[local_provider.py]"]
  node_intel_repo["Indicator repository<br/>[repository.py]"]
end

subgraph group_frontend["Analyst interface"]
  node_frontend_app["Frontend routes<br/>[App.tsx]"]
  node_pages["Analyst pages"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_session_details["Session intelligence view<br/>[SessionDetails.tsx]"]
end

subgraph group_storage["Persistent state"]
  node_database[("Application database<br/>[database.py]")]
  node_event_models["Domain models"]
end

node_analyst(("Security analyst"))
node_host(("Monitored host"))

node_host -->|"provides logs"| node_linux
node_linux -->|"produces events"| node_normalizer
node_windows -->|"produces events"| node_normalizer
node_json -->|"produces events"| node_normalizer
node_normalizer -->|"serializes events"| node_sender
node_sender -->|"submits events"| node_events_api
node_api -->|"mounts router"| node_events_api
node_api -->|"mounts router"| node_alerts_api
node_api -->|"mounts router"| node_sessions_api
node_api -->|"mounts router"| node_dashboard_api
node_api -->|"mounts router"| node_blacklist
node_detection -->|"queries and writes"| node_database
node_session_service -->|"reads and writes"| node_database
node_intel_repo -->|"reads and writes"| node_database
node_intel_service -->|"looks up indicators"| node_intel_provider
node_intel_service -->|"uses indicator storage"| node_intel_repo
node_frontend_app -->|"routes to"| node_pages
node_pages -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_api
node_pages -->|"renders session view"| node_session_details
node_session_details -->|"requests intelligence"| node_api_client
node_analyst -->|"uses interface"| node_frontend_app

click node_linux "https://github.com/huxynsys/bruteforceguard/blob/main/collectors/linux/ssh_auth_parser.py"
click node_windows "https://github.com/huxynsys/bruteforceguard/blob/main/collectors/windows/security_parser.py"
click node_json "https://github.com/huxynsys/bruteforceguard/blob/main/collectors/json/json_collector.py"
click node_normalizer "https://github.com/huxynsys/bruteforceguard/blob/main/collectors/common/models.py"
click node_sender "https://github.com/huxynsys/bruteforceguard/blob/main/collectors/common/sender.py"
click node_api "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/main.py"
click node_events_api "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/events.py"
click node_detection "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/detection_service.py"
click node_event_service "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/event_service.py"
click node_attack_sessions "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/attack_session_service.py"
click node_session_service "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/session_service.py"
click node_alerts_api "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/alerts.py"
click node_sessions_api "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/attack_sessions.py"
click node_dashboard_api "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/dashboard.py"
click node_blacklist "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/v1/endpoints/blacklist.py"
click node_intel_service "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/service.py"
click node_intel_provider "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/local_provider.py"
click node_intel_repo "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/repository.py"
click node_frontend_app "https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/huxynsys/bruteforceguard/tree/main/frontend/src/pages"
click node_api_client "https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/api/client.ts"
click node_session_details "https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/components/sessions/SessionDetails.tsx"
click node_database "https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/db/database.py"
click node_event_models "https://github.com/huxynsys/bruteforceguard/tree/main/backend/app/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_linux,node_windows,node_json,node_normalizer,node_sender toneBlue
class node_api,node_events_api,node_detection,node_event_service,node_attack_sessions,node_session_service,node_alerts_api,node_sessions_api,node_dashboard_api,node_blacklist toneAmber
class node_intel_service,node_intel_provider,node_intel_repo toneMint
class node_frontend_app,node_pages,node_api_client,node_session_details toneRose
class node_database,node_event_models,node_analyst,node_host toneIndigo
```

## Components

### Event collection

- [Linux SSH parser](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/linux/ssh_auth_parser.py): `collectors/linux/ssh_auth_parser.py`
- [Windows parser](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/windows/security_parser.py): `collectors/windows/security_parser.py`
- [JSON collector](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/json/json_collector.py): `collectors/json/json_collector.py`
- [Event model](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/common/models.py): `collectors/common/models.py`
- [Event sender](https://github.com/huxynsys/bruteforceguard/blob/main/collectors/common/sender.py): `collectors/common/sender.py`

### Detection backend

- [FastAPI application](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/main.py): `backend/app/main.py`
- [Event endpoints](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/events.py): `backend/app/api/events.py`
- [Pattern detection](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/detection_service.py): `backend/app/services/detection_service.py`
- [Event processing](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/event_service.py): `backend/app/services/event_service.py`
- [Session correlation](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/attack_session_service.py): `backend/app/services/attack_session_service.py`
- [Session lifecycle](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- [Alert endpoints](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/alerts.py): `backend/app/api/alerts.py`
- [Session endpoints](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/attack_sessions.py): `backend/app/api/attack_sessions.py`
- [Dashboard endpoints](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/dashboard.py): `backend/app/api/dashboard.py`
- [Blacklist endpoints](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/api/v1/endpoints/blacklist.py): `backend/app/api/v1/endpoints/blacklist.py`

### Threat intelligence

- [Enrichment and scoring](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/service.py): `backend/app/intelligence/service.py`
- [Local intel provider](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/local_provider.py): `backend/app/intelligence/local_provider.py`
- [Indicator repository](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/intelligence/repository.py): `backend/app/intelligence/repository.py`

### Analyst interface

- [Frontend routes](https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Analyst pages](https://github.com/huxynsys/bruteforceguard/tree/main/frontend/src/pages): `frontend/src/pages`
- [HTTP client](https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Session intelligence view](https://github.com/huxynsys/bruteforceguard/blob/main/frontend/src/components/sessions/SessionDetails.tsx): `frontend/src/components/sessions/SessionDetails.tsx`

### Persistent state

- [Application database](https://github.com/huxynsys/bruteforceguard/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Domain models](https://github.com/huxynsys/bruteforceguard/tree/main/backend/app/models): `backend/app/models`

### Other components

- **Security analyst**
- **Monitored host**

## Connections

- Monitored host → Linux SSH parser: provides logs
- Linux SSH parser → Event model: produces events
- Windows parser → Event model: produces events
- JSON collector → Event model: produces events
- Event model → Event sender: serializes events
- Event sender → Event endpoints: submits events
- FastAPI application → Event endpoints: mounts router
- FastAPI application → Alert endpoints: mounts router
- FastAPI application → Session endpoints: mounts router
- FastAPI application → Dashboard endpoints: mounts router
- FastAPI application → Blacklist endpoints: mounts router
- Pattern detection → Application database: queries and writes
- Session lifecycle → Application database: reads and writes
- Indicator repository → Application database: reads and writes
- Enrichment and scoring → Local intel provider: looks up indicators
- Enrichment and scoring → Indicator repository: uses indicator storage
- Frontend routes → Analyst pages: routes to
- Analyst pages → HTTP client: requests data
- HTTP client → FastAPI application: calls API
- Analyst pages → Session intelligence view: renders session view
- Session intelligence view → HTTP client: requests intelligence
- Security analyst → Frontend routes: uses interface