├── README.md
├── dns-shield-install.sh
└── images
    ├── 2018-10-14-11-03-47.png
    ├── 2018-10-14-12-08-36.png
    └── 2018-10-14-13-00-35.png


/README.md:
--------------------------------------------------------------------------------
  1 | ![](images/2018-10-14-11-03-47.png)
  2 | # **DNS Shield** 
  3 | 
  4 | **A simple DNS firewall to block ads, tracking and malware.**
  5 | 
  6 | This is a simple system that uses the excellent [CoreDNS](https://coredns.io/) DNS server, a composite [blacklist](https://github.com/StevenBlack/hosts) and CoreDNS's proxy capabilities to block users from ads, tracking, spyware, and malware content (currently blocks over 56K sites). In addition, alternate blacklists can be selected to also block porn, gambling, social media and fake news content. Since this works at the DNS level, it will work with all clients regardless of the OS, platform, browser and without the need for any plugins. The basic architecture is shown in the diagram below.
  7 | 
  8 | ![](images/2018-10-14-12-08-36.png)
  9 | 
 10 | ## Requirements
 11 | 
 12 | To install DNS Shield you'll need a Linux server with tcp/udp port 53 open (might need to disable/stop local dnsmasq server to free up port 53). The install script has been tested with Ubuntu 16.04 and 18.04 but it should also work on CentOS 7.x or any other systemd based system.  You'll also need at least one downstream DNS server to proxy requests to (your institution's, or ISP's DNS server(s)).
 13 | 
 14 | ## Installation
 15 | 
 16 | If you are on the Fred Hutch campus network you can use the install script as-is to install DNS Shield with the following command:  
 17 | 
 18 | ```bash
 19 | sudo bash -c "curl -s https://raw.githubusercontent.com/FredHutch/dns-shield/master/dns-shield-install.sh | bash"
 20 | ```
 21 | 
 22 | If you are not on the Fred Hutch campus network you'll need edit the script to include your dns server(s). First download the the installer script and make it executable:
 23 | 
 24 | ```bash
 25 | curl -s https://raw.githubusercontent.com/FredHutch/dns-shield/master/dns-shield-install.sh  > dns-shield-install.sh
 26 | chmod +x dns-shield-install.sh
 27 | ```
 28 | 
 29 | Edit the variables section of the script and update the DNS_SERVER1/2 variables. For example below we are going to use the public Google DNS servers:
 30 | 
 31 | ```bash
 32 | # Backend DNS servers to proxy; format "<ip_address>:<port>"
 33 | DNS_SERVER1=8.8.8.8:53
 34 | DNS_SERVER2=8.8.4.4:53
 35 | ```
 36 | 
 37 | Then execute the script as follows:
 38 | 
 39 | ```bash
 40 | sudo ./dns-shield-install.sh
 41 | ```
 42 | 
 43 | ## Testing
 44 | 
 45 | To make sure that the service is using the blacklist to block some requests, execute the following command on the server were DNS Shield in installed:
 46 | 
 47 | ```bash
 48 | dig @127.0.0.1 doubleclick.net
 49 | ```
 50 | 
 51 | In the answer section of the output you should see that the query received a non-routable address of "0.0.0.0":
 52 | 
 53 | ```bind
 54 | ;; ANSWER SECTION:
 55 | doubleclick.net.	3600	IN	A	0.0.0.0
 56 | ```
 57 | 
 58 | Now to make sure that non-blacklisted queries are being proxied to your DNS servers. Execute the following command on the server:
 59 | 
 60 | ```bash
 61 | dig @127.0.0.1 status.fredhutch.org
 62 | ```
 63 | 
 64 | In the output you should see that the query succeeded and you got a vaild IP in the answer section like the following:
 65 | 
 66 | ```bind
 67 | ;; ANSWER SECTION:
 68 | status.fredhutch.org.	86400	IN	A	52.60.128.125
 69 | ```
 70 | 
 71 | ## Client Configuration
 72 | 
 73 | Since DNS Shield works at the DNS level all that's required is to adjust the client's DNS settings and putting the IP address of the DNS Shield server as the first DNS server. As a backup the second and possibly third DNS server configured configured should be your standard DNS servers. With this configuration, if the DNS Shield has an outage, clients will bypass it and still resolve queries.
 74 | 
 75 | After a client has been configured to use the DNS Shield server as their first DNS server, ads and other unwanted content will simply be missing from rendered websites. Here is an example of the same website first without DNS Shield and then with DNS Shield (notice the extra whitespace).
 76 | 
 77 | ![](images/2018-10-14-13-00-35.png)
 78 | 
 79 | If you want to rollout DNS Shield to all clients on specific subnets on your entire network you can adjust your DHCP server to automatically configure clients DNS configuration.
 80 | 
 81 | ## Blacklist Updates
 82 | 
 83 | The upstream site typically updates the blacklists once a day. The install script created a cron job to check for and apply updates every six hours.
 84 | 
 85 | ## Blocking Porn, Gambling, Fake News, or Social Media Content
 86 | 
 87 | By default DNS Shield is only protecting from ads, tracking and malware sites. If you'd like to add protection from additional types of content such as porn, fake news, gambling or and social media you are configure CoreDNS to use an alternate blacklist. All blacklist contain ads/tracking/malware and are available in the following combinations:
 88 | 
 89 | - ads+malware+fakenews:  /etc/coredns/hosts/alternates/fakenews/hosts
 90 | - ads+malware+fakenews+gambling: /etc/coredns/hosts/alternates/fakenews-gambling/hosts
 91 | - ads+malware+fakenews+gambling+porn: /etc/coredns/hosts/alternates/fakenews-gambling-porn/hosts
 92 | - ads+malware+fakenews+gambling+porn + social: /etc/coredns/hosts/alternates/fakenews-gambling-porn-social/hosts
 93 | - ads+malware+fakenews+gambling+social: /etc/coredns/hosts/alternates/fakenews-gambling-social/hosts
 94 | - ads+malware+fakenews+porn: /etc/coredns/hosts/alternates/fakenews-porn/hosts
 95 | - ads+malware+fakenews+porn+social: /etc/coredns/hosts/alternates/fakenews-porn-social/hosts
 96 | - ads+malware+fakenews+social: /etc/coredns/hosts/alternates/fakenews-social/hosts
 97 | - ads+malware+gambling: /etc/coredns/hosts/alternates//hosts
 98 | - ads+malware+gambling+porn: /etc/coredns/hosts/alternates/gambling/hosts
 99 | - ads+malware+gambling+porn+social: /etc/coredns/hosts/alternates/gambling-porn-social/hosts
100 | - ads+malware+gambling+social: /etc/coredns/hosts/alternates/gambling-social/hosts
101 | - ads+malware+porn: /etc/coredns/hosts/alternates/porn/hosts
102 | - ads+malware+porn+social: /etc/coredns/hosts/alternates/porn-social/hosts
103 | - ads+malware+social: /etc/coredns/hosts/alternates/social/hosts
104 | 
105 | To use a different blacklist, edit the CoreDNS configuration file (/etc/coredns/Corefile) and edit the "hosts" line to point to the correct hosts file. For example here we are adding porn content filtering:
106 | 
107 | ```bind
108 | .:53 {
109 |     prometheus 0.0.0.0:9153
110 |     bind 0.0.0.0
111 |     hosts /etc/coredns/hosts/alternates/porn/hosts {
112 |       fallthrough
113 |     }
114 |     proxy . 140.107.42.11:53 140.107.117.11:53
115 | }
116 | ```
117 | 
118 | After making changes to the CoreDNS server you'll need to restart the service.
119 | 


--------------------------------------------------------------------------------
/dns-shield-install.sh:
--------------------------------------------------------------------------------
 1 | #!/bin/bash
 2 | set -e
 3 | 
 4 | # Variables #################################
 5 | # Version of CoreDNS to use
 6 | COREDNS_VERSION=1.2.2
 7 | # Backend DNS servers to proxy; format "<ip_address>:<port>"
 8 | DNS_SERVER1=140.107.42.11:53
 9 | DNS_SERVER2=140.107.117.11:53
10 | #############################################
11 | 
12 | # install Git and Wget
13 | echo -e "\nInstalling dependencies (git and wget)..."
14 | apt -qq update 
15 | apt -y -qq install git wget
16 | 
17 | # Create the unprivileged coredns user
18 | echo -e "\nCreating coredns user..."
19 | useradd -m -d /var/lib/coredns --shell /bin/false coredns
20 | 
21 | # Download and install CoreDNS
22 | echo -e "\nDownloading and installing CoreDNS..."
23 | wget -q  https://github.com/coredns/coredns/releases/download/v${COREDNS_VERSION}/coredns_${COREDNS_VERSION}_linux_amd64.tgz
24 | tar xf coredns_${COREDNS_VERSION}_linux_amd64.tgz 
25 | chmod +x coredns
26 | mv coredns /usr/local/bin/
27 | 
28 | # Download blacklist 
29 | echo -e "\nDownloading blacklist..."
30 | mkdir -p /etc/coredns
31 | git clone -q https://github.com/StevenBlack/hosts.git /etc/coredns/hosts
32 | 
33 | # Create CoreDNS configuration
34 | echo "Configuring CoreDNS..."
35 | cat > /etc/coredns/Corefile << EOL
36 | .:53 {
37 |     prometheus 0.0.0.0:9153
38 |     bind 0.0.0.0 
39 |     hosts /etc/coredns/hosts/hosts {
40 |       fallthrough
41 |     }
42 |     proxy . ${DNS_SERVER1} ${DNS_SERVER2}
43 | }
44 | EOL
45 | 
46 | # Create Systemd configuration
47 | echo -e "\nConfiguring systemd..."
48 | cat > /lib/systemd/system/coredns.service << EOL
49 | [Unit]
50 | Description=CoreDNS DNS server
51 | Documentation=https://coredns.io
52 | After=network.target
53 | 
54 | [Service]
55 | PermissionsStartOnly=true
56 | LimitNOFILE=1048576
57 | LimitNPROC=512
58 | CapabilityBoundingSet=CAP_NET_BIND_SERVICE
59 | AmbientCapabilities=CAP_NET_BIND_SERVICE
60 | NoNewPrivileges=true
61 | User=coredns
62 | WorkingDirectory=~
63 | ExecStart=/usr/local/bin/coredns -conf=/etc/coredns/Corefile
64 | ExecReload=/bin/kill -SIGUSR1 \$MAINPID
65 | Restart=always
66 | RestartSec=3
67 | 
68 | [Install]
69 | WantedBy=multi-user.target
70 | EOL
71 | 
72 | # Enable and start CoreDNS
73 | systemctl daemon-reload
74 | systemctl start coredns.service
75 | systemctl enable coredns.service
76 | systemctl --no-pager status coredns.service
77 | 
78 | # Create cron job to update black list
79 | echo -e "\nInstalling blacklist update cron job..."
80 | cat > /etc/cron.d/coredns-blacklist-update << EOL
81 | SHELL=/bin/sh
82 | PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
83 | 0 */6 * * *  root    cd /etc/coredns/hosts && git pull > /dev/null 2>&1
84 | EOL
85 | 
86 | # Cleanup
87 | echo -e "\nCleaning up..."
88 | rm coredns_${COREDNS_VERSION}_linux_amd64.tgz
89 | 
90 | echo -e "\nDone!!!"
91 | 


--------------------------------------------------------------------------------
/images/2018-10-14-11-03-47.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/FredHutch/dns-shield/6d90c004007f754a71c6c8c36bf40f9d9289328e/images/2018-10-14-11-03-47.png


--------------------------------------------------------------------------------
/images/2018-10-14-12-08-36.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/FredHutch/dns-shield/6d90c004007f754a71c6c8c36bf40f9d9289328e/images/2018-10-14-12-08-36.png


--------------------------------------------------------------------------------
/images/2018-10-14-13-00-35.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/FredHutch/dns-shield/6d90c004007f754a71c6c8c36bf40f9d9289328e/images/2018-10-14-13-00-35.png


--------------------------------------------------------------------------------