This commit is contained in:
Nathan Price 2025-01-12 23:17:24 -05:00
parent 6b1770832b
commit 70b34922b9
Signed by: gravityfargo
SSH key fingerprint: SHA256:bjq+uA1U+9bFMd70q2wdNtwaYxGv84IBXalnYvZDKmg
5 changed files with 716 additions and 0 deletions

View file

@ -0,0 +1,25 @@
# fail2ban-manager
## Introduction
Source Code hosted on my [Forgejo instance](https://forgejo.gravityfargo.dev/gravityfargo/fail2ban-manager). Registration is enabled for the public with GitHub via Authentik.
Any issues and feature requests can be submitted to the [issue tracker](https://github.com/gravityfargo/fail2ban-manager) on GitHub.
## Working with Jails
## Plugins
### Enabling Plugins
### Plugin: Hetzner
[MAN Page](plugins/hetzner.md)
### Plugin: Cloudflare
[MAN Page](plugins/cloudflare.md)
### Plugin: Telegram
[MAN Page](plugins/telegram.md)

270
fail2ban-manager.md Normal file
View file

@ -0,0 +1,270 @@
# `fail2ban-manager`
**Usage**:
```console
$ fail2ban-manager [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--install-completion`: Install completion for the current shell.
- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
- `--help`: Show this message and exit.
**Commands**:
- `jail`: Configure Fail2ban jails.
- `config`: Configure fail2ban-manager's configuration.
- `plugin`: Configure fail2ban-manager's plugins.
## `fail2ban-manager jail`
Configure Fail2ban jails.
**Usage**:
```console
$ fail2ban-manager jail [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--help`: Show this message and exit.
**Commands**:
- `ls`: List all defined jails.
- `enable`: Enable a jail.
- `disable`: Disable a jail.
- `info`: Display information about a jail.
- `edit`: Edit the properties of a jail.
### `fail2ban-manager jail ls`
List all defined jails.
**Usage**:
```console
$ fail2ban-manager jail ls [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager jail enable`
Enable a jail.
**Usage**:
```console
$ fail2ban-manager jail enable [OPTIONS] NAME
```
**Arguments**:
- `NAME`: [required]
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager jail disable`
Disable a jail.
**Usage**:
```console
$ fail2ban-manager jail disable [OPTIONS] NAME
```
**Arguments**:
- `NAME`: [required]
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager jail info`
Display information about a jail.
**Usage**:
```console
$ fail2ban-manager jail info [OPTIONS] NAME
```
**Arguments**:
- `NAME`: [required]
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager jail edit`
Edit the properties of a jail.
**Usage**:
```console
$ fail2ban-manager jail edit [OPTIONS] NAME
```
**Arguments**:
- `NAME`: Name of the jail. [required]
**Options**:
- `--backend TEXT`: The backend used to get file modifications.
Options: .
- `--bantime-increment`: Enable searching previously banned IPs to increment the ban time.
- `--bantime-rndtime INTEGER`: Add random time (in seconds) to the calculated ban time.
- `--bantime-maxtime INTEGER`: Maximum ban time (in seconds) that can be reached.
- `--bantime-factor FLOAT`: Factor used for exponential growth of ban time.
- `--bantime-formula TEXT`: Custom formula for calculating the next ban time.
- `--bantime-multipliers TEXT`: Custom multipliers for calculating the next ban time (e.g., 1 5 30 60).
- `--bantime-overalljails`: Search for banned IPs across all jails (default: false).
- `--ignoreself`: Ignore local/own IP addresses (default: true).
- `--ignoreip TEXT`: List of IPs, CIDR masks, or DNS hosts to ignore.
Example: "127.0.0.1/8 ::1"
- `--ignorecommand TEXT`: Command to dynamically determine if an IP should be ignored.
- `--bantime TEXT`: Duration for which a host is banned (e.g., 10m, 1h).
- `--findtime TEXT`: Time window for counting failed attempts before a ban (e.g., 10m).
- `--maxretry INTEGER`: Number of failed attempts allowed before a ban is triggered.
- `--maxmatches INTEGER`: Maximum number of stored matches for actions (defaults to maxretry).
- `--protocol TEXT`: Protocol to be banned (default: tcp).
- `--port TEXT`: Ports to ban (e.g., 0:65535 to ban all ports).
- `--chain TEXT`: Specify the chain where jumps will be added for ban actions.
- `--usedns TEXT`: Behavior for DNS lookups (yes, warn, no, raw).
- `--logencoding TEXT`: Encoding of the log files (e.g., utf-8, ascii, auto).
- `--action TEXT`: Default action for banning.
EX: action\_, action_mw, action_mwl, action_xarf, action_cf_mwl, action_abuseipdb
multiple values can be specified.
`--action action_ --action action_mw`
- `--mta TEXT`: Mail Transfer Agent (e.g., sendmail).
- `--sender TEXT`: Sender email address for notifications.
- `--destemail TEXT`: Destination email address for notifications.
- `--fail2ban-agent TEXT`: User-agent format for Fail2Ban.
- `--delete TEXT`: Delete an option from the jail.
Example: `--delete bantime`
- `--help`: Show this message and exit.
## `fail2ban-manager config`
Configure fail2ban-manager's configuration.
**Usage**:
```console
$ fail2ban-manager config [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--help`: Show this message and exit.
**Commands**:
- `reset`: Copy default configurations from `*.conf`...
### `fail2ban-manager config reset`
Copy default configurations from `*.conf` to `*.local` and json files.
**Usage**:
```console
$ fail2ban-manager config reset [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager plugin`
Configure fail2ban-manager's plugins.
**Usage**:
```console
$ fail2ban-manager plugin [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--help`: Show this message and exit.
**Commands**:
- `ls`: List installed plugins.
- `enable`: Enable a plugin.
- `disable`: Disable a plugin.
### `fail2ban-manager plugin ls`
List installed plugins.
**Usage**:
```console
$ fail2ban-manager plugin ls [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager plugin enable`
Enable a plugin.
**Usage**:
```console
$ fail2ban-manager plugin enable [OPTIONS] PLUGIN_NAME
```
**Arguments**:
- `PLUGIN_NAME`: [required]
**Options**:
- `--help`: Show this message and exit.
### `fail2ban-manager plugin disable`
Disable a plugin.
**Usage**:
```console
$ fail2ban-manager plugin disable [OPTIONS] PLUGIN_NAME
```
**Arguments**:
- `PLUGIN_NAME`: [required]
**Options**:
- `--help`: Show this message and exit.

109
plugins/cloudflare.md Normal file
View file

@ -0,0 +1,109 @@
# `fail2ban-manager cloudflare`
**Usage**:
```console
$ fail2ban-manager cloudflare [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--help`: Show this message and exit.
**Commands**:
- `zones`: List configured zones
- `zone-info`: Show information about a zone.
- `create-zone`: Create a new zone in the database.
- `check-ip`: Check if an IP is banned based on rules...
- `ban`: Check if an IP is banned based on rules...
## `fail2ban-manager cloudflare zones`
List configured zones
**Usage**:
```console
$ fail2ban-manager cloudflare zones [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager cloudflare zone-info`
Show information about a zone.
This command will pull the rules from Cloudflare and update the database as well as display the rules in a table.
**Usage**:
```console
$ fail2ban-manager cloudflare zone-info [OPTIONS] ZONE_ID
```
**Arguments**:
- `ZONE_ID`: [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager cloudflare create-zone`
Create a new zone in the database.
**Usage**:
```console
$ fail2ban-manager cloudflare create-zone [OPTIONS] ZONE_ID NAME
```
**Arguments**:
- `ZONE_ID`: [required]
- `NAME`: [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager cloudflare check-ip`
Check if an IP is banned based on rules cached in the database.
**Usage**:
```console
$ fail2ban-manager cloudflare check-ip [OPTIONS] IP
```
**Arguments**:
- `IP`: IP Address to check [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager cloudflare ban`
Check if an IP is banned based on rules cached in the database.
**Usage**:
```console
$ fail2ban-manager cloudflare ban [OPTIONS] ZONE_ID IP
```
**Arguments**:
- `ZONE_ID`: [required]
- `IP`: IP Address to ban [required]
**Options**:
- `--help`: Show this message and exit.

172
plugins/hetzner.md Normal file
View file

@ -0,0 +1,172 @@
# `fail2ban-manager hetzner`
**Usage**:
```console
$ fail2ban-manager hetzner [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--help`: Show this message and exit.
**Commands**:
- `info`: Check the status of the Hetzner plugin.
- `update`: Update the configuration.
- `reset`: Reset the configuration to defaults.
- `token`: Set Hetzner API token.
- `firewall-info`: Pull the firewalls from the server.
- `whitelist`: Whitelist an IP address.
- `whitelist-cloudflare`: Whitelist Cloudflare IP addresses.
- `delete-rule`: Delete a firewall rule.
## `fail2ban-manager hetzner info`
Check the status of the Hetzner plugin.
**Usage**:
```console
$ fail2ban-manager hetzner info [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner update`
Update the configuration.
**Usage**:
```console
$ fail2ban-manager hetzner update [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner reset`
Reset the configuration to defaults.
**Usage**:
```console
$ fail2ban-manager hetzner reset [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner token`
Set Hetzner API token.
Warning: If token_str is specified, it will be save in plaintext in the database.
**Usage**:
```console
$ fail2ban-manager hetzner token [OPTIONS] [TOKEN_STR]
```
**Arguments**:
- `[TOKEN_STR]`: The Hetzner API token.
**Options**:
- `--use-env`: Use the `HETZNER_TOKEN` environment variable.
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner firewall-info`
Pull the firewalls from the server.
**Usage**:
```console
$ fail2ban-manager hetzner firewall-info [OPTIONS] FIREWALL_ID
```
**Arguments**:
- `FIREWALL_ID`: The ID of the firewall to pull from the server. [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner whitelist`
Whitelist an IP address.
## Examples
fail2ban-manager hetzner whitelist <FIREWALLID> --self
fail2ban-manager hetzner whitelist <FIREWALLID> <IP>
**Usage**:
```console
$ fail2ban-manager hetzner whitelist [OPTIONS] FIREWALL_ID [IP] [PORT]
```
**Arguments**:
- `FIREWALL_ID`: The ID of the firewall to pull from the server. [required]
- `[IP]`: An IP to whitelist.
- `[PORT]`: any, 443, 80-85 [default: any]
**Options**:
- `--self`: Whitelist the External IP of the current machine.
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner whitelist-cloudflare`
Whitelist Cloudflare IP addresses.
**Usage**:
```console
$ fail2ban-manager hetzner whitelist-cloudflare [OPTIONS] FIREWALL_ID [PORT]
```
**Arguments**:
- `FIREWALL_ID`: The ID of the firewall to pull from the server. [required]
- `[PORT]`: any, 443, 80-85 [default: 443]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager hetzner delete-rule`
Delete a firewall rule.
## Examples
fail2ban-manager hetzner delete-rule <FIREWALLID> "fail2ban-manager whitelist - <PORT>"
fail2ban-manager hetzner delete-rule <FIREWALLID> "fail2ban-manager cloudflare whitelist - <PORT>"
**Usage**:
```console
$ fail2ban-manager hetzner delete-rule [OPTIONS] FIREWALL_ID DESCRIPTION
```
**Arguments**:
- `FIREWALL_ID`: The ID of the firewall to pull from the server. [required]
- `DESCRIPTION`: The description of the rule to delete. [required]
**Options**:
- `--help`: Show this message and exit.

140
plugins/telegram.md Normal file
View file

@ -0,0 +1,140 @@
# `fail2ban-manager telegram`
**Usage**:
```console
$ fail2ban-manager telegram [OPTIONS] COMMAND [ARGS]...
```
**Options**:
- `--install-completion`: Install completion for the current shell.
- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
- `--help`: Show this message and exit.
**Commands**:
- `ls`: List all jails with Telegram notifications.
- `add-to-jail`: Add the Telegram provider to a jail.
- `remove-from-jail`: Remove the Telegram provider from a jail.
- `edit-message`: Set the message for a specific action.
- `enable-message`: Enable a message for a specific action in...
- `send`: Send a messague to a Telegram bot.
## `fail2ban-manager telegram ls`
List all jails with Telegram notifications.
**Usage**:
```console
$ fail2ban-manager telegram ls [OPTIONS]
```
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager telegram add-to-jail`
Add the Telegram provider to a jail.
**Usage**:
```console
$ fail2ban-manager telegram add-to-jail [OPTIONS] JAILNAME TOKEN CHATID
```
**Arguments**:
- `JAILNAME`: [required]
- `TOKEN`: [env var: TELEGRAM_API_TOKEN; required]
- `CHATID`: [env var: TELEGRAM_CHAT_ID; required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager telegram remove-from-jail`
Remove the Telegram provider from a jail.
**Usage**:
```console
$ fail2ban-manager telegram remove-from-jail [OPTIONS] JAILNAME
```
**Arguments**:
- `JAILNAME`: [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager telegram edit-message`
Set the message for a specific action.
**Usage**:
```console
$ fail2ban-manager telegram edit-message [OPTIONS] JAILNAME ACTION MESSAGE
```
**Arguments**:
- `JAILNAME`: [required]
- `ACTION`: The action to send a message for. [required]
- `MESSAGE`: The action to send. [required]
**Options**:
- `--help`: Show this message and exit.
## `fail2ban-manager telegram enable-message`
Enable a message for a specific action in a jail.
**Usage**:
```console
$ fail2ban-manager telegram enable-message [OPTIONS] JAILNAME
```
**Arguments**:
- `JAILNAME`: [required]
**Options**:
- `--start`: Enable message for start action.
- `--stop`: Enable message for stop action.
- `--check`: Enable message for check action.
- `--ban`: Enable message for ban action.
- `--unban`: Enable message for unban action.
- `--help`: Show this message and exit.
## `fail2ban-manager telegram send`
Send a messague to a Telegram bot.
**Usage**:
```console
$ fail2ban-manager telegram send [OPTIONS] ACTION JAILNAME [TOKEN] [CHATID]
```
**Arguments**:
- `ACTION`: The action to send a message for. [required]
- `JAILNAME`: Name of the jail sending the message [required]
- `[TOKEN]`: [env var: TELEGRAM_API_TOKEN]
- `[CHATID]`: [env var: TELEGRAM_CHAT_ID]
**Options**:
- `--ip TEXT`: IP address of the banned/unbanned IP
- `--failures INTEGER`: Number of failures before ban [default: 0]
- `--help`: Show this message and exit.