Snub

Snub is a python package that enables users to retrieve whether or not a given IP, Hash, Email, Domain, or URL is on a blackhole list via the CLI or Flask API. You can specify whether to check if one of the indicators above is on a text based list or a DNSBL list. Alternatively you can specify your own static (known bad) indicators.

If you clone this repository you can also use the provided docker-compose.yml file to utilize an API built around Snub.

Installation

Python Package or CLI Tool

To use Snub as a Python package with in your project or a CLI tool, you can install it via pip or pip3.

pip3 install snub

Flask API

In order to utilize the provided Flask API, you will need to clone this repository and build the image:

git clone https://github.com/swimlane/snub.git

Using Python Package or CLI

Once Snub is installed using pip or from the repository, you can import the Python package within your project:

from snub import Snub

snub = Snub()

# You can check an indicator against all or a specific snubbed list
# By default snub checks all lists for the given indicator

snub.check('10.103.79.86')

# To select to use a specific list provide one of the following value set to `True` or any combination of the following.

snub.check('10.103.79.86', text_list=True, dns_list=True, static_list=True)

# Snub also includes another python package called Hopper (https://github.com/MSAdministrator/hopper).

# By using the `analyze` method within Snub you can pass in a email message raw string header and get information about the received from hops as well as whether they are on any of Snubs lists

snub.analyze('''
Delivered-To: money@capitalism.com
Received: by 10.129.52.209 with SMTP id b200csp1430876ywa;
        Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
X-Received: by 10.31.153.20 with SMTP id b20mr6116862vke.110.1507623422746;
        Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65])
        by mx.google.com with SMTPS id b31sor1345013uaa.124.2017.10.10.01.17.02
        for <money@capitalism.com>
        (Google Transport Security);
        Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
Received-SPF: pass (google.com: domain of bags@test_email.ua.edu designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65;
X-Received: by 10.176.85.196 with SMTP id w4mr6874179uaa.75.1507623422198; Tue, 10 Oct 2017 01:17:02 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.103.79.86 with HTTP; Tue, 10 Oct 2017 01:17:01 -0700 (PDT)
From: Mr. Money Bags <bags@moneyrules.com>
Date: Tue, 10 Oct 2017 01:17:01 -0700
Subject:
To: money@capitalism.com;
Content-Type: text/plain; charset="UTF-8"
Bcc: satan@wallstreet.com

A business opportunity awaits
''')  

# You can provide any of the same lists types as optional paramters.  By default it will search all from and receivedBy indicators against all lists.

Building Docker Image

You first need to build the Docker image:

docker build --force-rm -t snub .

Running the Docker Image

You can run the docker image in a few different ways:

Running the CLI tool

If running the CLI tool inside of Docker then you can run the container with the value you are wanting to search blackhole or DNS based lists for:

docker run -t -i -p 5000:5000 snub {SOME_VALUE_HERE}

An example would be:

docker run -t -i -p 5000:5000 snub tfvai.marketer.mobi

Running the API

If you want to run the API, then simply emit the value you want to search:

NOTE: You must now use docker-compose to expose the api directly

docker-compose up

If you have made changes to either of the defined lists (yml files) file then you must rebuild docker-compose:

docker-compose build

Then run docker-compose:

docker-compose up

API ENDPOINTS

There are several new API endpoints available:

Search All Snubbed Lists

To search all snubbed lists then navigate to your browser at:

http://0.0.0.0:5000/snub/search/{SOME_VALUE_HERE}

Search text based snubbed list

To search just the text based snubbed lists then navigate to your browser at:

http://0.0.0.0:5000/snub/blackhole/{SOME_VALUE_HERE}

Search only DNS Based Lists

To search DNS blackhole lists then navigate to your browser at:

http://0.0.0.0:5000/snub/dns/{SOME_VALUE_HERE}

Search only static items in your text.static.yml

To search only your static list then navigate to your browser at:

http://0.0.0.0:5000/snub/static/{SOME_VALUE_HERE}

This will return any information found about the value you are searching for.