https://github.com/verifiedjoseph/intruder-alert
Self-hosted event dashboard for Fail2ban
https://github.com/verifiedjoseph/intruder-alert
dashboard docker-image fail2ban fail2ban-dashboard php self-hosted
Last synced: 5 months ago
JSON representation
Self-hosted event dashboard for Fail2ban
- Host: GitHub
- URL: https://github.com/verifiedjoseph/intruder-alert
- Owner: VerifiedJoseph
- License: mit
- Created: 2023-08-22T12:05:35.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-12T03:38:47.000Z (5 months ago)
- Last Synced: 2026-01-16T16:32:31.841Z (5 months ago)
- Topics: dashboard, docker-image, fail2ban, fail2ban-dashboard, php, self-hosted
- Language: PHP
- Homepage: https://verifiedjoseph.github.io/intruder-alert/demo/
- Size: 8.91 MB
- Stars: 28
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Intruder Alert
[](https://github.com/VerifiedJoseph/intruder-alert/releases/latest)
[](LICENSE)
[](https://app.codecov.io/gh/VerifiedJoseph/intruder-alert/)
Intruder Alert is a self-hosted event dashboard for [Fail2ban](https://github.com/fail2ban/fail2ban).
[More screenshots](./docs/screenshots.md)
## Demo
A demo is [available](https://verifiedjoseph.github.io/intruder-alert/demo/) and is built from the latest commit on the `main` brach.
## Installation
### docker-compose
Show/hide details
```yaml
version: '3'
services:
app:
image: ghcr.io/verifiedjoseph/intruder-alert:1.22.9
container_name: intruder-alert
environment:
- IA_TIMEZONE=Europe/London
- IA_SYSTEM_LOG_TIMEZONE=UTC
- IA_MAXMIND_LICENSE_KEY=
- IA_LOG_FOLDER=/app/backend/data/logs
volumes:
- path/to/fail2ban.log:/app/backend/data/logs/fail2ban.log:ro
- path/to/fail2ban.log.1:/app/backend/data/logs/fail2ban.log.1:ro
- path/to/fail2ban.log.2.gz:/app/backend/data/logs/fail2ban.log.2.gz:ro
- path/to/fail2ban.log.3.gz:/app/backend/data/logs/fail2ban.log.3.gz:ro
- path/to/fail2ban.log.4.gz:/app/backend/data/logs/fail2ban.log.4.gz:ro
ports:
- '127.0.0.1:8080:8080'
```
### Manually
Show/hide install details
1) Download the [latest release](https://github.com/VerifiedJoseph/intruder-alert/releases/latest) to your web server and extract the zip archive.
2) Configure the application using `backend/config.php` copied from [`backend/config.example.php`](backend/config.example.php).
```
cp backend/config.example.php backend/config.php
```
3) Create a scheduled task with cron (below) or similar that runs `backend\cron.php` at least once an hour.
```
0 1 * * * php path/to/intruder-alert/backend/cron.php
```
**Notes**
The backend folder does not need to be reachable in the browser and access should blocked.
The scheduled task needs to run as root or a user with permission to read the fail2ban logs.
## Configuration
Environment variables are used to adjust the configuration.
| Name | Type | Description |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------- |
| `IA_LOG_PATHS` | `string` | Comma separated list of Fail2ban log files. |
| `IA_LOG_FOLDER` | `string` | Path of the Fail2ban logs folder.
Ignored when `IA_LOG_PATHS` is set. |
| `IA_MAXMIND_LICENSE_KEY` | `string` | MaxMind license key for GeoLite2 database downloads. |
| `IA_ASN_DATABASE` | `string` | Path of the GeoLite2 ASN database file.
Ignored when `IA_MAXMIND_LICENSE_KEY` is set. |
| `IA_COUNTRY_DATABASE` | `string` | Path of the GeoLite2 Country database file.
Ignored when `IA_MAXMIND_LICENSE_KEY` is set. |
| `IA_TIMEZONE` | `string` | Timezone to use in the dashboard. ([php docs](https://www.php.net/manual/en/timezones.php)) |
| `IA_SYSTEM_LOG_TIMEZONE` | `string` | Timezone of fail2ban logs. Required when using the docker image.
Use the timezone of the host system. |
| `IA_VERBOSE` | `boolean` | Enable additional logging for debugging. |
| `IA_DASH_CHARTS` | `boolean` | Enable/disable dashboard charts.
(optional, charts are enabled by default) |
| `IA_DASH_UPDATES` | `boolean` | Enable/disable automatically updating the dashboard with new events. (optional, updates are enabled by default) |
| `IA_DASH_DAEMON_LOG` | `boolean` | Enable/disable displaying daemon log in the dashboard.
(optional, log viewer is enabled by default) |
| `IA_DASH_DEFAULT_CHART` | `string` | Override default chart displayed in the dashboard. Optional.
Supported values: `24hours`, `48hours`, `14days`, `30days` |
| `IA_DASH_PAGE_SIZE` | `int` | Override default table page size in the dashboard. Optional.
Supported values: `25`, `50`, `100`, `200`, `500` |
### GeoLite2 databases
GeoLite2 databases will be automatically downloaded and updated if a [MaxMind license key](https://support.maxmind.com/hc/en-us/articles/4407111582235-Generate-a-License-Key) is set with `IA_MAXMIND_LICENSE_KEY`.
Alternatively, the databases can be manually [downloaded](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en) and set using the environment variables `IA_ASN_DATABASE` and `IA_COUNTRY_DATABASE`.
## Development
Clone the repository.
```
git clone https://github.com/VerifiedJoseph/intruder-alert
```
Install PHP dependencies with composer.
```
composer install
```
Install JavaScript dependencies with npm.
```
npm install
```
Start [esbuild](https://esbuild.github.io/) watcher
```
npm run watch
```
### Commands
Show/hide commands
Lint code:
```
composer lint
npm run lint
```
Fix code:
```
composer fix
npm run fix
```
Build code:
```
npm run build
```
Live code build:
```
npm run watch
```
Test code:
```
composer test
```
## Dependencies
- PHP
- [`geoip2/geoip2`](https://github.com/maxmind/GeoIP2-php)
- JavaScript
- [Chart.js](https://github.com/chartjs/Chart.js/)
- [Spacetime](https://github.com/spencermountain/spacetime)
## Requirements
- PHP >= 8.3
- Composer
- Node.js >= 22.0 (development only)
## Changelog
All notable changes to this project are documented in the [CHANGELOG](CHANGELOG.md).
## License
MIT License. Please see [LICENSE](LICENSE) for more information.