.. raw:: html

<h1 align="center">

.. image:: ./pictures/logo.png

.. raw:: html

<br class="title"> Jok3r v3 beta <br>

.. image:: https://img.shields.io/badge/python-3.6-blue.svg :target: https://www.python.org/downloads/release/python-366/ :alt: Python 3.6

.. image:: https://readthedocs.org/projects/jok3r/badge/?version=latest :target: https://jok3r.readthedocs.io/en/latest/ :alt: Documentation ReadTheDocs

.. image:: https://img.shields.io/microbadger/image-size/koutto/jok3r.svg :target: https://hub.docker.com/r/koutto/jok3r/ :alt: Docker Size

.. image:: https://img.shields.io/docker/cloud/build/koutto/jok3r.svg :alt: Docker Build Status

.. raw:: html

</h1> <h3 align="center">Network & Web Pentest Automation Framework</h3> <p align="center"><a href="https://www.jok3r-framework.com/">www.jok3r-framework.com</a></p>

WARNING: Project is still in version 3 BETA. It is still under active development and bugs might be present.

Many tests are going on: see https://github.com/koutto/jok3r/blob/master/tests/TESTS.rst. Ideas, bug reports, contributions are welcome !

.. contents:: :local: :depth: 1

============= Overview

Jok3r is a Python3 CLI application which is aimed at helping penetration testers for network infrastructure and web black-box security tests.

The goal is to save as much time as possible during network/web pentests by automating as many security tests as possible in order to quickly identify low-hanging fruits vulnerabilities, and then spend more time on more interesting and tricky stuff !

It is based upon the observation that there are many hacking open-source tools/scripts (from various sources) targeting common network services available out there, that allow to perform various tasks from fingerprinting to exploitation. Therefore, the idea of Jok3r is to combine those open-source tools in a smart way to get the more relevant results.

============= Features

Pentest Toolbox management

• Selection of Tools: Compilation of 50+ open-source tools & scripts, from various sources.
• Docker-based: Application packaged in a Docker image running Kali OS, available on Docker Hub.
• Ready-to-use: All tools and dependencies installed, just pull the Docker image and run a fresh container.
• Updates made easy: Easily keep the whole toolbox up-to-date by running only one command.
• Easy Customization: Easily add/remove tools from a simple configuration file.

Network Infrastructure Security Assessment

• Many supported Services: Target most common TCP/UDP services (HTTP, FTP, SSH, SMB, Oracle, MS-SQL, MySQL, PostgreSQL, VNC, etc.).
• Combine Power of Tools: Each security check is performed by a tool from the toolbox. Attacks are performed by chaining security checks.
• Context Awareness: Security checks to run are selected and adapted according to the context of the target (i.e. detected technologies, credentials, vulnerabilities, etc.).
• Reconnaissance: Automatic fingerprinting (product detection) of targeted services is performed.
• CVE Lookup: When product names and their versions are detected, a vulnerability lookup is performed on online CVE databases (using Vulners & CVE Details).
• Vulnerability Scanning: Automatically check for common vulnerabilities and attempt to perform some exploitations (auto-pwn).
• Brute-force Attack: Automatically check for default/common credentials on the service and perform dictionnary attack if necessary. Wordlists are optimized according to the targeted services.
• Post-authentication Testing: Automatically perform some post-exploitation checks when valid credentials have been found.

Web Security Assessment

• Large Focus on HTTP: More than 60 different security checks targeting HTTP supported for now.
• Web Technologies Detection: Fingerprinting engine based on Wappalyzer is run prior to security checks, allowing to detect: Programming language, Framework, JS library, CMS, Web & Application Server.
• Server Exploitation: Automatically scan and/or exploit most critical vulnerabilities (e.g. RCE) on web and application servers (e.g. JBoss, Tomcat, Weblogic, Websphere, Jenkins, etc.).
• CMS Vulnerability Scanning: Automatically run vulnerability scanners on most common CMS (Wordpress, Drupal, Joomla, etc.).

Local Database & Reporting

• Local Database: Data related to targets is organized by missions (workspaces) into a local Sqlite database that is kept updated during security testings.
• Metasploit-like Interactive Shell: Access the database through an interactive shell with several built-in commands.
• Import Targets from Nmap: Add targets to a mission either manually or by loading Nmap results.
• Import Targets from Shodan: Add targets to a mission manually from shodan (need shodan API key).
• Access all Results: All outputs from security checks, detected credentials and vulnerabilities are stored into the database and can be accessed easily.
• Reporting: Generate full HTML reports with targets summary, web screenshots and all results from security testing.

