tsalkenov/PortQatyran

Automated network scanner for hunting IPs and port changes

Automated network scanner for hunting IPs and port changes

What is this?

PortQatyran is an automated network scanner designed to hunt for IP and port changes. Based on the rustscan scanner, it efficiently scans networks for open ports, logs executed commands, and sends notifications in chat via Telegram about the scan results. The tool is highly configurable, allowing users to set scanning frequencies and manually initiate scans.

Why "PortQatyran"?

The name "PortQatyran" is inspired by the Kazakh word for shark "qatyran" symbolizing its efficiency and speed in detecting network changes. The logo represents an RJ-45 connector with a shark face, which is usually used to connect equipment ports.

Features

• Fast Network Scanning: Quickly scans networks for open port IP addresses
• Scheduling: Set the scanning frequency using cron jobs
• Sandboxed Application: Runs in a secure, isolated environment
• Logging: Logs all executed commands for auditing.
• Easy Setup: Simple configuration via environment files.
• Configuration Display: Shows tool configuration with the qatyranfetch command.
• Manual Scanning: Initiate scans manually using the portqatyran command.
• Telegram Notifications: Sends scan results via Telegram.
• Notification Modes: Supports aggresive and passive notification modes.

Tools and libraries

• Bash
• Rustscan
• Cron
• Curl
• Nmap
• Debian 12
• Docker
• Docker Compose

Modes

• Aggresive: Sends all ip addresses and ports after each scan
• Passive: Sends only ip addresses and ports that have not been found before

Usage

• Clone the repository:

git clone https://github.com/LaggerIsME/PortQatyran.git

• Download and install a Docker: https://docs.docker.com/engine/install/
• Create a bot in Telegram and get a TELEGRAM_BOT_TOKEN from @BotFather
• Also in chat with @BotFather write: /setprivacy and set DISABLE mode
• Get TELEGRAM_CHAT_ID for notifications by adding @my_id_bot in chat
• Move to the ~/PortQatyran/ directory:

cd PortQatyran

• Copy the example.env to .env:

cp example.env .env

• Configure variables in .env file:

# Timezone settings
DEFAULT_TIMEZONE="Asia/Almaty"

# Rustscan settings
# Could be "random" or "serial"
SCAN_MODE="serial"
# Number of ports to scan at once
BATCH_SIZE=1000
# IP Addreses for scan. Write without spaces.
PREY_IPS="127.0.0.1,192.168.124.200"
# Set Only Ports or Port Range
# Ports. Write without spaces
#PORTS="80,443,5432"
# Port range
PORT_RANGE="0-65535"
# Exlude ports. Write without spaces.
EXCLUDE_PORTS=""

# PortQatyran settings.
# Could be "aggresive". In future will be "passive"
NOTIFICATION_MODE="passive"
TELEGRAM_BOT_TOKEN=""
TELEGRAM_CHAT_ID=""

# Directory path
RAW_OUTPUT_FILE="/tmp/output.txt"
APP_LOG_FILE="/var/log/portqatyran.log"
APP_DB_PATH="/app/db/"
TMP_LOG_FILE="/tmp/portqatyran.log"
TMP_DB_PATH="/tmp/db/"

• Move to the ~/PortQatyran/network_scanner/ directory:

cd network_scanner/

• Configure schedule in auto.cronjob file:

# For example: every 2 minutes run portqatyran
*/2 * * * * /bin/bash -l -c "/app/scripts/main.sh $NOTIFICATION_MODE"

• Move to the ~/PortQatyran/ directory:

cd ~/PortQatyran

• Build and Run with Docker Compose:

docker compose up -d --build

After all these actions, the bot will send a message with the PortQatyran configuration to the chat you specified

Commands

• Show PortQatyran configuration:

docker exec portqatyran qatyranfetch

• Manually run scanner:

docker exec portqatyran portqatyran

About us

• Tool creator: LaggerIsME (@LaggerIsME | LinkedIn)
• Logo designer: NoyanTM (@NoyanTM | LinkedIn)

License

PortQatyran is licensed under the GNU General Public License v3.0