diff --git a/docs/dashboard.md b/docs/dashboard.md index ace7955..0c5b52f 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -2,20 +2,182 @@ Access the dashboard at `http://:/` -The dashboard shows: -- Total and unique accesses -- Suspicious activity and attack detection -- Top IPs, paths, user-agents and GeoIP localization -- Real-time monitoring +The Krawl dashboard is a single-page application with **5 tabs**: Overview, Attacks, IP Insight, Tracked IPs, and IP Banlist. The last two tabs are only visible after authenticating with the dashboard password. -The attackers' access to the honeypot endpoint and related suspicious activities (such as failed login attempts) are logged. +--- -Krawl also implements a scoring system designed to distinguish between malicious and legitimate behavior on the website. +## Overview -![dashboard-1](../img/dashboard-1.png) +The default landing page provides a high-level summary of all traffic and suspicious activity detected by Krawl. -The top IP Addresses is shown along with top paths and User Agents +### Stats Cards -![dashboard-2](../img/dashboard-2.png) +Seven metric cards are displayed at the top: -![dashboard-3](../img/dashboard-3.png) +- **Total Accesses** — total number of requests received +- **Unique IPs** — distinct IP addresses observed +- **Unique Paths** — distinct request paths +- **Suspicious Accesses** — requests flagged as suspicious +- **Honeypot Caught** — requests that hit honeypot endpoints +- **Credentials Captured** — login attempts captured by the honeypot +- **Unique Attackers** — distinct IPs classified as attackers + +### Search + +A real-time search bar lets you search across attacks, IPs, patterns, and locations. Results are loaded dynamically as you type. + +### IP Origins Map + +An interactive world map (powered by Leaflet) displays the geolocation of top IP addresses. You can filter by category: + +- Attackers +- Bad Crawlers +- Good Crawlers +- Regular Users +- Unknown + +The number of displayed IPs is configurable (top 10, 100, 1,000, or all). + +![Overview — Stats and Map](../img/geoip_dashboard.png) + +### Recent Suspicious Activity + +A table showing the last 10 suspicious requests with IP address, path, user-agent, and timestamp. Each entry provides actions to view the raw HTTP request or inspect the IP in detail. + +### Top IP Addresses + +A paginated, sortable table ranking IPs by access count. Each IP shows its category badge and can be clicked to expand inline details or open the IP Insight tab. + +### Top Paths + +A paginated table of the most accessed HTTP paths and their request counts. + +### Top User-Agents + +A paginated table of the most common user-agent strings with their frequency. + +![Overview — Tables](../img/overview_tables_dashboard.png) + +--- + +## Attacks + +The Attacks tab focuses on detected malicious activity, attack patterns, and captured credentials. + +### Attackers by Total Requests + +A paginated table listing all detected attackers ranked by total requests. Columns include IP, total requests, first seen, last seen, and location. Sortable by multiple fields. + +![Attacks — Attackers and Credentials](../img/top_attackers_dashboard.png) + +### Captured Credentials + +A table of usernames and passwords captured from honeypot login forms, with timestamps. Useful for analyzing common credential stuffing patterns. + +### Honeypot Triggers by IP + +Shows which IPs accessed honeypot endpoints and how many times, sorted by trigger count. + +### Detected Attack Types + +A detailed table of individual attack detections showing IP, path, attack type classifications, user-agent, and timestamp. Each entry can be expanded to view the raw HTTP request. + +### Most Recurring Attack Types + +A Chart.js visualization showing the frequency distribution of detected attack categories (e.g., SQL injection, path traversal, XSS). + +### Most Recurring Attack Patterns + +A paginated table of specific attack patterns and their occurrence counts across all traffic. + +![Attacks — Attack Types and Patterns](../img/attack_types_dashboard.png) + +--- + +## IP Insight + +The IP Insight tab provides a deep-dive view for a single IP address. It is activated by clicking "Inspect IP" from any table in the dashboard. + +### IP Information Card + +Displays comprehensive details about the selected IP: + +- **Activity** — total requests, first seen, last seen, last analysis timestamp +- **Geo & Network** — location, region, timezone, ISP, ASN, reverse DNS +- **Category** — classification badge (Attacker, Good Crawler, Bad Crawler, Regular User, Unknown) + +### Ban & Track Actions + +When authenticated, admin actions are available: + +- **Ban/Unban** — immediately add or remove the IP from the banlist +- **Track/Untrack** — add the IP to your watchlist for ongoing monitoring + +### Blocklist Memberships + +Shows which threat intelligence blocklists the IP appears on, providing external reputation context. + +### Access Logs + +A filtered view of all requests made by this specific IP, with full request details. + +![IP Insight — Detail View](../img/ip_insight_dashboard.png) + +--- + +## Tracked IPs + +> Requires authentication with the dashboard password. + +The Tracked IPs tab lets you maintain a watchlist of IP addresses you want to monitor over time. + +### Track New IP + +A form to add any IP address to your tracking list for ongoing observation. + +### Currently Tracked IPs + +A paginated table of all manually tracked IPs, with the option to untrack each one. + +![Tracked IPs](../img/tracked_ips_dashboard.png) + +--- + +## IP Banlist + +> Requires authentication with the dashboard password. + +The IP Banlist tab provides tools for managing IP bans. Bans are exported every 5 minutes. + +### Force Ban IP + +A form to immediately ban any IP address by entering it manually. + +### Detected Attackers + +A paginated list of all IPs detected as attackers, with quick-ban actions for each entry. + +![IP Banlist — Detected](../img/banlist_attackers_dashboard.png) + +### Active Ban Overrides + +A table of currently active manual ban overrides, with options to unban or reset the override status for each IP. + +![IP Banlist — Overrides](../img/banlist_overrides_dashboard.png) + +### Export Banlist + +A dropdown menu to download the current banlist in two formats: + +- **Raw IPs List** — plain text, one IP per line +- **IPTables Rules** — ready-to-use firewall rules + +--- + +## Authentication + +The dashboard uses session-based authentication with secure HTTP-only cookies. Protected features (Tracked IPs, IP Banlist, ban/track actions) require entering the dashboard password. The login includes brute-force protection with IP-based rate limiting and exponential backoff. + +Click the lock icon in the top-right corner of the navigation bar to authenticate or log out. + +![Authentication Modal](../img/auth_prompt.png) diff --git a/img/attack_types_dashboard.png b/img/attack_types_dashboard.png new file mode 100644 index 0000000..67b4223 Binary files /dev/null and b/img/attack_types_dashboard.png differ diff --git a/img/auth_prompt.png b/img/auth_prompt.png new file mode 100644 index 0000000..934b7e6 Binary files /dev/null and b/img/auth_prompt.png differ diff --git a/img/banlist_attackers_dashboard.png b/img/banlist_attackers_dashboard.png new file mode 100644 index 0000000..7e12d13 Binary files /dev/null and b/img/banlist_attackers_dashboard.png differ diff --git a/img/banlist_overrides_dashboard.png b/img/banlist_overrides_dashboard.png new file mode 100644 index 0000000..e630e86 Binary files /dev/null and b/img/banlist_overrides_dashboard.png differ diff --git a/img/geoip_dashboard.png b/img/geoip_dashboard.png index 5a4f389..e046ffd 100644 Binary files a/img/geoip_dashboard.png and b/img/geoip_dashboard.png differ diff --git a/img/overview_tables_dashboard.png b/img/overview_tables_dashboard.png new file mode 100644 index 0000000..5557101 Binary files /dev/null and b/img/overview_tables_dashboard.png differ diff --git a/img/top_attackers_dashboard.png b/img/top_attackers_dashboard.png new file mode 100644 index 0000000..b86c490 Binary files /dev/null and b/img/top_attackers_dashboard.png differ diff --git a/img/tracked_ips_dashboard.png b/img/tracked_ips_dashboard.png new file mode 100644 index 0000000..13e991e Binary files /dev/null and b/img/tracked_ips_dashboard.png differ