============ Demos

• Example 1: Scan a JAVA-RMI (JMX) service:

.. image:: pictures/video-01.png :target: https://www.youtube.com/watch?v=FlbeBj5FPtI

• Example 2: Scan a Joomla website:

.. image:: pictures/video-02.png :target: https://www.youtube.com/watch?v=z4cf_8EQ59Q

============ Architecture

.. image:: ./pictures/visio/architecture/jok3r-architecture.png :alt: Jok3r architecture

.. image:: ./pictures/visio/flowchart/jok3r-flow-chart.svg :width: 700px :alt: Jok3r flowchart

============ Installation

IMPORTANT: The recommended way to use Jok3r is by pulling the Docker Image so you will not have to worry about dependencies issues and installing the various hacking tools of the toolbox. Everything is tested from the Docker container available on Docker Hub !

.. image:: https://raw.githubusercontent.com/koutto/jok3r/master/pictures/docker-logo.png

A Docker image is available on Docker Hub and automatically re-built at each update: https://hub.docker.com/r/koutto/jok3r/. It is initially based on official Kali Linux Docker image (kalilinux/kali-linux-docker).

.. image:: https://images.microbadger.com/badges/image/koutto/jok3r.svg :target: https://microbadger.com/images/koutto/jok3r :alt: Docker Image size

1. Pull Jok3r Docker Image:

   .. code-block:: console

    sudo docker pull koutto/jok3r
   

2. Run fresh Docker container:

   .. code-block:: console

    sudo docker run -i -t --name jok3r-container -w /root/jok3r -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --shm-size 2g --net=host koutto/jok3r
   

Notes:

• -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix is required in order to be able to start GUI applicationfrom the Docker container (e.g. open web browser to read reports). It requires running xhost +local:root on the host.

• --shm-size 2g is used to increase the size of the shared memory, it is required to avoid crashs of web browser when reading reports from the Docker container.

• --net=host is required to share host's interface. It is needed for reverse connections (e.g. Ping to container when testing for RCE, Getting a reverse shell)

3. To re-run a stopped container:

   .. code-block:: console

    sudo docker start -i jok3r-container
   

4. To open multiple shells inside the container:

   .. code-block:: console

    sudo docker exec -it jok3r-container bash
   

============ Update

In order to update, just pull the latest Docker Image from Docker Hub and run a fresh container from this new image:

.. code-block:: console

sudo docker pull koutto/jok3r
sudo docker run -i -t --name jok3r-container-updated -w /root/jok3r -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --shm-size 2g --net=host koutto/jok3r

Note: Of course, you can retrieve your local database local.db (with your saved missions, targets...) from an old container by using the command sudo docker cp.

==================== Quick usage examples

Pentest Toolbox management

• Show all the tools in the toolbox:

.. code-block:: console

python3 jok3r.py toolbox --show-all

• Install all the tools in the toolbox (already done in Docker container):

.. code-block:: console

python3 jok3r.py toolbox --install-all --auto

• Update all the tools in the toolbox and prompt each time to check update:

.. code-block:: console

python3 jok3r.py toolbox --update-all

• Update all the tools in the toolbox without any prompt:

.. code-block:: console

python3 jok3r.py toolbox --update-all --auto

Information

• List supported services:

.. code-block:: console

python3 jok3r.py info --services

• Show security checks for a given service:

.. code-block:: console

python3 jok3r.py info --checks <service>

• Show supported attack profiles for a given service:

.. code-block:: console

python3 jok3r.py info --attack-profiles <service>

• Show supported products for all services:

.. code-block:: console

python3 jok3r.py info --products

Security Testing

Create a new mission in local database:

.. code-block:: console

python3 jok3r.py db

jok3rdb[default]> mission -a mayhem

[+] Mission "mayhem" successfully added
[*] Selected mission is now mayhem

jok3rdb[mayhem]> 

Single target:

• Run all security checks against an URL in interactive mode and add results to the "mayhem" mission:

.. code-block:: console

python3 jok3r.py attack -t https://www.example.com/ --add2db mayhem

• Run security checks