################################################################### # pf-badhost 0.5 MacOS Installation Instructions # Copyright 2018-2021 Jordan Geoghegan ################################################################### ################################################################### # Table of Contents: ################################################################### * Upgrade Instructions (upgrade from 0.4) * Fresh Install Instructions * Post Install Notes ################################################################### # Upgrade from pf-badhost 0.4 ################################################################### NOTE: A fresh install of unbound-adblock is recommended 1) Download updated script: $ ftp https://geoghegan.ca/pub/pf-badhost/0.5/pf-badhost.sh 2) Install script with appropriate permissions and remove old install location: # install -m 755 -o root -g bin pf-badhost.sh /usr/local/bin/pf-badhost # rm /usr/local/bin/pf-badhost.sh 3) Create pf-badhost log directory: # install -d -o root -g wheel -m 755 /var/log/pf-badhost # install -o _pfbadhost -g wheel -m 640 /dev/null /var/log/pf-badhost/pf-badhost.log # install -o _pfbadhost -g wheel -m 640 /dev/null /var/log/pf-badhost/pf-badhost.log.0.gz 4) Install gsort (MacOS base-system sort doesn't support '-R', '-V' or '-Z'): brew install coreutils 5) pf-badhost now automagically detects if RipGrep or GNU grep is installed. If you were using them with previous versions of pf-badhost, then no further action is required. --- Similarly, pf-badhost also automagically detects if mawk or gawk is present. This can improve performance on low powered devices significantly (certain functions such as the geoblock and statistics generation functions saw their execution times cut by 40%! 6) To enable additional features such as IPv6, Subnet Aggregation, Geo-Blocking, Bogon Filtering or Authlog Scanning open "/usr/local/bin/pf-badhost" with your text editor of choice and find the "User Configuration Area" near the top of the file where you can enable features by setting their value to "1" --- See the "Notes" section below for more info on installing optional utilities. Please read the man page for information on how to configure pf-badhost. The manpage can be found here: https://www.geoghegan.ca/pub/pf-badhost/0.5/man/man.txt To receive notification of new pf-badhost releases and updates please send an email to 'announce@geoghegan.ca' with a subject line and body of "subscribe pf-badhost" ################################################################### # Fresh Installation Guide ################################################################### 1) Create a new user (we'll call ours "_pfbadhost"): The user should be created with default shell of "nologin" and an empty password (disables password logins) NOTE: Make sure you set the "UniqueID" and "PrimaryGroupID" to an unused value! # dscl . -create /Users/_pfbadhost # dscl . -create /Users/_pfbadhost UserShell /sbin/nologin # dscl . -create /Users/_pfbadhost RealName “_pfbadhost" # dscl . -create /Users/_pfbadhost UniqueID 1011 # Pick an unused UID here # dscl . -create /Users/_pfbadhost PrimaryGroupID 1011 # Pick an unused GID here 1.b) You may need to give the user admin privledges, but you shouldn't need to: # dscl . -append /Groups/admin GroupMembership _pfbadhost 2) Download script: $ curl https://geoghegan.ca/pub/pf-badhost/0.5/pf-badhost.sh 3) Install script with appropriate permissions: # install -m 755 -o root -g bin pf-badhost.sh /usr/local/bin/pf-badhost 4) Create required files: # install -m 640 -o _pfbadhost -g wheel /dev/null /etc/pf-badhost.txt # install -d -m 755 -o root -g wheel /var/log/pf-badhost # install -m 640 -o _pfbadhost -g wheel /dev/null /var/log/pf-badhost/pf-badhost.log # install -m 640 -o _pfbadhost -g wheel /dev/null /var/log/pf-badhost/pf-badhost.log.0.gz 5.a) Install GNU sort and RipGrep: # brew install coreutils ripgrep 5.b) OPTIONAL: Install mawk for improved performance: # brew install mawk 6) Give "_pfbadhost" user permission to use sudo without a password: Run "sudo visudo" and then add the following line near the end of the file: _pfbadhost ALL = (ALL) NOPASSWD: ALL 7) Add the following lines to your pf.conf: (Putting it higher-up/earlier in the ruleset is recommended) ... table persist file "/etc/pf-badhost.txt" block in quick on egress from block out quick on egress to ... 8) To enable additional features such as IPv6, Subnet Aggregation, Geo-Blocking, Bogon Filtering or Authlog Scanning open "/usr/local/bin/pf-badhost" with your text editor of choice and find the "User Configuration Area" near the top of the file where you can enable features by setting their value to "1" --- See the "Notes" section below for more info on installing optional utilities. 9) Run pfbadhost as user "_pfbadhost" using the "-O macos" argument: # sudo -u _pfbadhost pf-badhost -O macos 10) Reload your pf rule set: # pfctl -f /etc/pf.conf 11) For good measure, we'll run the pf-badhost script once more: # sudo -u _pfbadhost pf-badhost -O macos 12) Edit _pfbadhost crontab to run pf-badhost every night at midnight: # crontab -u _pfbadhost -e ... @daily pf-badhost -O macos ... Yay! pf-badhost is now installed! With the nightly cron job, the list will be regularly updated with the latest known bad hosts. Please read the man page for information on how to configure pf-badhost. The manpage can be found here: https://www.geoghegan.ca/pub/pf-badhost/0.5/man/man.txt To receive notification of new pf-badhost releases and updates please send an email to 'announce@geoghegan.ca' with a subject line and body of "subscribe pf-badhost" ################################################################### # Post Install Notes: ################################################################### 1) To add custom rules or enable features, or add alternate blocklists, See the "User Configuration Area" located at the top of the script. This area serves as a built in config file, so please feel free to edit it and experiment with all the features available within. --- Note: Most options can also be configured from the command line 2) NOTE: authlog analysis is not supported on MacOS 3) The script is able to detect which (if any) subnet aggregation utilities are installed and will try to "Do The Right Thing(tm)" and fallback to the best available option. If no subnet aggregation utility is found, the script will fallback to using a pure Perl IPv4 aggregator if Perl is installed. Despite its name, "aggregate6" supports both IPv4 and IPv6 addresses and is written in Python, whereas the "aggregate" utility supports only IPv4 addresses and is written in C and uses less memory and runs slightly faster. If both utilities are installed, the C based "aggregate" utility will be preferred for IPv4 aggregation, but the script will happily function if only one or the other is installed (or neither). --- Note: Subnet aggregation can be enabled with the '-A' switch on the commandline. * "aggregate" can be installed via: # brew install aggregate * "aggregate6" can be installed via: # pip install aggregate6 * The experimental aggregator "aggy" can be installed like so: ... # brew install go $ curl https://geoghegan.ca/pub/aggy/0.1/aggy.go $ go build aggy.go # install -m 755 -o root -g bin aggy /usr/local/bin/aggy ... 4) If you intend to run pf-badhost on a LAN or are using NAT etc, you will want to negate your local subnet range from the filter. This can be equally achieved via four different methods: i) Specify rule on command line (requires updating cron job): $ pf-badhost -O macos -r '!192.0.2.0/24' -r '!2001:db8::/64' ii) Specify path to text file containing list of rules (1 per line): $ pf-badhost -O macos -w '/path/to/rules.txt' iii) Edit built-in config file: # vi /usr/local/bin/pf-badhost ... # User Defined Rules: !192.0.2.0/24 !2001:db8::/64 ... iv) Conversely, you can add a pass quick rule to your pf.conf appearing BEFORE the pf-badhost rules allowing traffic to and from your local subnet so that you can still access your gateway and any DNS servers. Something like this should do: # vi /etc/pf.conf ... pass in quick on egress from 192.0.2.0/24 pass out quick on egress to 192.0.2.0/24 table persist file "/etc/pf-badhost.txt" block in quick on egress from block out quick on egress to ...