Metadata-Version: 2.1
Name: nfsinkhole
Version: 0.1.0
Summary: nfsinkhole is a Python library and scripts for setting up a Unix server as a sinkhole (monitor, log/capture, and drop all traffic to a secondary interface).
Home-page: https://github.com/secynic/nfsinkhole
Download-URL: https://github.com/secynic/nfsinkhole/tarball/master
Author: Philip Hane
Author-email: secynic AT gmail DOT com
License: Copyright (c) 2016 Philip Hane
        All rights reserved.        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
        ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Keywords: Python
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Unix Shell
Classifier: Topic :: Internet
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Monitoring
License-File: LICENSE.txt

==========
nfsinkhole
==========

.. image:: https://img.shields.io/badge/license-BSD%202--Clause-blue.svg
    :target: https://github.com/secynic/nfsinkhole/tree/master/LICENSE.txt
.. image:: https://img.shields.io/badge/python-2.6%2C%202.7%2C%203.0+-blue.svg
.. image:: https://img.shields.io/badge/os-RHEL%2FCentOS%206%2F7-blue.svg

.. warning::

    This version is considered experimental. Do not attempt to use this
    library in production until tests via travis and docker are setup, stable,
    and sufficiently covered.

.. attention::

    You are responsible for rotating log files (/var/log/nfsinkhole*), and
    syslog forwarding must be configured manually (automation pending).

nfsinkhole is a Python library and scripts for setting up a Unix server
as a sinkhole (monitor, log/capture, and drop all traffic to a secondary
interface).

The default setup arguments monitor/capture all traffic. Setup arguments are
provided to configure protocols, ports, rate limiting, logging,
source IP/CIDR exclusions from logging, and optional packet capture.

All sinkhole events are written to /var/log/nfsinkhole-events.log. Optionally,
you can enable tcpdump to output packet capture text to
/var/log/nfsinkhole-pcap.log if your version of tcpdump supports packet
printing; otherwise reverts to /var/log/nfsinkhole.pcap.

Features
========

* Simple install script
* Installs as a init.d/systemctl service
* Service modifies iptables on start/stop, no need to persist iptables
* rsyslog and syslog-ng (pending) supported
* RedHat/CentOS 6/7 tested
* Python 2.6+ and 3.0+ supported
* Built-in support for dealing with SELinux/AppArmor
* Packet capture of sinkhole traffic (printed output to log for tcpdump v4.5+)
* Useful set of utilities
* Detailed logging to /var/log/nfsinkhole-*
* Syslog forwarding configuration (pending)
* BSD license

Planned Improvements
====================

