Plugins and External Integrations

Plugins are Python extensions loaded from plugins/. They complement catalog modules without modifying the framework core. Unlike use/run modules, plugins orchestrate third-party tools, multi-module workflows, or local services (TCP listener, ngrok tunnel, integrated Metasploit console).

Plugin architecture

Location and discovery

Each plugin is a plugins/<name>.py file defining a class inheriting from Plugin with an __info__ dictionary:

• name --- short identifier (e.g. ngrok).
• description --- summary displayed by plugin list.
• version, author.
• dependencies --- optional Python packages (pyngrok, requests…).

The plugin_manager automatically discovers files at startup. The plugin list command reads metadata without importing the code (AST analysis), which avoids side effects during simple listing.

Flow diagram

  kittyconsole
       |
       |  plugin run <name> [args]
       v
  +------------------+
  | plugin_manager   |
  | execute_plugin() |
  +------------------+
       |
       |  import plugins/<name>.py
       v
  +------------------+
  | Plugin.run(args) |
  +------------------+
       |
       +---> framework (modules, sessions, jobs)
       +---> external tools (msfconsole, ngrok, KittyOSINT)

plugin run convention

General syntax:

plugin run <plugin_name> [plugin arguments]

Plugins using ModuleArgumentParser accept GNU-style options. When options start with -, use the -- separator if the console requires it:

plugin run nextjs -- -l
plugin run nextjs -- -t http://127.0.0.1:3000 --ssl
plugin run web_vuln_scanner -- -u https://target.local --stealth

plugin command --- complete reference

Listing and search

plugin
plugin list
plugin search tunnel
plugin search metasploit
plugin search serial
plugin search nextjs
plugin help

plugin search <term> filters on name and description. Useful query examples:

Loading and lifecycle

plugin load ngrok
plugin info ngrok
plugin reload ngrok
plugin unload ngrok

load imports the module into memory; run can load on the fly if needed. reload is handy in development after modifying the source file.

Creating a custom plugin

plugin create mon_plugin "Short extension description"

The command creates the new plugin file under plugins/. Use plugins/example.py as inspiration for the minimal structure (ModuleArgumentParser, run method).

Detailed information

plugin info metasploit
plugin info web_vuln_scanner
plugin info osint

Displays name, version, author, description, and declared dependencies.

Metasploit integration --- msf command

The msf command is a shortcut to the metasploit plugin in integrated context mode. It lets you use use, show, set, run, and back as in Metasploit while retaining access to other KittySploit commands.

Activation and deactivation

msf on
msf off
msf status
msf on --path /opt/metasploit-framework/bin/msfconsole

• msf on --- starts msfconsole in the background and activates integrated mode; the prompt displays the :msf suffix.
• msf off --- deactivates integrated mode without necessarily killing msfconsole.
• msf status --- integrated context and console state.
• --path --- explicit path if msfconsole is not in PATH.

Behavior in integrated mode

Once msf on is active:

use exploits/multi/http/wing_ftp_cve_2026_44403_rce
show options
set RHOSTS 127.0.0.1
set RPORT 21
run
back
.kitty

• Classic Metasploit commands target msfconsole.
• .kitty (dot + kitty) returns to the KittySploit prompt without closing Metasploit.
• KittySploit commands (sessions, workspace, host) remain available outside the msf context.

Equivalent via the plugin

plugin run metasploit context on
plugin run metasploit context off
plugin run metasploit context status
plugin run metasploit console-status
plugin run metasploit detach
plugin run metasploit stop-console

Remote RPC connection

To control Metasploit via its MessagePack API (without interactive console):

plugin run metasploit connect --host 127.0.0.1 --port 55552 \
  --user msf --pass your_password
plugin run metasploit probe --host 127.0.0.1 --port 55552 \
  --user msf --pass your_password
plugin run metasploit status

SSL options:

plugin run metasploit connect --host 127.0.0.1 --port 55552 \
  --user msf --pass secret --ssl
plugin run metasploit connect --host 127.0.0.1 --port 55552 \
  --user msf --pass secret --no-ssl

Successful RPC configuration is persisted in data/metasploit/rpc_config.json.

RPC exploration and execution

