Home | History | Annotate | Line # | Download | only in blocklist 
      1 # $NetBSD: README,v 1.3 2024/02/09 00:53:30 wiz Exp $
      2 
      3 This package contains library that can be used by network daemons to
      4 communicate with a packet filter via a daemon to enforce opening and
      5 closing ports dynamically based on policy.
      6 
      7 The interface to the packet filter is in libexec/blocklistd-helper
      8 (this is currently designed for npf) and the configuration file
      9 (inspired from inetd.conf) is in etc/blocklistd.conf.
     10 
     11 On NetBSD you can find an example npf.conf and blocklistd.conf in
     12 /usr/share/examples/blocklistd; you need to adjust the interface
     13 in npf.conf and copy both files to /etc; then you just enable
     14 blocklistd=YES in /etc/rc.conf, start it up, and you are all set.
     15 
     16 There is also a startup file in etc/rc.d/blocklistd
     17 
     18 Patches to various daemons to add blocklisting capabilities are in the
     19 "diff" directory:
     20     - OpenSSH: diff/ssh.diff [tcp socket example]
     21     - Bind: diff/named.diff [both tcp and udp]
     22     - ftpd: diff/ftpd.diff [tcp]
     23 
     24 These patches have been applied to NetBSD-current.
     25 
     26 The network daemon (for example sshd) communicates to blocklistd, via
     27 a Unix socket like syslog. The library calls are simple and everything
     28 is handled by the library. In the simplest form the only thing the
     29 daemon needs to do is to call:
     30 
     31 	blocklist(action, acceptedfd, message);
     32 
     33 Where:
     34 	action = 0 -> successful login clear blocklist state
     35 		 1 -> failed login, add to the failed count
     36 	acceptedfd -> the file descriptor where the server is
     37 		      connected to the remote client. It is used
     38 		      to determine the listening socket, and the
     39 		      remote address. This allows any program to
     40 		      contact the blocklist daemon, since the verification
     41 		      if the program has access to the listening
     42 		      socket is done by virtue that the port
     43 		      number is retrieved from the kernel.
     44 	message    -> an optional string that is used in debugging logs.
     45 
     46 Unfortunately there is no way to get information about the "peer"
     47 from a udp socket, because there is no connection and that information
     48 is kept with the server. In that case the daemon can provide the
     49 peer information to blocklistd via:
     50 
     51 	blocklist_sa(action, acceptedfd, sockaddr, sockaddr_len, message);
     52 
     53 The configuration file contains entries of the form:
     54 
     55 # Blocklist rule
     56 # host/Port	type	protocol	owner	name	nfail	disable
     57 192.168.1.1:ssh	stream	tcp		*	-int	10	1m
     58 8.8.8.8:ssh	stream	tcp		*	-ext	6	60m
     59 ssh		stream	tcp6		*	*	6	60m
     60 http		stream	tcp		*	*	6	60m
     61 
     62 Here note that owner is * because the connection is done from the
     63 child ssh socket which runs with user privs. We treat IPv4 connections
     64 differently by maintaining two different rules one for the external
     65 interface and one from the internal We also register for both tcp
     66 and tcp6 since those are different listening sockets and addresses;
     67 we don't bother with IPv6 and separate rules. We use nfail = 6,
     68 because ssh allows 3 password attempts per connection, and this
     69 will let us have 2 connections before blocking. Finally we block
     70 for an hour; we could block forever too by specifying * in the
     71 duration column.
     72 
     73 blocklistd and the library use syslog(3) to report errors. The
     74 blocklist filter state is persisted automatically in /var/db/blocklistd.db
     75 so that if the daemon is restarted, it remembers what connections
     76 is currently handling. To start from a fresh state (if you restart
     77 npf too for example), you can use -f. To watch the daemon at work,
     78 you can use -d.
     79 
     80 The current control file is designed for npf, and it uses the
     81 dynamic rule feature. You need to create a dynamic rule in your
     82 /etc/npf.conf on the group referring to the interface you want to block
     83 called blocklistd as follows:
     84 
     85 ext_if=bge0
     86 int_if=sk0
     87 	
     88 group "external" on $ext_if {
     89 	...
     90         ruleset "blocklistd-ext" 
     91         ruleset "blocklistd" 
     92 	...
     93 }
     94 
     95 group "internal" on $int_if {
     96 	...
     97         ruleset "blocklistd-int" 
     98 	...
     99 }
    100 
    101 You can use 'blocklistctl dump -a' to list all the current entries
    102 in the database; the ones that have nfail <c>/<t> where <c>urrent
    103 >= <t>otal, should have an id associated with them; this means that
    104 there is a packet filter rule added for that entry. For npf, you
    105 can examine the packet filter dynamic rule entries using 'npfctl
    106 rule <rulename> list'.  The number of current entries can exceed
    107 the total. This happens because entering packet filter rules is
    108 asynchronous; there could be other connection before the rule
    109 becomes activated.
    110 
    111 Enjoy,
    112 
    113 christos
    114