Skip to content

Commit

Permalink
Fix format and prepare for latest changes on the source code
Browse files Browse the repository at this point in the history
@proditis
proditis committed Jun 10, 2015
1 parent cf8324e commit 9de73fd
Showing 1 changed file with 53 additions and 18 deletions.
71 changes: 53 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,21 @@
# pf diverters

A collection of daemons written for [OpenBSD](http://www.openbsd.org/) [PF](http://www.openbsd.org/faq/pf/), that listen on [divert(4)](http://www.openbsd.org/cgi-bin/man.cgi?query=divert&sektion=4) sockets.

PF can be configured to send matching packets to a divert socket via the parameter `divert-packet port <port>`. Divert sockets are bound to divert ports (completely separated from tcp/udp) and enable us to queue raw packets from the kernel stack to userspace applications and vice versa.

This synergy leaves plenty of space for innovation; matching packets from PF can be stopped from propagating through the IP stack, in order to be brought to our userspace daemons, and optionally be re-injected back into the kernel stack for normal processing. Certainly, the daemons can perform additional checks on intercepted connections and, based on those checks, immediately enforce firewall policy.

A collection of daemons written for [OpenBSD](http://www.openbsd.org/)
[PF](http://www.openbsd.org/faq/pf/), that listen on
[divert(4)](http://www.openbsd.org/cgi-bin/man.cgi?query=divert&sektion=4)
sockets.

PF can be configured to send matching packets to a divert socket via the
parameter `divert-packet port <port>`. Divert sockets are bound to divert ports
(completely separated from tcp/udp) and enable us to queue raw packets from the
kernel stack to userspace applications and vice versa.

This synergy leaves plenty of space for innovation; matching packets from PF
can be stopped from propagating through the IP stack, in order to be brought to
our userspace daemons, and optionally be re-injected back into the kernel stack
for normal processing. Certainly, the daemons can perform additional checks on
intercepted connections and, based on those checks, immediately enforce
firewall policy.

```
WARNING: THESE TOOLS ARE EXPERIMENTAL AND IN NO-WAY PRODUCTION READY.
@@ -15,28 +25,40 @@ Feel free to test and run them on your systems, but make sure you keep a close e

List of diverters available:

* `bofh-divert` Divert connections to this daemon and add each src host to a predefined PF table (used for banning abusers).
* `dnsbl-divert` Divert connections to this daemon and check if the source ip is on a dnsbl and drop packet, or else reinject packet to reach its original destination. (still work-in-progress)
* `bofh-divert` Divert connections to this daemon and add each src host to a
predefined PF table (used for banning abusers).
* `dnsbl-divert` Divert connections to this daemon and check if the source ip
is on a dnsbl and drop packet, or else reinject packet to reach its original
destination. (still work-in-progress)

## Building

On an OpenBSD system, get the source and simply run make:

<sub>Note: if git(1) is not installed on your system, you can always download the code as a tar.gz archive ([http link](https://github.com/echothrust/pf-diverters/archive/master.tar.gz)).</sub>
<sub>Note: if git(1) is not installed on your system, you can always download
the code as a tar.gz archive ([http link](https://github.com/echothrust/pf-diverters/archive/master.tar.gz)).</sub>

```
$ git clone https://github.com/echothrust/pf-diverters
$ cd pf-diverters
$ make
```

This will compile the binaries for the diverters. If you wish, you can also run `make install` to place the executables in `/usr/local/sbin` and the rc scripts in /etc/rc.d.
This will compile the binaries for the diverters. If you wish, you can also run
`make install` to place the executables in `/usr/local/sbin` and the rc scripts
in /etc/rc.d.

## Running

### bofh-divert

A simple divert socket daemon that can used to automaticaly block connections. With the help of PF, you redirect a bunch of unused (by you) ports to this daemon listening on a divert socket and hosts that attempt access are instantly added to a predefined PF table. Combined with a block rule for that table, this essentially sets tripwires for any attackers probing those unused TCP ports, effectively blocking the rest of the attempts originating from the same IP addresses.
A simple divert socket daemon that can used to automaticaly block connections.
With the help of PF, you redirect a bunch of unused (by you) ports to this
daemon listening on a divert socket and hosts that attempt access are instantly
added to a predefined PF table. Combined with a block rule for that table, this
essentially sets tripwires for any attackers probing those unused TCP ports,
effectively blocking the rest of the attempts originating from the same IP
addresses.

```
$ ./bofh-divert
@@ -45,7 +67,9 @@ usage: bofh-divert <divert_port> <pf_table_name>
<pf_table_name> table to add collected host IPs (up to 32 chars)
```

Say you run `bofh-divert 1100 bastards`, you would also need the corresponding PF rules for this to work, in `/etc/pf.conf`, say for a list of well-known scanner ports:
Say you run `bofh-divert 1100 bastards`, you would also need the corresponding
PF rules for this to work, in `/etc/pf.conf`, say for a list of well-known
scanner ports:

```
table <bastards> persist counters
@@ -61,7 +85,9 @@ Sep 17 18:56:16 fw01 bofh-divert: attacker_ip:13477 -> your_ip:3389

### dnsbl-divert

A similar daemon that can be used on firewalls to fence connections on listening (used) ports. Based on DNS blacklists, source IPs can be validated prior to allowing the connection to happen.
A similar daemon that can be used on firewalls to fence connections on
listening (used) ports. Based on DNS blacklists, source IPs can be validated
prior to allowing the connection to happen.

```
$ ./dnsbl-divert
@@ -72,7 +98,10 @@ usage: dnsbl-divert <divert_port> <pf_table_black> <pf_table_cache> [dns_ip]
<dns_ip> DNS server address (default: use system-configured dns)
```

This is BETA/untested software that can take numerous improvements. Usage is very similar to bofh-divert, but this is destined for application in front of listening ports. For up-to-date running instructions, PF config and also for setting your prefered DNSBLs, please take a look in the source code.
This is BETA/untested software that can take numerous improvements. Usage is
very similar to bofh-divert, but this is destined for application in front of
listening ports. For up-to-date running instructions, PF config and also for
setting your prefered DNSBLs, please take a look in the source code.

### rc.scripts

@@ -83,21 +112,27 @@ ln -s /etc/rc.d/rc.bofh /etc/rc.d/bofh_bastards
echo 'bofh_bastards_flags="1100 bastards"' >> /etc/rc.conf.local
```

This will configure the system to start `bofh-divert` daemon on boot, listening on divert_port '1100' and logging offenders in PF table 'bastards'. Of course, PF should be configured to create the table 'bastards' and forward offending connections to divert_port 1100.
This will configure the system to start `bofh-divert` daemon on boot, listening
on divert_port '1100' and logging offenders in PF table 'bastards'. Of course,
PF should be configured to create the table 'bastards' and forward offending
connections to divert_port 1100.

## Notes

The code is destined to compile and run on OpenBSD 5.3 amd64. It could also be suitable for other platforms featuring PF, but modifications may be needed.
The code is destined to compile and run on OpenBSD 5.3 amd64. It could also be
suitable for other platforms featuring PF, but modifications may be needed.

On OpenBSD, superuser privileges are required to open a divert socket (and thus run these programs).
On OpenBSD, superuser privileges are required to open a divert socket (and thus
run these programs).

When dealing with pf tables you also need write access to /dev/pf.

All the diverters require the pre-existance of the pf table.

## Contributing

There sure is room for improvement, but also many ideas on similar diverters to implement. Code contributions are always welcome:
There sure is room for improvement, but also many ideas on similar diverters to
implement. Code contributions are always welcome:

1. [Fork it](https://github.com/echothrust/pf-diverters/fork)
2. Clone your forked project (`git clone https://github.com/YOUR-ACCOUNT/pf-diverters`)

0 comments on commit 9de73fd

Please sign in to comment.