The instructions below only apply to pfSense 2.0, pfSense 1.x is NOT supported by an automatic script. Contact ThreatSTOP support if you wish to run ThreatSTOP on a pfSense 1.x device.
We have written some scripts to set up your pfSense firewall with the correct firewall rules, to get your block lists, use the results to update the rules and to upload your firewall logs to us.
You can download the scripts here but you will probably find it easier to cut and paste the line in the instructions below.
If this is a new device, please allow up to 15 minutes for our systems to be updated.
To set up your firewall you will find it easiest to have enabled SSH on the device. It is possible to follow the instructions by typing directly from the firewall CLI console but the easiest way to do the install is to cut a line from this page and past it into the console. Therefore these instructions assume you have enabled SSH.
You should connect to the pfSense firewall via SSH and log in to it as root (not admin!). Then select option 8 (shell) to get to a shell prompt. Using that login session you should confirm that the firewall can also access/download files from the Internet. In particular you should check that your firewall can:
It is recommended that you save the current configuration before applying ThreatSTOP. This can be done from the Diagnostics: Backup/Restore page of the webConfigurator, as illustrated to the right.
Finally if you are running pfSense on a flash filesystem (or another filesystem that is read only by default) then you should temporarily mount the root filesystem as read/write. This is done by entering the following command in the SSH session:
- tsgetblockip.php: The main script. It downloads the block lists and creates the files pfSense uses to populate a table.
- tslogupload.php: Script that uploads the log file
- ts_state.php: Page to show ThreatSTOP state and enable/disable ThreatSTOP blocklists
- tsenable.php: Script to enable ThreatSTOP blocklists
- tsdisable.php: Script to disable ThreatSTOP blocklists
- tssetup.php: Set up script.
- tsremove.php: Script to remove ThreatSTOP from device.
- threatstop.conf.php: Configuration file (modified during setup).
Connect to the pfSense device via SSH, login as root and then select option 8 (shell). Then copy and paste the following lines into the pfSense ssh session:
This command will let the device download, unpack, and install the ThreatSTOP scripts. The scripts will then create a new page (ThreatSTOP) in the Firewall section of the webConfigurator, confirm that periodic list updates are set, and retrieve the block and allow lists associated with your device in the ThreatSTOP user portal. Additionally two aliases (ThreatSTOP_allow and ThreatSTOP_Block) will be added, however they will not appear in the alias list until ThreatSTOP is enabled in the next section.
Periodic List Updates
To have the block lists updated at regular intervals, two entries are made in crontab:
This enables tsgetblockip.php to download the latest blocklist data every two hours, but may be adjusted.
Enabling and Disabling ThreatSTOP
To enable ThreatSTOP on the device it is necessary to visit the new ThreatSTOP firewall page in the webConfigurator and click on the Enable button.
Once this has been done the page will change to report a success and to display a Disable button.
To disable the ThreatSTOP for troubleshooting purposes or to uninstall it you can click on Disable, then on Remove.
Below these buttons is a link to the ThreatSTOP marketing site.
Finally if you are running pfSense on a flash filesystem (or another filesystem that is read only by default) then you should now remount the root filesystem as read-only. This is done by entering the following command in the SSH session:
Once installation and setup are completed, reboot the system to ensure that logging works correctly. Until you reboot the device ThreatSTOP will be unable to provide you with reports but it will block traffic.
Viewing Addresses Added by ThreatSTOP
You can view the addresses that have been added by ThreatSTOP by clicking on Diagnostics, then on Tables, and selecting one of the ThreatSTOP tables in the pull-down.
Similarly, you can view the association on the rules page by hovering your cursor over the names of the ThreatSTOP tables, which shows the Diagnostics Tables view. However, this can be a little cumbersome for large tables.
A guide to troubleshooting four common problems. If you are confused or if these steps do not help then please contact ThreatSTOP support.
ThreatSTOP rules do not appear to block anything
The most likely reason is that you have not enabled ThreatSTOP (see above). If you have enabled ThreatSTOP then you should verify that you have correctly entered the firewall's IP address in the ThreatSTOP device definition page. You can verify whether the address the firewall uses is in our database by running the following from the command promt (SSH or console):
You should see a simple result stating the device's IP address and whether it is in the database or not. Database updates are not instantaneous but take place every 20 minutes; so, if you have recently added/modified the firewall IP details, you may wish to wait about half an hour before checking this. If there is no response at all then verify by using the ping command that the firewall can reach threatstop.com and, if not, that it can reach other places such as google.com. If you have no connectivity to ThreatSTOP but do have connectivity elsewhere please contact ThreatSTOP support for further information about the status of the ThreatSTOP infrastructure.
If the address is valid but there are still problems you should manually run the blocklist retrieval procedure and then examine the output. To download the blocklists do the following at the command prompt (SSH or console):
If there are problems then the script will report what the problem is.
In addition you should check that there are actual ip addresses in the block lists by checking the size of the ThreatSTOP aliastables files:
If the size of /var/db/aliastables/ThreatStop_block.txt is 0 but /var/db/aliastables/ThreatStop_allow.txt is nonzero then it is likely that you have failed to configure any block lists. Go back to the devices page in your ThreatSTOP account, click edit by the appropriate entry and confirm that you have some blocklists enabled. If you are in standard mode then normally you should have at least the "Basic", and "Advanced" blocklists enabled and probably either or both of "Botnets" and "Unix Server.". In expert mode you should confirm that you have some lists checked and you should contact ThreatSTOP support to understand what the lists you have enabled should be blocking.
ThreatSTOP blocks access to places it shouldn't
The first thing to do is to disable ThreatSTOP by using the ThreatSTOP page on webConfigurator and check that the problem is fixed. If it isn't, then ThreatSTOP is not the problem.
If it is a ThreatSTOP problem, then please report which IP address and domain you are having a problem with to ThreatSTOP support. ThreatSTOP tries very hard to ensure that we have zero false positives in our standard lists, we do occasionally miss something. . Please check in the pfSense log file (/var/log/filter.log) that the IP address is indeed being blocked by the ThreatSTOP rules before contacting us.
You can also add the ip address to a custom allow list. Once you have created the allow list and added it to this device in the "Edit device" page, it will be automatically added the next time the firewall downloads data from ThreatSTOP. If you want to force it to happen faster then after waiting about 20 minutes issue the following command on the pfSense command prompt:
Our expert Advanced lists are not so well checked for false positives as we believe that it is up to each expert user to make his or her decision about the suitability of certain feeds and some feeds - e.g. the "Parasites" feed - are known to block ip addresses that are not considered harmful by everyone. Do consider a custom allowlist (see above) as a first step and do please contact ThreatSTOP support to verify that the feeds you have chosen are appropriate to your situation.
- Other firewall rules do not appear to work
The first thing to do is to disable ThreatSTOP by using the ThreatSTOP page on webConfigurator and check that the problem is fixed, if it isn't then ThreatSTOP is not the problem.
One reason for this could be that the ThreatSTOP enable script modified the existing firewall setup and in the process disabled the effect of one of the rules. The ThreatSTOP rules are inserted before other existing rules as in almost all cases this is the correct behavior. You should click on Firewall/Rules and verify that the rules you had are still present and that the order of them and the ThreatSTOP rules makes sense. If it does not then use the webConfurator to change the order.
No Logs Uploaded
In many cases logging issues are related to issue 1) above. If running the "validip" test described above is successful then you should verify that "log enable" is set appropriately in the current configuration (all ThreatSTOP firewall drop rules should have log enable in them). Click on Firewall/Rules and see ff the blue log option is set for all ThreatSTOP rules (they are in the WAN and LAN sections). If not, then you should edit the rule to enable logging.
If the above checks are fine, then the issue may be a pfSense configuration issue.
You should check whether the "Disable writing log files to the local RAMdisk" checkbox is clear on the "Status/System Logs/Settings" page in the the webConfigurator.
You should also confirm that the system's root crontab has been correctly modified. To check the root crontab ssh into the device and do:
If crontab is correctly setup there should be a two lines with a number, some asterisks and then a command. The second one should be:
Restore to previous state
Disable ThreatSTOP in the webConfigurator by visiting the Firewall/ThreatSTOP page and then clicking on the Disable button.
Once disabled the page refreshes to show a Remove button. Clicking on that removes ThreatSTOP from your pfSense firewall. Optionally you may then SSH into the device and delete the /root/ts-pfsense/ directory.