plugin run metasploit list exploits
plugin run metasploit list auxiliary
plugin run metasploit search samba
plugin run metasploit info exploits/multi/http/wing_ftp_cve_2026_44403_rce
plugin run metasploit options exploits/multi/http/wing_ftp_cve_2026_44403_rce
plugin run metasploit payloads exploits/multi/http/wing_ftp_cve_2026_44403_rce
plugin run metasploit execute exploits/multi/http/wing_ftp_cve_2026_44403_rce \
  --set RHOSTS=10.10.10.3
plugin run metasploit execute listeners/multi/reverse_tcp \
  --payload payload/windows/meterpreter/reverse_tcp \
  --set LHOST=10.0.0.5 --set LPORT=4444
plugin run metasploit jobs
plugin run metasploit sessions

Classic Metasploit console (non-integrated)

plugin run metasploit shell
plugin run metasploit shell --path /opt/metasploit-framework/bin/msfconsole
plugin run metasploit mode
plugin run metasploit resume

shell temporarily replaces the KittySploit console with msfconsole; on exit, you return to the framework.

Metasploit troubleshooting

• msfconsole not found --- install Metasploit Framework or specify --path.
• RPC 401 --- verify msfrpcd / load msgrpc and credentials.
• Prompt conflict --- msf off then plugin run metasploit stop-console.
• msgpack dependency --- pip install msgpack for the RPC client.

Plugin ngrok --- public tunnels

Exposes a local service (listener, web application) via an ngrok URL. Depends on pyngrok.

Commands

plugin run ngrok -c 8080
plugin run ngrok --create 4444
plugin run ngrok -l
plugin run ngrok --list
plugin run ngrok -d <tunnel_id>
plugin run ngrok -k
plugin run ngrok -s

Scenario --- reverse shell via tunnel

1. Start a listener module such as listeners/multi/reverse_tcp.
2. plugin run ngrok -c 4444 --- note the public URL.
3. Configure a compatible payload, for example payloads/singles/cmd/unix/python_reverse_tcp, with the ngrok host and port.
4. At end of mission: plugin run ngrok -k.

Plugin osint --- open-source reconnaissance

Orchestrates OSINT modules from the console through the repository plugin plugins/osint.py.

Commands

plugin run osint -l
plugin run osint -t example.com
plugin run osint -t 8.8.8.8
plugin run osint -t contact@target.com -v
plugin run osint -t example.com -m domain_whois
plugin run osint example.com

• -l / --list --- lists available OSINT modules.
• -t / --target --- domain, IP, or email.
• -m / --module --- runs a single module by identifier.
• -v / --verbose --- detailed output.

Without -m, all compatible modules run sequentially. Modules prefixed ip_ require IPv4 resolution; the plugin attempts gethostbyname for domains.

OSINT plugin loading

plugin load osint
plugin run osint -l

Plugin router --- tagged modules

Loads and runs all catalog modules tagged router (routers, CPE, administration interfaces).

Commands

plugin run router -l
plugin run router --list
plugin run router -t 192.168.1.1
plugin run router --target 192.168.0.1

-l displays the path, name, and tags of each module. -t runs sequentially each module by setting rhost or target.

Plugin web_vuln_scanner --- orchestrated web scan

Step-based workflow: crawl, passive detectors, active probes (SQLi, XSS, LFI, SSRF), automatic HTTP follow-up modules.

Essential commands

plugin run web_vuln_scanner -- -u https://target.local
plugin run web_vuln_scanner -- -u https://target.local --depth 3 --threads 8
plugin run web_vuln_scanner -- -u https://target.local --no-crawl
plugin run web_vuln_scanner -- -u https://target.local --passive-only
plugin run web_vuln_scanner -- -u https://target.local --aggressive
plugin run web_vuln_scanner -- -u https://target.local --stealth
plugin run web_vuln_scanner -- -u https://target.local --stealth --request-budget 520
plugin run web_vuln_scanner -- -u https://target.local \
  --cookie "session=abc" --user-agent "AuditBot/1.0"
plugin run web_vuln_scanner -- -u https://target.local --report-json /tmp/scan.json

Advanced options

Recommended profiles

• Light reconnaissance --- --passive-only --no-crawl on a specific URL.
• Standard audit --- defaults (--depth 2, --threads 6).
• CI / preprod --- --stealth --request-budget 520.
• Authorized black box --- --aggressive with maintenance window.

