Ninja

A general-purpose fully customizable software to control a remote computer behind any NAT, Firewall and proxy. Providing secure shell access, file transfer and shell stream (stream shell output from remote to a local file). Ninja has no prerequisites, you can just download the release and use it right away!

Please note that Ninja is the host and executor of commands, so it will be running on the target (remote) computer. You will need Jonin on the controller (commander) computer to connect to your Ninjas and command them.

Overview

Ninja is a portable remote computer control software. Once it's run on a remote computer, it will provide you shell access, file transfer (upload/download), and shell stream. There's no need to open ports on the remote computer; even if it uses a cellular data network and is behind proxies, there will be no problem connecting since Ninja won't listen on a port for connections and instead will ask the controller or the Jonin computer for a connection (WebSocket if available, otherwise XHR polling). So the controller computer should be running Jonin and have the required port open.

• Automatic Deployment / Installation on Target
• Features
• Download
• Demo
• Platforms
• Jonin
• Setup
  • Fix No Ninjas Error
• Configuration File
• Host Setup
  • ngrok
  • Dynamic DNS
  • VPS
  • Static IP Address
  • Domain Name
• Use As Spyware
• Source Code

Automatic Deployment / Installation on Target

Deploy to Linux

Use these scripts to deploy, install, and run Ninja on a Linux target machine in the background (using PM2). Run deploy.bat from Windows or deploy.sh from Linux/macOS:

cd deployment

# from Windows
deploy.bat JONIN_HOST TARGET_USER TARGET_HOST [PASSWORD]

# from Linux / macOS
./deploy.sh JONIN_HOST TARGET_USER TARGET_HOST [PASSWORD]

• JONIN_HOST — publicly accessible address of the machine running Jonin (automatically written to Ninja's HOST config)
• TARGET_USER — SSH user on the target Linux machine
• TARGET_HOST — IP or hostname of the target Linux machine
• PASSWORD — optional; omit to use SSH key authentication (requires sshpass when provided)

Make sure to use a publicly accessible IP address or hostname for JONIN_HOST, otherwise you won't be able to talk to the Ninja using Jonin.

Windows

You can use this single-click installer (which uses Servicifier) on Windows:

windows single click installer

Please note that you should still change HOST and PORT in the Ninja config file as explained in Setup (for this installer, it will be in files/config/constants.json) before you use the installer. Also note that this installer will install Ninja in C:/Ninja and name the service ninja.exe. To customize this, you can change the installation config file in config/installation-config.json (check here for installation config format). To make the installer ask for installation config values when you run it, instead of automatically using the config file, you can simply remove the installation config file.

Features

• Secure shell access to remote (Ninja) computer
• File upload/download (Multiple files at once) to/from remote (Ninja)
• Shell stream, run command on remote (Ninja) and stream output to a file on local (Jonin)

Download

You can download the latest release from here

Demo

demo.mp4

Platforms

Windows 10 ✔	macOS 12 Monterey ✔	Parrot OS 4.11.2 ✔

Jonin

Jonin is the pair for Ninja which can control (order!) multiple Ninja instances. You'll need to use it on the controller computer in order to communicate with a Ninja

Setup

Follow these steps to setup Jonin and Ninja:

• Download Jonin Release and Ninja Release
• Change PORT in config/constants.json for both Ninja and Jonin; the ports should be the same. Please read this guide about how to set up HOST so you never lose access to Ninja
• Expose Jonin to the internet — either with ngrok (easiest) or by forwarding the configured port on Jonin's router (guide from No-IP)
• Done! Now run Ninja on the target/remote computer, run Jonin on controller/local computer and wait for some report from your Ninja !

For usage guide and list of commands, check here

Note: NO_LOG in the config file SHOULD be set to true when you want to use Ninja as a service, otherwise the log file might grow forever (up to the limit).

Fix No Ninjas Error

If you did everything above and got No Ninjas, then the chances are your ISP is putting you behind a NAT. To check this, you can find your router's WAN IP address (can be found on the router's homepage) and then compare it to the actual IP address that you have on the internet (can be found by searching my ip on Google); if these IP addresses are NOT identical, then your router is behind a NAT. To fix this, you should ask your ISP to change your NAT type to OPEN.

