Add SD-WAN Harvester files

Author: manmolecular

.gitignore

@@ -0,0 +1,5 @@
+.env
+results
+harvester/.env
+harvester/results
+harvester/__pycache__

LICENSE

@@ -1,4 +1,91 @@
 # SD-WAN Harvester
 
 `SD-WAN Harvester` tool was created to automatically enumerate and fingerprint SD-WAN nodes on the Internet. 
-It uses Shodan as a search engine and another custom tools like NMAP NSE scripts, masscan checks, etc.
+It uses Shodan search engine for discovering, NMAP NSE scripts for fingerprinting, and masscan to implement some specific checks.
+
+## Requirements
+`SD-WAN Harvester` requires [Python 3.6](https://www.python.org/getit/) or later and [Nmap](https://nmap.org/download.html).
+
+You also need an Shodan API key.
+
+## Installation
+1. Clone the repository:
+```
+git clone https://github.com/sdnewhop/sdwan-harvester.git
+```
+2. Install `pip` requirements:
+```
+python3.6 -m pip install -r requirements.txt
+```
+3. Run the script:
+```
+python3.6 harvester.py -h
+```
+4. Set your Shodan key via a command line argument
+```
+./harvester.py -sk YOUR_SHODAN_KEY
+```
+or via an environment variable
+```
+export SHODAN_API_KEY=YOUR_API_KEY_HERE
+./harvester.py (without -sk key)
+```
+
+## Usage
+### Command Line Arguments
+1. `-h, --help` - show the help message and exit.  
+
+2. `-sk SHODAN_KEY, --shodan-key SHODAN_KEY` - set a Shodan API key.
+
+3. `-n, --new` - initiate a new discovery using Shodan.  
+
+4. `-q QUERIES, --queries QUERIES` - specify the file containing SD-WAN queries and filters for Shodan.
+*Default value is `shodan_queries.json`.*
+
+5. `-d DESTINATION, --destination DESTINATION` - the directory where results will be stored.
+*Default value is `results`.*
+
+6. `-C CONFIDENCE, --confidence CONFIDENCE` - set the confidence level (`certain`, `firm`, or `tentative`).  
+*Default value is `certain`.*
+
+7. `-v [VULNERS [VULNERS ...]], --vulners [VULNERS [VULNERS ...]]` - the list of venodrs checked by Shodan vulnerability scanner. For example, `--- vulners silver peak, arista, talari` command starts finding of known vulnerabilities for `silver peak`, `arista` and `talari` products. Use `--vulners all` to run scanning for all vendors.
+*By default, Shodan vulnerability scanning is turned off.*
+
+8. `-mv MAX_VENDORS, --max-vendors MAX_VENDORS` - the Maximum Number of Vendors shown in reports.  
+*Default value is `10`.*
+
+9. `-mc MAX_COUNTRIES, --max-countries MAX_COUNTRIES` - the Maximum Number of Countries shown in reports.
+*Default value is `10`.*
+
+10. `-maxv MAX_VULNERS, --max-vulners MAX_VULNERS` - the Maximum Number of Vulnerabilities shown in reports.  
+*Default value is `10`.*
+
+### Examples
+Show help 
+```
+python3.6 harvester.py -h
+```
+Run an enumeration
+```
+python3.6 harvester.py -sk YOUR_API_KEY -n
+```
+Run an enumeration with `firm` level of confidence
+```
+python3.6 harvester.py -sk YOUR_API_KEY -n -c firm
+```
+Run a vulnerability scan against `talari` vendor
+```
+python3.6 harvester.py -sk YOUR_API_KEY -n -v talari
+```
+Run a new vulnerability scan for all vendors. The Maximum Number of Vendors is 8, the Maximum Number of Countries is 8, and the Maximum Number of CVEs is 8
+```
+python3.6 harvester.py -sk YOUR_API_KEY -n -v all -mv 8 -mc 8 -maxv 8
+```
+Run a new scan with all features enabled
+```
+ python3.6harvester.py -sk YOUR_API_KEY -n -v all -c all
+```
+Process data from previous scan results (for example, if you want to build new charts and graphics containing fewer vendors, countries, or vulners.)
+```
+ python3.6 harvester.py -v -mv <num> -mc <num> -maxv <num>
+```

README.md

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+
+import argparse
+import os
+import sys
+
+import harvester.core as core
+
+# Default input file with queries
+core.QUERIES_JSON_FILE = "shodan_queries.json"
+
+# Default confidence level
+core.DEFAULT_CONFIDENCE = "certain"
+
+# Default quantity of results
+core.MAX_COUNTRIES = 10
+core.MAX_VENDORS = 10
+core.MAX_VULNERS = 10
+
+# Default paths and directories
+core.NMAP_SCRIPTS_PATH = "nse-scripts"
+core.RESULTS_DIR = "results"
+
+
+def get_key_from_env():
+    """
+    Get Shodan API Key from environment variable
+
+    :return: Shodan API key from env variable (str)
+    """
+    try:
+        shodan_api_key = os.environ['SHODAN_API_KEY']
+        return shodan_api_key
+    except KeyError:
+        print(
+            'Please set the environment variable SHODAN_API_KEY or use -sk key')
+        sys.exit(1)
+
+
+def main():
+    """
+    Main interface for harvester core
+
+    :return: None
+    """
+    if sys.version_info < (3, 6):
+        print('Required python version is 3.6 or greater')
+        sys.exit(1)
+
+    if len(sys.argv) == 1:
+        print(
+            "Usage: '{script_name} -h' for help".format(
+                script_name=sys.argv[0]))
+        sys.exit(1)
+
+    parser = argparse.ArgumentParser(description=".")
+    parser.add_argument("-sk", "--shodan-key", action="store",
+                        default=None, help="Shodan API key")
+    parser.add_argument("-n", "--new", action="store_true",
+                        help="New scan in shodan")
+    parser.add_argument("-q", "--queries", action="store",
+                        default=core.QUERIES_JSON_FILE,
+                        help="File with queries")
+    parser.add_argument("-d", "--destination", action="store",
+                        default=core.RESULTS_DIR, help="Destination directory")
+    parser.add_argument("-c", "--confidence", default=core.DEFAULT_CONFIDENCE,
+                        action="store", help="""Confidence level. Available
+                                                levels: certain, firm,
+                                                tentative""")
+    parser.add_argument("-v", "--vulners", action="store", nargs='*',
+                        help="""List of vendors for vulners scan, e.g., 
+                                '--vulners silver peak, arista, talari'.  
+                                Use '--vulners all' to include all vendors 
+                                in statistics.""")
+    parser.add_argument("-mv", "--max-vendors", default=core.MAX_VENDORS, type=int,
+                        action="store",
+                        help="Max number of vendors in statistics")
+    parser.add_argument("-mc", "--max-countries", default=core.MAX_COUNTRIES,
+                        type=int,
+                        action="store",
+                        help="Max number of countries in statistics")
+    parser.add_argument("-maxv", "--max-vulners", default=core.MAX_VULNERS,
+                        type=int, action="store",
+                        help="Max number of vulners in statistics")
+    args = parser.parse_args()
+
+    # Try to get key from environment if it was not passed with CLI
+    if not args.shodan_key and args.new is True:
+        args.shodan_key = get_key_from_env()
+
+    # Check confidence level
+    if args.confidence.lower() not in ['certain', 'firm', 'tentative']:
+        print('Wrong confidence level. Use -h key for help.')
+        sys.exit(1)
+
+    # Run harvester
+    core.run(args)
+
+
+if __name__ == '__main__':
+    main()