Simple CLI port scanner

pip install port-eye==0.2.1



Build Status codecov code style License: MIT

Simple CLI wrapper around nmap to perform port scanning in Python

Note: This software is indended for legitimate use only.


  • Scanning of IPV4, IPV6 hosts and CIDR blocks.
  • Parsing of hosts from input file.
  • Automated generation of reports in HTML format.
  • Parallel scanning for increased performance.
  • Optional Docker-based execution.

Example command:

$ port-eye -t -o report.html

Output html file example:

Example output


This application is compatible with Python 2.7 and Python 3.5+.

Docker installation

If you have Docker installed, you can pull the image from Docker-Hub:

docker pull ahugues/port-eye

You can also build the image by cloning the repository and running:

docker build -t port-eye .


You need to install nmap on your machine for the application to work (unless you choose the Docker install.)

Example on Ubuntu:

sudo apt update
sudo apt install nmap

Example on Arch

sudo pacman -S nmap

Example on Mac with Homebrew

brew install nmap

Install with pypi

If you have Python 2.7 or 3.5+ installed, you can install port-eye from PyPI:

pip install port-eye

or locally by clonning the repository and running:

pip install .


General notes

port-eye exposes a command line executable named port-eye

When run without any option, port-eye will simply display the help message.

Input hosts can be inputed from the CLI with the option -t or --target. Inputted hosts can be IPV4 and 6 as well as CIDR blocks.

Hosts can be added from an input file in which hosts are put line by line. Example:

If using Docker, and assuming you are working in a certain directory, you can run a port-eye container using:

docker run -v "$(pwd)":/files port-eye <options>

Or if built locally

docker run -v "$(pwd)":/files port-eye <options>

CLI reference

Usage: port-eye [OPTIONS]

  Run the main application from arguments provided in the CLI.

  -t, --target TEXT   Target host (IPV4, IPV6 or CIDR
  -f, --file PATH     File containing the hosts to check
  -o, --output PATH   Output HTML file into which the results must be stored
  -s, --sudo          Run nmap as privileged user for more accurate scanning
  -d, --debug         Display debug information to the terminal
  -m, --mock          Use mock API instead of really running nmap
  -j, --jobs INTEGER  Max number of concurrent scans (default 4)
  -h, --help          Show this message and exit.


Contributions are closed at the moment.