Configuration File

You can find this file in config/constants.json:

{
  // connection port
  "PORTS": {
    "DATA": 3707
  },

  // name to identify Ninja on Jonin when working with multiple Ninjas
  "NAME": "Ninja's Name",

  // Jonin computer's address
  "HOST": "domain.com",

  // connection config. any valid Socket.io option
  "CONNECTION": {
    "RECONNECTION_DELAY_MAX": 5000,
    "RECONNECTION_DELAY": 1000,
    "TIMEOUT": 20000,

    "rejectUnauthorized": false
  },

  // interval in which file receiver party will send ack to sender
  "FILE_TRANSFER": {
    "ACK_INTERVAL": 2000
  },

  // stop logging, this SHOULD be set to true when you want to use Ninja
  // as a service; otherwise, the log file might grow larger forever
  // (or up to the limit)
  "NO_LOG": false,

  "PROGRESS_BAR": {
    // progress bar colors
    "COLOR_MAP": {
      "FAILED": ["red", "red"],
      "INVALID": ["red", "red"],
      "DONE": ["gray", "green"],
      "IN_PROGRESS": ["gray", "cyan"]
    },
    // progress bar name/label maximum length
    "MAX_NAME_LENGTH": 10
  }
}

Host Setup

When configuring Ninja, you should use a HOST that points to the Jonin computer and will always be available. So you'll have to use one of the following options:

Dynamic DNS

This is the best free option for a permanent setup when you can port-forward. You just need to create an account with one of the DDNS services (like Duck DNS and No-Ip), create a domain name, and set it to point to your dynamic IP address. If your ISP changes your IP, then simply change it on the DDNS website or install a Dynamic Update Client (DUC) to do this for you automatically.

ngrok

This is the easiest way to get started, especially if you can't port-forward (e.g. CGNAT) or just want to try things quickly. Since Ninja connects outbound to Jonin, you run ngrok on the machine where Jonin is listening and tunnel Jonin's port to a public URL. ngrok supports the WebSocket and XHR polling that Socket.io uses, so no extra tunnel configuration is needed.

1. Start Jonin on your controller machine (default port 3707).

2. In another terminal, run:

   ngrok http 3707

   (Replace 3707 with your PORTS.DATA value if you changed it.)

3. Copy the ngrok hostname (e.g. abc123.ngrok-free.app) — without https://.

4. In Ninja's config/constants.json:

   • Set HOST to that ngrok hostname.
   • Set PORTS.DATA to 443 (ngrok exposes the tunnel over HTTPS on port 443).

Jonin keeps listening on its local port (3707); only Ninja's config changes to reach it through the tunnel.

Downside: on the free tier, the ngrok URL changes every time you restart the tunnel, so you must update Ninja's HOST (or redeploy with a new JONIN_HOST) after each restart. For a permanent setup, use one of the options below instead. The tunnel must also stay running whenever you want Ninjas to connect.

VPS

You can purchase a VPS and use its IP or hostname as HOST in the config file. However, you'll always have to control your Ninjas from this VPS. Another downside is that this is paid.

Static IP Address

You can use an IP address for your Jonin and set this IP in Ninja's configuration. This is not recommended since you'll have to spend money while there are easy free ways, unless you already have a static IP.

Domain Name

Just like a static IP, you can use a domain name for your Jonin and set this name in Ninja's configuration. For the same reason as a static IP, this is also not a recommended way.

Use As Spyware

Please note that Ninja can be easily used as spyware, especially when installed as a service; it will open full access to the target computer for the Jonin controlling it. So use it carefully and don't leave the Ninja process running on a computer that is connected to the internet.

Source Code

Source code will be open soon, after some refactoring and improvements.