We have written some scripts to set up the EdgeOS device with the correct firewall rules, to get your block lists and use the results to update the ipset sets that are created 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 links in the instructions below.
- EdgeOS is a fork of the Vyatta codebase. These instructions have been adapted from our Vyatta instructions but the background links below refer to Vyatta as the two are essentially the same.
- If this is a new device, please allow up to 30 minutes for our systems to be updated.
- If you are unclear about what the scripts will do you should read the background notes first. This also explains the difference between "Bridge" and "Router" mode.
- We also have a PDF file showing how to setup a basic Vyatta/EdgeOS device and then apply ThreatSTOP to it.
You should have a management station with a web browser that can read this page and an ssh client that can access the EdgeOS device.
You should have set up your EdgeOS device with the external ethernet port and ip address as well as a management ip address that can be accessed from your management station.
The EdgeOS device should have ssh enabled on it, which can be done by entering these commands from the console:
You should also ensure that the device has a default gateway and name server configured. If you wish you may set the default name server of the device to one of the ThreatSTOP DNS servers (addresses below).
You should confirm that the management's ssh client can connect to the EdgeOS device and log in to it. Using that login session you should confirm that the EdgeOS device can also access/download files from the Internet. In particular you should check that your EdgeOS device can:
It is recommended that you save the configuration prior to applying the ThreatSTOP changes, which can be done by entering the following from the console:
If this is a reinstallation you may wish to either rename the folder ts-vyatta something else or restore the system to its original state before running the reinstallation code.
You should also download the libnet-dns-perl module. This can be done by entering the following after logging in:
Copy and paste the following line into the EdgeOS ssh session:
The device should download and unpack the ThreatSTOP scripts and then run the setup script which will display the following (if you have a sudo password enabled on your EdgeOS device then you will need to enter that when prompted).
You will then be asked a number of questions and normally you should accept the default values. The critical questions are the third one asking about the external interface id and the subsequent ones concerning firewall rule names and numbers. If the external interface id is not eth0 then you must correct this. Likewise if you have existing firewall rules defined for the "in", "out" and "local" directions of the external interface you must enter their names and an appropriate rule number since otherwise those rules will no longer be applied to traffic on that interface. If you do have existing rules it is generally recommended that the ThreatSTOP rules are performed first and thus that they have the lowest numbers. The setup script creates the four ThreatSTOP rules with consecutive numbers. Thus, if your existing rules start at 10, you should specify that the script insert the rules starting from 1 to 5.
Once these questions have been answered the script will create the install directory and copy files if required, test whether the firewall can download the block list from ThreatSTOP's DNS server and create the EdgeOS firewall rules (but not apply them) and the modifications of the various files that are needed.
Now you are asked whether you wish to accept the changes. If you have a complex/non-standard configuration you may wish to say N at this point and examine the files that have been created.
Finally you have the choice to run the script to get the block list data for the first time:
After some seconds (depending on the blocklist size and the connectivity to our DNS servers this may take up to a minute) you should see a report of a successful first run and the script completes. Assuming this last step reports success, you have installed ThreatSTOP on your EdgeOS routing device.
You should verify that none of the changes have broken basic connectivity and, if there are no problems, you should save the configuration so that it is used whenever the device reboots. This can be done by entering from the console:
To view the contents of the block and allow lists, you will need to run the "ipset" command:
The output will most likely go by too fast to view. You can pipe it to less so you can page through the output:
When updating EdgeOS by using the image upgrade procedure, the scripts will be moved to a different location on the filesystem. This results in the block list not being updated and logs not uploading. In order to get ThreatSTOP working again, you will need to re-run the setup procedure, but this time it is run in a update mode. The configuration will not be modified, but the cronjobs that update the block list and uploads the log are recreated.
To perform the update copy and paste the following line into the EdgeOS ssh session:
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 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 file. To download the blocklists do the following at the command prompt (SSH or console):
In the output file the first few lines should look like:
If instead you see ;; connection timed out; no servers could be reached then there is a problem with either our DNS or with the internet path to us. If you confirm via pings etc. (see above) that the problem is with our DNS then please contact ThreatSTOP support for guidance on how to use a backup DNS server (and/or when the DNS will resume operation).
If the status message is NXDOMAIN or REFUSED then the blocklist name is probably incorrect. Double-check that the name in the file is<block list name>.<ThreatSTOP account ID>.threatstop.local
If the status is NOERROR but the ANSWER number is 0 (or possibly 1) then the likely issue is that you have forgotten to enable any blocklists. 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 normally you should have at least the "Basic", and "Advanced" blocklists enabled and probably either or both of "Botnets" and "Unix Server". In Advanced 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
Although ThreatSTOP tries very hard to ensure that we have zero false positives in our standard lists, we do occasionally miss something. If you are a community user or are using ThreatSTOP in standard mode on your firewall then please report the offending domain and ip address to ThreatSTOP support. Please check in the EdgeOS log file (/var/log/threatstop.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.
Note:Our Advanced lists are not so well checked for false positives as we believe that it is up to each user to make a decision about the suitability of certain feeds. 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 most common reason for this is that the ThreatSTOP setup script modified the existing firewall setup and in the process overwrote either the name of the firewall used for traffic or some of the rules - including changing the default action to accept.
Take a look at the "prethreatstop" and "postthreatstop" saved configurations (both are in /opt/vyatta/etc/config) to see what changes have been made. One place to look at is in the interfaces section. If there are firewall names in the prethreatstop bridge interfaces then make sure that they remain there in the postthreatstop (check spelling differences). If those match then also check that you did not overwrite rules in that firewall name and also verify that if the firewall name had a "default-action accept" line previously.
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 log enable in them).
You should also confirm that the systems root crontab and /etc/logrotate.d/messages files have been correctly modified. To check the root crontab do:
If crontab is correctly setup there should be a line with a number, some asterisks and then the following perl command line:
To check the /etc/logrotate.d/messages enter:
If crontab is correctly setup there should be the following lines displayed:
You should also be able to see the same lines in the relevant files in the ts-vyatta directory. An upload can be forcing a logrotation and then examining /tmp/tsoutput.txt for errors.
Logging private addresses
If private intranet addresses are being logged talking to other private addresses then it is possible that the issue is to do with the "log-martians enable" line that ThreatSTOP adds to the firewall configuration. You should verify that the traffic is indeed harmless and then remove that line.
Restore to previous state
If you have run setup and applied the changes and wish to return to the pre-threatstop configuration then you should perform the following command (assuming that you installed to /home/vyatta/ts-vyatta).
From a console enter:
Optionally you may also wish to remove the ts-vyatta directory (rm -r ts-vyatta/).
This has now restored all the files changed. To restore the configuration you should do the following:
It is possible that you may need to "load prethreatstop" more than once to handle "commit" errors. Once you have managed to load the old configuration without error you should probably reboot the EdgeOS device to be sure that it runs with no traces of ThreatSTOP changes in the system.