diff --git a/README.md b/README.md index e69de29..e3803bd 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/fail2ban-manager.md b/fail2ban-manager.md new file mode 100644 index 0000000..454e02b --- /dev/null +++ b/fail2ban-manager.md @@ -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. diff --git a/plugins/cloudflare.md b/plugins/cloudflare.md new file mode 100644 index 0000000..1069ecc --- /dev/null +++ b/plugins/cloudflare.md @@ -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. diff --git a/plugins/hetzner.md b/plugins/hetzner.md new file mode 100644 index 0000000..687eb21 --- /dev/null +++ b/plugins/hetzner.md @@ -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. diff --git a/plugins/telegram.md b/plugins/telegram.md new file mode 100644 index 0000000..9d060b2 --- /dev/null +++ b/plugins/telegram.md @@ -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.