* API/class documentation
* syslog-ng support (currently partially built; unused)
* Tests via travis-ci/docker
* Coverage via coverage.io
* Exception handling overhaul
* Set logging level (currently debug)
* BIND/Microsoft/etc DNS server configuration documentation/examples
* Monitoring use case examples
* Automatic configuration for syslog forwarding
* SIEM parsers/apps/plugins
* Official support/testing for more OS environments
* Support handling exceptions for HIPS and other endpoint security products
* Intelligent handling/handshakes (inspired by iptrap -
  https://github.com/jedisct1/iptrap)

Links
=====

Documentation
-------------

Release v0.1.0
^^^^^^^^^^^^^^

https://nfsinkhole.readthedocs.io/en/v0.1.0

GitHub master
^^^^^^^^^^^^^

https://nfsinkhole.readthedocs.io/en/latest

GitHub dev
^^^^^^^^^^

https://nfsinkhole.readthedocs.io/en/dev

Examples
--------

Pending

Github
------

https://github.com/secynic/nfsinkhole

Pypi
----

https://pypi.python.org/pypi/nfsinkhole

Changes
-------

https://nfsinkhole.readthedocs.io/en/latest/CHANGES.html

Dependencies
============

OS::

    iptables (likely already included in base OS)
    tcpdump (optional - likely already included in base OS)

Python 2.6::

    argparse

Python 2.7, 3.0+::

    None!

Installing
==========

.. attention::

    The nfsinkhole service, iptables rules, and tcpdump must run as root.
    You can still use user/virtualenv Python environments, for the library,
    but ultimately, the core sinkhole will be run as root.

.. note::

    Replace any below occurence of <INTERFACE> with the name of your
    sinkhole network interface name.

Base OS (pip) -- RECOMMENDED
----------------------------

If pip is not installed, you will first need to add the EPEL repo and install::

    sudo yum install epel-release
    sudo yum install python-pip

RHEL/CentOS 6/7
^^^^^^^^^^^^^^^

Basic::

    pip install --user --upgrade nfsinkhole
    python ~/.local/bin/nfsinkhole-setup.py --interface <INTERFACE> --install --pcap

virtualenv::

    pip install virtualenv
    virtualenv nfsinkhole
    source nfsinkhole/bin/activate
    nfsinkhole/bin/pip install nfsinkhole
    nfsinkhole/bin/python nfsinkhole/bin/nfsinkhole-setup.py --interface <INTERFACE> --install --pcap

Base OS (no pip)
----------------

RHEL/CentOS 6
^^^^^^^^^^^^^

GitHub - Stable::

    wget -O argparse.tar.gz https://github.com/ThomasWaldmann/argparse/tarball/master
    tar -C argparse -zxvf argparse.tar.gz
    cd argparse
    python setup.py install --user prefix=
    cd ..
    rm -Rf argparse
    wget -O nfsinkhole.tar.gz https://github.com/secynic/nfsinkhole/tarball/master
    tar -C nfsinkhole -zxvf nfsinkhole.tar.gz
    cd nfsinkhole
    python setup.py install --user prefix=
    cd ..
    rm -Rf nfsinkhole
    python ~/.local/bin/nfsinkhole-setup.py --interface <INTERFACE> --install --pcap

RHEL/CentOS 7
^^^^^^^^^^^^^

GitHub - Stable::

    wget -O nfsinkhole.tar.gz https://github.com/secynic/nfsinkhole/tarball/master
    tar -C nfsinkhole -zxvf nfsinkhole.tar.gz
    cd nfsinkhole
    python setup.py install --user prefix=
    cd ..
    rm -Rf nfsinkhole
    python ~/.local/bin/nfsinkhole-setup.py --interface <INTERFACE> --install --pcap

Service
=======

Once installed you need to start the nfsinkhole service.

RHEL/CentOS 6
-------------

::

    sudo service nfsinkhole start

RHEL/CentOS 7
-------------

::

    sudo systemctl start nfsinkhole.service

API
===

AppArmor
--------

AppArmor documentation:

https://nfsinkhole.readthedocs.io/en/latest/apparmor.html

iptables
--------

iptables documentation:

https://nfsinkhole.readthedocs.io/en/latest/iptables.html

rsyslog
-------

rsyslog documentation:

https://nfsinkhole.readthedocs.io/en/latest/rsyslog.html

SELinux
-------

SELinux documentation:

https://nfsinkhole.readthedocs.io/en/latest/selinux.html

Service
-------

Service (systemd/init.d) documentation:

https://nfsinkhole.readthedocs.io/en/latest/service.html

syslog-ng
---------

syslog-ng documentation:

https://nfsinkhole.readthedocs.io/en/latest/syslog_ng.html

tcpdump
-------

tcpdump documentation:

https://nfsinkhole.readthedocs.io/en/latest/tcpdump.html

Utilities
---------

Utilities documentation:

https://nfsinkhole.readthedocs.io/en/latest/utils.html

Contributing
============

https://nfsinkhole.readthedocs.io/en/latest/CONTRIBUTING.html

Special Thanks
==============

Thank you JetBrains for the `PyCharm <https://www.jetbrains.com/pycharm/>`_
open source support!


Changelog
=========

0.1.0 (2016-08-29)
------------------

- Initial release