Plugin nextjs --- Next.js bundle

Runs all nextjs-tagged modules in one command (recent CVE/GHSA scanners).

Commands

plugin run nextjs -- -l
plugin run nextjs -- -n
plugin run nextjs -- -t 127.0.0.1 --port 3000 --path /
plugin run nextjs -- -t https://app.target.com:443/
plugin run nextjs -- -t 10.0.0.5 --ssl --scanner-only
plugin run nextjs -- -t target.local --auxiliary-only

• -l --- lists nextjs modules.
• -n / --dry-run --- lists without executing.
• -t --- host, IP, or full URL (the plugin extracts scheme, port, path).
• --port --- HTTP(S) port (default 3000).
• --ssl --- forces HTTPS.
• --scanner-only / --auxiliary-only --- exclusive filters.

Combine with search nextjs to discover individual catalog modules.

Plugin minicom --- serial communication

Minicom-style interface for serial ports (/dev/ttyUSB0, COM3), useful for IoT and authorized hardware hacking.

Interactive mode

plugin run minicom

Without arguments, starts an interactive loop: list, connect <port>, help, exit commands.

Command-line mode

plugin run minicom -l
plugin run minicom --list
plugin run minicom -p /dev/ttyUSB0 -b 115200
plugin run minicom --port COM3 --baudrate 9600
plugin run minicom -c

Dependency: pip install pyserial.

Plugin listen --- TCP listener

Minimal netcat-style listener to receive connections and send data interactively.

plugin run listen -p 6000
plugin run listen --port 4444

1. The plugin listens on the indicated port (default 6000).
2. On client connection, type text --- it is sent with a newline.
3. exit closes the connection and stops the listener.
4. Ctrl+C interrupts cleanly.

Classic pairing with a reverse payload or post-exploitation connectivity test.

Plugin default_password --- credentials database

Searches a JSON database of default username/password pairs (routers, NAS, IoT).

plugin run default_password -c
plugin run default_password -s linksys
plugin run default_password -v Cisco
plugin run default_password -u admin
plugin run default_password -p admin

• -c / --count --- total number of entries.
• -s / --search --- global search (product, user, password).
• -v / --vendor --- manufacturer/product filter.
• -u / --username --- login filter.
• -p / --password --- password filter.

Ethical use: cross-reference with search default password for audit modules; never test outside scope.

Minimal skeleton to understand the Plugin API.

plugin run example -m "Hello KittySploit"
plugin run example -m "Test" -c 3
plugin run example --message "Audit" --count 5

• -m / --message --- displayed text.
• -c / --count --- repetitions (default 1).

Reference for plugin create: copy the structure of example.py before adding your business logic.

Quick choice matrix

Integrated scenario --- WebGoat isolated test environment + ngrok

1. lab start webgoat (or equivalent local target).
2. plugin run listen -p 4444 in a dedicated job or terminal.
3. plugin run ngrok -c 4444 --- copy the public URL.
4. Configure the exploit / payload with the ngrok host.
5. After test: plugin run ngrok -k, stop the listener, jobs --kill-all.

Interaction with jobs and workspace

Some plugins launch long-running tasks (web_vuln_scanner, router). Monitor execution:

jobs
jobs --list
jobs --watch

Record results in the current workspace:

workspace use mission-plugins
host add 10.0.0.20
vuln add --host 10.0.0.20 --name "XSS reflected" --severity medium

General plugin troubleshooting

• Missing dependency --- explicit message (pip install pyngrok…).
• Arguments misparsed --- use -- before options; verify plugin run <name> without args for built-in help.
• Plugin not found --- file absent from plugins/ or incorrect name (without .py).
• Silent failure --- plugin info <name> then rerun with -v if the plugin supports it.
• Metasploit conflict --- only one active mode: RPC or integrated console; msf off before plugin run metasploit shell.

Professional best practices

1. Document each plugin run in the mission log (who, when, target).
2. Isolate network plugins (ngrok, listen) on a test VM.
3. Version custom plugins in Git, not only in plugins/.
4. Test with example or plugin create before deploying to the team.
5. Prefer catalog modules for repeatable auditing; reserve plugins for orchestrations and third-party integrations.