https://github.com/meinside/balog
Fail2ban's ban action logger
https://github.com/meinside/balog
cli fail2ban golang
Last synced: 4 months ago
JSON representation
Fail2ban's ban action logger
- Host: GitHub
- URL: https://github.com/meinside/balog
- Owner: meinside
- Created: 2022-02-03T09:07:14.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2025-04-25T04:30:30.000Z (6 months ago)
- Last Synced: 2025-04-25T05:31:24.634Z (6 months ago)
- Topics: cli, fail2ban, golang
- Language: Go
- Homepage:
- Size: 136 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# balog = Ban Action Logger
## What is it?
A logger for [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page)'s ban actions.
## What does it do?
Logs ban actions with ip addresses, and if possible, fetch their geolocations from [ipgeolocation.io](https://ipgeolocation.io/).
Also generates reports in various formats, including: plain text, json, and [telegra.ph](https://telegra.ph/).
## Installation and configuration
```bash
$ go install github.com/meinside/balog@latest
```
On the first run, it will create a default configuration file `~/.config/balog/config.json`:
```json
{
"db_filepath": "/your/home/.config/balog/database.db"
}
```
### Telegraph Access Token
For posting reports to telegra.ph, set your telegraph access token like this:
```json
{
"db_filepath": "/path/to/database.db",
"telegraph_access_token": "1234567890abcdefghijklmnopqrstuvwxyz"
}
```
### ipgeolocaiton.io API Key
For fetching geolocations of banned IP addresses, set your [ipgeolocation.io](https://ipgeolocation.io/) API key like this:
```json
{
"db_filepath": "/path/to/database.db",
"ipgeolocation_api_key": "abcdefghijk1234567890"
}
```
If `ipgeolocation_api_key` is not set, locations will be saved as `Unknown`.
### Google AI API Key
For generating insights on logs with generative AI models, set [your Google AI API key](https://aistudio.google.com/app/apikey) like this:
```json
{
"db_filepath": "/path/to/database.db",
"google_ai_api_key": "abcdefghijklmnopqrstuvwxyz0123456789"
}
```
then it will try to generate some insights on the logs and append them to the report.
### Using Infisical
You can also use [Infisical](https://infisical.com/) for retrieving your access token and api key:
```json
{
"db_filepath": "/path/to/database.db",
"infisical": {
"client_id": "012345-abcdefg-987654321",
"client_secret": "aAbBcCdDeEfFgG0123456789xyzwXYZW",
"project_id": "012345abcdefg",
"environment": "dev",
"secret_type": "shared",
"telegraph_access_token_key_path": "/path/to/your/KEY_TO_TELEGRAPH_ACCESS_TOKEN",
"ipgeolocation_api_key_key_path": "/path/to/your/KEY_TO_IPGEOLOCATION_API_KEY",
"google_ai_api_key_key_path": "/path/to/your/KEY_TO_GOOGLE_AI_API_KEY"
}
}
```
## Usage
Run with `-h` to see the usage:
```bash
$ balog -h
```
### Logging
It can be run from the shell directly:
```bash
$ balog -action save -ip 8.8.8.8 -protocol ssh
```
or it can be called from fail2ban's ban action.
#### Fail2ban Configuration
Duplicate `iptables-multiport.conf` to `iptables-multiport-balog.conf`:
```bash
$ sudo cp /etc/fail2ban/action.d/iptables-multiport.conf /etc/fail2ban/action.d/iptables-multiport-balog.conf
```
then append 3 lines below the `actionban` in that file:
```
# /etc/fail2ban/action.d/iptables-multiport-balog.conf
# from original
#actionban = -I f2b- 1 -s -j
# to this one
# ('' is checked for not saving duplicated ban actions on restarts of fail2ban)
actionban = -I f2b- 1 -s -j
if [ '' = '0' ]; then
/path/to/balog -config /path/to/balog.json -action save -ip -protocol
fi
```
Change `/path/to/balog` and `/path/to/balog.json` to yours,
(NOTE: fail2ban-generated config and database files will be owned by `root`)
and add custom ban actions in your `/etc/fail2ban/jail.local` file:
```
# ...
[DEFAULT]
# ...
# custom ban actions
banaction = iptables-multiport-balog
```
Finally, `sudo systemctl restart fail2ban.service` to apply changes.
### Reporting
```bash
# print report to stdout
$ balog -action report -format plain
# print report to stdout in json format
$ balog -action report -format json
# post report to telegra.ph and print the url to stdout
$ balog -action report -format telegraph
```
You can put the above commands in your crontab:
```crontab
0 0 * * 0 balog -action report -format plain > /tmp/report_weekly.txt
0 0 1 * * balog -action report -format plain > /tmp/report_monthly.txt
```
### Maintenance
```bash
# list unknown ips
$ balog -action maintenance -job list_unknown_ips
# resolve unknown ips through ipgeolocation.io
$ balog -action maintenance -job resolve_unknown_ips
# purge logs
$ balog -action maintenance -job purge_logs
```
## License
MIT