The foghorn project is a DNS proxy intended to reduce user exposure to phishing and other malicious items that can be interdicted by DNS greylisting
Python Makefile
Switch branches/tags
Nothing to show
Latest commit 301252f Feb 8, 2017 @Dr-Syn Dr-Syn Merge pull request #52 from zallison/baseline_settings
Baseline settings
Permalink
Failed to load latest commit information.
docs More documentation changes Sep 2, 2016
example
foghornd Allow baseline property to be set in the settings file Nov 11, 2016
.flake8 Config for flake8 and a Makefile Sep 3, 2016
.gitignore Add eggs and virtualenv to gitignore Oct 18, 2016
Makefile Added all and install option, clean updated Oct 18, 2016
README.md Update README.md Oct 26, 2016
contributors.txt
foghorn.py pylint update for foghorn.py Aug 26, 2016
foghornc.py Made foghornc.py executeable Oct 3, 2016
foghornd.tac Catch exception where an interface has no address Oct 26, 2016
pylintrc
requirements.txt Update requirements.txt Oct 26, 2016
setup.py

README.md

README

This README is for the foghorn project.

Table of Contents

Description

  • foghorn is a configurable DNS proxy to allow for black-, white-, and greylisting of DNS resources.
  • Version 0.1

Setup

Configuration

Configuration details can be found in docs/foghorn-whitepaper.md - you will need to configure your networks to be compatible with certain prerequisites before foghorn will be effective

There are four configuration files:

  • greydns/blacklist - a UTF-8 encoded list of blacklisted domains, one per line.
  • greydns/whitelist - a UTF-8 encoded list of whitelisted domains, one per line.
  • greydns/greylist - a UTF-8 encoded file for greylisted entities, one per line, listed as a comma-separated list of DNS, firstseen, and lastseen times.
  • settings.json - a json dictionary of configuration variables, lightly documented in settings.py

Dependencies

foghorn is dependent on python, twisted, python-dateutil, and requests

Your OS may have specific packages required to install some of these - for example, CentOS 7 demands python-devel

Installation

Foghorn requires that twisted, python-dateutil, netifaces, and requests be installed prior to use. Run:

pip install twisted python-dateutil requests netifaces

Foghorn can then be installed via PIP directly from this GitHub repository. To install first, then edit the configuration settings later, run:

python -m pip install git+git://github.com/hasameli/foghorn.git --user

Otherwise, you can clone the repository and install it manually:

git clone https://github.com/hasameli/foghorn.git
cd foghorn
python setup.py install --user

After you have configured the settings in foghornd/settings.json appropriately for your network (see the docs folder for an explanation of the settings) you can run foghorn with

make run

and test it out.

Deployment Instructions

See the diagram in the bsideslv-2016 presentation in the docs folder for an overview; see also the foghorn-whitepaper.md for rationale, etc.

foghorn MUST be positioned within a network with egress filtering enabled for DNS - only the local resolver can be allowed to make outbound requests for DNS.

Also, squid or some similar proxy should be in place to filter naked IP requests, in order to mitigate the possibility of certain workarounds that would otherwise be available to attackers.

After baselining, the workstations that you desire to protect should be configured to use the foghorn server as their DNS resolver, and any ACLs adjusted accordingly.

FAQ

Available here

Gotchas

Installing this within Virtualbox or KVM may require forwarding ports in order to ensure access to the VM.

Some OSs may require development tools be installed before twisted will install correctly.

FreeBSD requires pkg install openssl databases/py-sqlite3 installed before foghorn can be installed. It also may require symlinking a 'python' alias to /usr/local/bin/python2.7

If you desire foghorn to run on the standard DNS port 53, you MUST run with root privileges. Use this with caution! The default port is set to 10053 specifically to avoid this.

If you change the settings in settings.json you will need to rerun setup.py as per the instructions above before the new settings will be enabled.

Contributor Guidelines

  • We would like contributions to be in line with the PEP8 standards.
  • We would like if you run pylint before sending contributions. It makes things a little tidier.
  • If adding a new feature, please check if it's listed in the issues and reference it in your PR

License

MIT

Contact