Skip to content
This repository has been archived by the owner on Sep 6, 2023. It is now read-only.

esoadamo/simple-guardian

Repository files navigation

Simple guardian

Easy alternative to Fail2ban

Build to be fast to deploy (deploying SG and making your server secure against OpenSSH, VSFTPD and Dovecot attacks takes under 6 seconds when using Simple Guardian Server) and easy to configure (uses JSON formatted dictionaries as profiles, no regex-skills needed).

How it works

SG loads informations from enabled applications profiles and then checks their log files for known attack lines' patterns. If enough attacks from one IP is found, SG banns the IP using iptables and prevents further attacks. All that without writing single regular expression.

You can also use the mighty and powerful web interface, which add remote control functionality, as well as managing multiple servers from one page and also provides the hub with many applications profiles shared by users, which can be sent to your server in just two clicks.

Instalation

on Debian-based systems

If you are running a Debian-based OS (like Debian or Ubuntu), you can use SG's official repository and get also automatic updates.

# first make sure that you have root rights
sudo ls
# then import the repository key
wget -O - https://deb.adamhlavacek.com/pub.gpg | sudo apt-key add -
# then add the repository to your system
echo "deb https://deb.adamhlavacek.com ./" | sudo tee -a /etc/apt/sources.list
# update
sudo apt update
# install
sudo apt install simple-guardian 

on generic Linux

# clone the repository
git clone https://github.com/esoadamo/simple-guardian
cd simple-guardian

# execute the installer
chmod +x install.py
sudo ./install.py

Configuration

All configuration is saved in folder data.

Main configuration

--- config.json ---
{
 "scanTime": 30,  -- how often to check for new attacks
  "updater": {  -- informations about sources for the autoupdater
    "githubOwner": "esoadamo",
    "githubRepo": "simple-guardian",
    "autoupdate": false -- if set to true, updates itself everytime a new version is released
  },
 "defaults": { -- valid for are profiles if not overridden
  "scanRange": 600,  -- what is the max delay between to attack from one IP to count them as connected
   "maxAttempts": 5 -- maximum number of attacks in scan range time after which is the IP blocked from the server
 }
}

Online data

File server.json holds login informations gathered from the server when client has logged this device to some online account.

Profiles

Every file in data/profiles can have one or more profiles. Profiles have a specific (JSON) format.

The attacks are parsed from log files using filters defined in their profiles. The filters are lines from the log file, where are variables are replaced with their names. The variable is defined as %VARIABLE_NAME%. There are some reserved variables which are listed below and the parser uses them as sources of its data.

Profile default.json comes prebundled from the GitHub repository with most basic profiles and online.json is generated by the web interface.

Example profile

{
  "debug": {
    "logFile": "debug.log",  -- path to the file with log lines
    "filters": [  -- list of the filter lines
      "%D:M% %D:D% %TIME% %IP% attacked on user %USER%"  -- example line: Aug 10 16:52:08 1.2.3.4 attacked on user myUser6
    ]
  },
  "secondProfile": {...}
}

Reserved variables

These variables are recognized and used by the parser itself:

Variable name Represenataion
USER the user that was target of attack
IP the IP from where the attack has come
TIME time of attack in format HH:MM:SS
D:M month of attack - eg. Jan, Feb,...
D:D the day of month the attack has occurred - from 1 to 31

simple-guardian-client

recognized commands:

command action must be runned as root
help prints help n
-V/version print current version of the simple guardian n
login loginKey logs in with user using loginKey and assigns this instance to the online account and server Y
uninstall completely wipes simple guardian from the disc Y
update updates s-g to the latest version from GitHub releases Y
update-master updates s-g to the latest version from GitHub master branch Y
unblock unblocks IP blocked by s-g Y

Looking for legacy version?

There was also an old version, outdated now, on which is this software based. You can find it here