Merge branch '4-create-a-list-route-for-showing-banned-addresses' into 'develop'

Resolve "Create a /list route for showing banned addresses"

See merge request ruben/jail2ban-pf!7

.gitignore

@@ -1,5 +1,7 @@
 venv/
 
+*.sw?
+
 *.pyc
 __pycache__/
 
@@ -12,3 +14,6 @@ htmlcov/
 dist/
 build/
 *.egg-info/
+
+coverage.xml
+report.xml

.gitlab-ci.yml

@@ -1,6 +1,6 @@
 run tests:
   stage: test
-  image: python:3.8
+  image: python:3.9
   script:
     - pip install pytest pytest-cov pytest-mock pytest-flask
     - pip install Flask-HTTPAuth
@@ -11,7 +11,9 @@ run tests:
   artifacts:
     when: always
     reports:
-      cobertura: coverage.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
       junit: report.xml
   tags:
     - docker

.pylintrc

@@ -0,0 +1,2 @@
+[TYPECHECK]
+generated-members=app.logger.*

CHANGELOG

@@ -0,0 +1,3 @@
+- 2023.1
+
+* Implement #3, a /ping health check endpoint

README.md

@@ -1,3 +1,130 @@
 [![pipeline status](https://gitlab.niet.verweg.com/ruben/jail2ban-pf/badges/main/pipeline.svg)](https://gitlab.niet.verweg.com/ruben/jail2ban-pf/-/commits/main)
 [![coverage report](https://gitlab.niet.verweg.com/ruben/jail2ban-pf/badges/main/coverage.svg)](https://gitlab.niet.verweg.com/ruben/jail2ban-pf/-/commits/main)
 
+
+## Installation
+
+
+* Install uwsgi 
+
+```
+sudo pkg install www/uwsgi
+```
+
+* Clone this repository
+
+## Configuration
+
+### rc.conf
+
+* Use the following for configuring uwsgi in rc.conf
+
+```
+sudo sysrc uwsgi\_enable="YES"
+sudo sysrc uwsgi\_profiles="jail2ban\_pf"
+sudo sysrc uwsgi\_jail2ban\_pf\_flags="-L -M --uid \_jail2ban --python-path /opt/jail2ban-pf --wsgi-file /opt/jail2ban-pf/wsgi.py --stats 127.0.0.1:9191 --socket 127.0.0.1:3031 --chdir /var/empty --callable app --manage-script-name"
+```
+
+### jail2ban
+
+* Configure <installation root>/instance/config.py
+
+```
+SECRET\_KEY = os.urandom(32).hex()
+AUTHFILE = '/usr/local/etc/jail2ban-pf-users.txt'
+```
+
+### nginx
+
+* Configure a nginx upstream and vhost
+
+_Of course you can listen on ipv4/ipv6 but you want to protect these addresses from inadvertent or malicious probes_
+
+    upstream uwsgi_pf_jail2ban {
+        server 127.0.0.1:3031;
+    }
+
+    server {
+        listen       unix:/path/to/jail_1/var/run/pf2ban/pf_jail2ban.sock;
+        listen       unix:/path/to/jail_2/var/run/pf2ban/pf_jail2ban.sock;
+        listen       unix:/path/to/jail_3/var/run/pf2ban/pf_jail2ban.sock;
+        server_name  _;
+
+        location / {
+            index     index.html index.htm index.php;
+            allow all;
+            include /usr/local/etc/nginx/uwsgi_params-dist;
+            uwsgi_pass uwsgi_pf_jail2ban;
+        }
+    }
+
+### /etc/pf.conf
+
+* Place anchors in pf for jail2ban to use. You probably want to place the early in your existing pf configuration
+
+```
+anchor "f2b/*"
+anchor f2b-jail {
+    anchor "jail1_fqdn" to { <addr_jail1>, <addr_extra_jail1>, <addr_extra6_jail1> }
+    anchor "jail2_fqdn" to { <addr_jail2>, <addr_extra_jail2>, <addr_extra6_jail2> }
+    anchor "jail3_fqdn" to { <addr_jail3>, <addr_extra_jail3>, <addr_extra6_jail3> }
+}
+```
+
+Having seperate anchors per jail makes it possible to have fine grained
+blocking: Something that is harmful to jail2 might be perfectly legit for jail2.
+
+#### Checking rules/tables made with fail2ban/jail2ban
+Fail2ban will (re)create the per anchor rules on startup, and populate the designated address tables with offenders, e.g.:
+
+    sudo pfctl -a f2b-jail/jail1\_fqdn -T show -t f2b-recidive
+    192.0.2.66
+    2001:db8:abad:cafe:0bad:f00d
+
+And the rules referencing these tables
+
+    sudo pfctl -a 'f2b-jail/jail1\_fqdn' -s rules
+    block drop quick proto tcp from <f2b-dovecot> to any port = pop3
+    block drop quick proto tcp from <f2b-dovecot> to any port = pop3s
+    block drop quick proto tcp from <f2b-dovecot> to any port = imap
+    block drop quick proto tcp from <f2b-dovecot> to any port = imaps
+    block drop quick proto tcp from <f2b-dovecot> to any port = submission
+    block drop quick proto tcp from <f2b-dovecot> to any port = smtps
+    block drop quick proto tcp from <f2b-dovecot> to any port = sieve
+    block drop quick proto tcp from <f2b-sendmail-auth> to any port = submission
+    block drop quick proto tcp from <f2b-sendmail-auth> to any port = smtps
+    block drop quick proto tcp from <f2b-sendmail-auth> to any port = smtp
+    block drop quick proto tcp from <f2b-sshd> to any port = ssh
+    block drop quick proto tcp from <f2b-recidive> to any
+    
+### fail2ban
+
+* Create the following action plugin for fail2ban on the jail desiring to use fail2ban/jail2ban
+
+```
+cat <<'EOT' | tee /usr/local/etc/fail2ban/action.d/jail2ban-pf.conf > /dev/null
+Definition]
+actionstart = curl --unix-socket <jail2ban_sock> --basic -u '<jail2ban_user>:<jail2ban_pass>' -XPUT -H 'Content-Type: application/json' -d '{"port":"<actiontype>","name":"<name>","protocol":"<protocol>"}' http://localhost/register
+actionstart_on_demand = false
+actionstop = curl --unix-socket <jail2ban_sock> --basic -u '<jail2ban_user>:<jail2ban_pass>' -XDELETE -H 'Content-Type: application/json' -d '{"port":"<actiontype>","name":"<name>","protocol":"<protocol>"}' http://localhost/register
+actionflush = curl --unix-socket <jail2ban_sock> --basic -u '<jail2ban_user>:<jail2ban_pass>' -X GET http://localhost/flush/<name>
+actioncheck = 
+actionban = curl --unix-socket <jail2ban_sock> --basic -u '<jail2ban_user>:<jail2ban_pass>' -X PUT -H 'Content-Type: application/json' -d '{"name":"<name>","ip":"<ip>"}' http://localhost/ban
+actionunban = curl --unix-socket <jail2ban_sock> --basic -u '<jail2ban_user>:<jail2ban_pass>' -X DELETE -H 'Content-Type: application/json' -d '{"name":"<name>","ip":"<ip>"}' http://localhost/ban
+[Init]
+protocol = tcp
+actiontype = <multiport>
+allports = any
+multiport = any port {<port>}
+jail2ban_sock = /var/run/pf2ban/jail2ban.sock
+jail2ban_user = login as set in password file for jail2ban
+jail2ban_pass = password as set in password file for jail2ban
+```
+
+* Configure jail.local
+
+```
+cat <<'EOT' | tee /usr/local/etc/fail2ban/jail.local > /dev/null
+[DEFAULT]
+banaction = jail2ban-pf
+```

jail2ban/__init__.py

@@ -1,11 +1,16 @@
+'''
+jail2ban, a remote fail2ban action plugin using OpenBSD pf(8)
+'''
+from ipaddress import ip_address
+import re
+from subprocess import CalledProcessError
+
 from flask import Flask, request, jsonify, current_app
 from flask_httpauth import HTTPBasicAuth
 from werkzeug.security import check_password_hash
-from ipaddress import ip_address
-import re
+
 from jail2ban.pfctl import pfctl_table_op, pfctl_cfg_read, pfctl_cfg_write
 from jail2ban.auth import get_users
-from subprocess import CalledProcessError
 
 
 auth = HTTPBasicAuth()
@@ -15,6 +20,13 @@ PAT_PORT = r'^any(?:\s+port\s+{\w+(?:,\w+)*})?$'
 PAT_PROT = r'^(?:tcp|udp)$'
 PAT_NAME = r'^[\w\-]+$'
 
+_PFCTL_TABLE_PAT = r'''\s+(?P<addr>\S+)\n
+\s+Cleared:\s+(?P<date>\S+\s+\S+\s+\d+\s+(?:\d{2}:){2}\d{2}\s+\d{4})\n
+\s+In/Block:\s+\[\s+Packets:\s+(?P<in_pckt_block>\d+)\s+Bytes:\s+(?P<in_bytes_block>\d+)\s+\]\n
+\s+In/Pass:\s+\[\s+Packets:\s+(?P<in_pckt_pass>\d+)\s+Bytes:\s+(?P<in_bytes_pass>\d+)\s+\]\n
+\s+Out/Block:\s+\[\s+Packets:\s+(?P<out_pckt_block>\d+)\s+Bytes:\s+(?P<out_bytes_block>\d+)\s+\]\n
+\s+Out/Pass:\s+\[\s+Packets:\s+(?P<out_pckt_pass>\d+)\s+Bytes:\s+(?P<out_bytes_pass>\d+)\s+\]'''
+
 
 def untaint(pattern, string):
     '''
@@ -23,11 +35,13 @@ def untaint(pattern, string):
     match = re.match(pattern, string)
     if match:
         return match.string
-    else:
-        raise ValueError(f'"{string}" is tainted')
+    raise ValueError(f'"{string}" is tainted')
 
 
 def create_app():
+    '''
+    Create wsgi application instance
+    '''
     app = Flask(__name__, instance_relative_config=True)
 
     # load the instance config, if it exists, when not testing
@@ -41,7 +55,17 @@ def create_app():
         if username in users and \
                 check_password_hash(users.get(username), password):
             return username
+        return None
 
+    @app.route("/ping", methods=['GET'])
+    @auth.login_required
+    def ping():
+        remote_user = auth.username()
+        app.logger.info('Received ping for'
+                        f' anchor f2b-jail/{remote_user}')
+        return jsonify({'anchor': f'f2b-jail/{remote_user}',
+                        'operation': 'ping',
+                        'result': 'pong'})
     @app.route("/flush/<name>", methods=['GET'])
     @auth.login_required
     def flush(name):
@@ -57,6 +81,36 @@ def create_app():
                         'operation': 'flush',
                         'result': [x.decode('ascii') for x in res]})
 
+    @app.route("/list/<name>", methods=['GET'])
+    @auth.login_required
+    def list_table(name):
+        remote_user = auth.username()
+        name = untaint(PAT_NAME, name)
+        app.logger.info(f'Flushing table f2b-{name}'
+                        f' in anchor f2b-jail/{remote_user}')
+        reply = {'anchor': f'f2b-jail/{remote_user}',
+                        'table': f'f2b-{name}',
+                        'operation': 'list'}
+        try:
+            res = pfctl_table_op('f2b-jail/{remote_user}',
+                                 table='f2b-{name}',
+                                 operation='show',
+                                 verbose=True)
+        except CalledProcessError as err:
+            if err.stderr.find(b'pfctl: Table does not exist.') > 0:
+                res = []
+                reply.update({'error': f'\'{name}\' is not a known fail2ban jail'})
+            else:
+                raise err
+
+        result = [entry.groupdict() for entry in
+                  re.finditer(_PFCTL_TABLE_PAT,
+                              '\n'.join([x.decode('ascii') for x in res]),
+                              re.MULTILINE|re.VERBOSE)]
+        reply.update({'result': result})
+
+        return jsonify(reply), 200 if len(res) else 404
+
     @app.route("/register", methods=['PUT', 'DELETE'])
     @auth.login_required
     def register():
@@ -102,21 +156,21 @@ def create_app():
         data = request.get_json()
         # name / ip
         name = untaint(PAT_NAME, data['name'])
-        ip = ip_address(data['ip'])
+        ip_addr = ip_address(data['ip'])
         if request.method == 'PUT':
-            app.logger.info(f'Add {ip} to f2b-{name}'
+            app.logger.info(f'Add {ip_addr} to f2b-{name}'
                             f' in anchor f2b-jail/{remote_user}')
             res = pfctl_table_op(f'f2b-jail/{remote_user}',
                                  table=f'f2b-{name}',
                                  operation='add',
-                                 value=str(ip))
+                                 value=str(ip_addr))
         else:  # 'DELETE':
-            app.logger.info(f'Remove {ip} from f2b-{name}'
+            app.logger.info(f'Remove {ip_addr} from f2b-{name}'
                             f' in anchor f2b-jail/{remote_user}')
             res = pfctl_table_op(f'f2b-jail/{remote_user}',
                                  table=f'f2b-{name}',
                                  operation='delete',
-                                 value=str(ip))
+                                 value=str(ip_addr))
         return jsonify({'anchor': f'f2b-jail/{remote_user}',
                         'table': f'f2b-{name}',
                         'operation': 'add' if request.method == 'PUT'
@@ -137,6 +191,8 @@ def create_app():
         Show a json parsable error if the value is illegal
         '''
         app.logger.fatal(error)
+        app.logger.fatal('stdout: %s', error.stderr)
+        app.logger.fatal('stderr: %s', error.stderr)
         return jsonify({'error': str(error)}), 500
 
     @app.errorhandler(FileNotFoundError)

jail2ban/pfctl.py

@@ -1,11 +1,16 @@
+'''
+Lowlevel routines for calling the pf binary with passwordless sudo
+'''
 import logging
 from subprocess import run
 
 _SUDO = '/usr/local/bin/sudo'
 _PFCTL = '/sbin/pfctl'
 
-
 def pfctl_cfg_read(anchor):
+    '''
+    Read pf rules stored under a certain anchor
+    '''
     cmd = [_SUDO, _PFCTL, '-a', anchor, '-sr']
     logging.info('Running %s', cmd)
 
@@ -16,6 +21,9 @@ def pfctl_cfg_read(anchor):
 
 
 def pfctl_cfg_write(anchor, cfg):
+    '''
+    Write pf rules under a certain anchor
+    '''
     cmd = [_SUDO, _PFCTL, '-a', anchor, '-f-']
     logging.info('Running %s', cmd)
     logging.info('Config %s', cfg)
@@ -30,10 +38,14 @@ def pfctl_cfg_write(anchor, cfg):
 
 
 def pfctl_table_op(anchor, **kwargs):
+    '''
+    pf table operation
+    '''
     table = kwargs['table']
     operation = kwargs['operation']
     value = kwargs['value'] if 'value' in kwargs else None
-    cmd = [_SUDO, _PFCTL, '-a', anchor, '-t', table, '-T', operation, value]
+    verbose =  '-v' if 'verbose' in kwargs and kwargs['verbose'] else None
+    cmd = [_SUDO, _PFCTL, '-a', anchor, '-t', table, verbose, '-T', operation, value]
 
     logging.info('Running %s', cmd)
 

tests/test_list.py

@@ -0,0 +1,140 @@
+'''
+Tests for /list route
+'''
+from types import SimpleNamespace
+from subprocess import CalledProcessError
+
+
+_PF_TABLE_LIST = b'''   192.0.2.66
+        Cleared:     Sat Jan  7 12:50:36 2023
+        In/Block:    [ Packets: 0                  Bytes: 0                  ]
+        In/Pass:     [ Packets: 0                  Bytes: 0                  ]
+        Out/Block:   [ Packets: 0                  Bytes: 0                  ]
+        Out/Pass:    [ Packets: 0                  Bytes: 0                  ]
+   2001:db8::abad:cafe
+        Cleared:     Sat Jan  7 05:13:53 2023
+        In/Block:    [ Packets: 4                  Bytes: 240                ]
+        In/Pass:     [ Packets: 0                  Bytes: 0                  ]
+        Out/Block:   [ Packets: 0                  Bytes: 0                  ]
+        Out/Pass:    [ Packets: 0                  Bytes: 0                  ]
+   2001:db8::abad:f00d:cafe
+        Cleared:     Sat Jan  7 05:05:16 2023
+        In/Block:    [ Packets: 48                 Bytes: 2880               ]
+        In/Pass:     [ Packets: 0                  Bytes: 0                  ]
+        Out/Block:   [ Packets: 0                  Bytes: 0                  ]
+        Out/Pass:    [ Packets: 0                  Bytes: 0                  ]'''
+
+_LIST_RESULT = [{'addr': '192.0.2.66',
+  'date': 'Sat Jan  7 12:50:36 2023',
+  'in_pckt_block': '0',
+  'in_bytes_block': '0',
+  'in_pckt_pass': '0',
+  'in_bytes_pass': '0',
+  'out_pckt_block': '0',
+  'out_bytes_block': '0',
+  'out_pckt_pass': '0',
+  'out_bytes_pass': '0'},
+ {'addr': '2001:db8::abad:cafe',
+  'date': 'Sat Jan  7 05:13:53 2023',
+  'in_pckt_block': '4',
+  'in_bytes_block': '240',
+  'in_pckt_pass': '0',
+  'in_bytes_pass': '0',
+  'out_pckt_block': '0',
+  'out_bytes_block': '0',
+  'out_pckt_pass': '0',
+  'out_bytes_pass': '0'},
+ {'addr': '2001:db8::abad:f00d:cafe',
+  'date': 'Sat Jan  7 05:05:16 2023',
+  'in_pckt_block': '48',
+  'in_bytes_block': '2880',
+  'in_pckt_pass': '0',
+  'in_bytes_pass': '0',
+  'out_pckt_block': '0',
+  'out_bytes_block': '0',
+  'out_pckt_pass': '0',
+  'out_bytes_pass': '0'}]
+
+
+def test_list_single_table(client, mocker, valid_credentials):
+    '''
+    List a single pf table using the fail2ban jail name
+    '''
+
+    def noop():
+        pass
+
+    run_res = SimpleNamespace()
+    run_res.stdout = _PF_TABLE_LIST
+    run_res.stderr = b'No ALTQ support in kernel\nALTQ related functions disabled\n'
+    run_res.returncode = 0
+    run_res.check_returncode = noop
+
+    mocker.patch('jail2ban.pfctl.run', return_value=run_res)
+
+    response = client.get("/list/sshd",
+                          headers={"Authorization":
+                                   "Basic " + valid_credentials})
+
+    assert response.json['table'] == 'f2b-sshd'
+    assert response.json['result'] == _LIST_RESULT
+
+
+def test_list_nonexistent_table(client, mocker, valid_credentials):
+    '''
+    Test for nonexistent table. Should result in a 404 not found
+    '''
+    def noop():
+        pass
+
+    run_res = SimpleNamespace()
+    run_res.stdout = b''
+    run_res.stderr = b'No ALTQ support in kernel\nALTQ related functions disabled\n' \
+                     b'pfctl: Table does not exist.\n'
+    run_res.returncode = 255
+    run_res.check_returncode = noop
+
+    mocker.patch('jail2ban.pfctl.run',
+                 return_value=run_res,
+                 side_effect=CalledProcessError(run_res.returncode,
+                                                'foobar',
+                                                 output=run_res.stdout,
+                                                 stderr=run_res.stderr)
+                 )
+
+    response = client.get("/list/nonexistent",
+                          headers={"Authorization":
+                                   "Basic " + valid_credentials})
+
+    assert response.status_code == 404
+    assert response.json['error'] == "'nonexistent' is not " \
+                                     "a known fail2ban jail"
+
+def test_list_wrong_table_name(client, mocker, valid_credentials):
+    '''
+    Test for an wrong table name that lets pfctl fail. should result in a 500
+    '''
+    def noop():
+        pass
+
+    run_res = SimpleNamespace()
+    run_res.stdout = b''
+    run_res.stderr = b'No ALTQ support in kernel\nALTQ related functions disabled\n' \
+            b'pfctl: Invalid argument.\n'
+    run_res.returncode = 255
+    run_res.check_returncode = noop
+
+    mocker.patch('jail2ban.pfctl.run',
+                 return_value=run_res,
+                 side_effect=CalledProcessError(run_res.returncode,
+                                                'foobar',
+                                                 output=run_res.stdout,
+                                                 stderr=run_res.stderr)
+                 )
+
+    response = client.get("/list/notanerrorbuttestneedstofail",
+                          headers={"Authorization":
+                                   "Basic " + valid_credentials})
+
+    assert response.status_code == 500
+    assert response.json['error'] == "Command 'foobar' returned non-zero exit status 255."

tests/test_ping.py

@@ -0,0 +1,10 @@
+def test_ping(client, mocker, valid_credentials):
+    '''
+    Test application health check
+    '''
+
+    response = client.get("/ping",
+                          headers={"Authorization":
+                                   "Basic " + valid_credentials})
+
+    assert response.json['operation'] == 'ping'

wsgi.py

@@ -0,0 +1,3 @@
+from jail2ban import create_app
+
+app = create_app()