Skip to content
🔎 Python framework to automatically discover and enumerate hosts from different back-end systems
Branch: master
Clone or download
manmolecular Merge pull request #12 from sdnewhop/develop
Set Nmap workers with argument
Latest commit ac1e455 Apr 20, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
additional_queries Basic Nmap support while scanning Mar 27, 2019
grinder Set Nmap workers with argument Apr 20, 2019
map
tests
.gitignore
LICENSE Upload files Mar 14, 2019
README.md Update documentation and requirements Mar 27, 2019
grinder.py
queries.json Add basic confidence level support Apr 20, 2019
requirements.txt
screenshot.png Link Censys connector with Grinder core Mar 14, 2019

README.md

grinder

Internet-connected Devices Census Python Framework Grinder Screenshot

Description

The Grinder framework was created to automatically enumerate and fingerprint different hosts on the Internet using different back-end systems: search engines, such as Shodan or Censys, for discovering hosts and NMAP engine for fingerprinting and specific checks. The Grinder framework can be used in many different areas of researches, as a connected Python module in your own project or as an independent ready-to-use from the box tool.

Requirements

  • Python 3.6+
  • Shodan and Censys accounts

Current features

Grinder Development Project

Setup and configure environment

  1. Clone the repository
git clone https://github.com/sdnewhop/grinder
  1. Create virtual environment
cd grinder
python3 -m venv grindervenv
source grindervenv/bin/activate
  1. Check if virtual environment successfully loaded
which python
which pip
  1. Install project requirements in virtual environment
pip3 install -r requirements.txt
  1. Run the script
./grinder.py -h
  1. Set your Shodan and Censys keys via a command line argument
./grinder.py -sk YOUR_SHODAN_KEY -ci YOUR_CENSYS_ID -cs YOUR_CENSYS_SECRET

or via an environment variable

export SHODAN_API_KEY=YOUR_SHODAN_API_KEY_HERE
export CENSYS_API_ID=YOUR_CENSYS_API_ID_HERE
export CENSYS_API_SECRET=YOUR_CENSYS_API_SECRET_HERE
  1. Deactivate virtual environment after use and restore default python interpreter
deactivate

Usage

usage: grinder.py [-h] [-r] [-u] [-q QUERIES_FILE] [-sk SHODAN_KEY] [-cu]
                  [-cp] [-ci CENSYS_ID] [-cs CENSYS_SECRET] [-cm CENSYS_MAX]
                  [-nm]

The Grinder framework was created to automatically enumerate and fingerprint
different hosts on the Internet using different back-end systems

optional arguments:
  -h, --help            show this help message and exit
  -r, --run             Run scanning
  -u, --update-markers  Update map markers
  -q QUERIES_FILE, --queries-file QUERIES_FILE
                        JSON File with Shodan queries
  -sk SHODAN_KEY, --shodan-key SHODAN_KEY
                        Shodan API key
  -cu, --count-unique   Count unique entities
  -cp, --create-plots   Create graphic plots
  -ci CENSYS_ID, --censys-id CENSYS_ID
                        Censys API ID key
  -cs CENSYS_SECRET, --censys-secret CENSYS_SECRET
                        Censys API SECRET key
  -cm CENSYS_MAX, --censys-max CENSYS_MAX
                        Censys default maximum results quantity
  -nm, --nmap-scan      Initiate Nmap scanning

Tests

You can run tests from root grinder directory with command

pytest

Examples

Run an enumeration with Nmap scanning, where maximum Censys results is 555 hosts per query, update map markers, count unique entities and create plots

./grinder.py -sk YOUR_SHODAN_API_KEY_HERE -ci YOUR_CENSYS_ID -cs YOUR_CENSYS_SECRET -u -q queries.json -cu -cp -cm 555 -nm -r 

For more options and help use

./grinder.py -h
You can’t perform that action at this time.