Skip to content

API Reference.md

Jump to bottom
IOTechnology edited this page Jan 24, 2026 · 1 revision

API Reference

Complete documentation of the KittySploit Framework REST API.

Overview

The REST API allows you to control the framework programmatically without using the CLI interface. It is based on Flask and supports JSON.

Starting the API Server

python kittyapi.py -H <host> -p <port> -m <master_key>

Examples:

# Listen on all interfaces, port 5000
python kittyapi.py -H 0.0.0.0 -p 5000 -m "my_secret_key"

# Listen only on localhost
python kittyapi.py -H 127.0.0.1 -p 5000 -m "my_secret_key"

Authentication

All requests require an API key in the header:

X-API-Key: <master_key>

Endpoints

Base URL

http://<host>:<port>/api

Modules

List Modules

GET /api/modules

Response:

{
  "modules": {
    "exploits": [...],
    "auxiliary": [...],
    "payloads": [...]
  }
}

Get a Module

GET /api/modules/<module_path>

Example:

GET /api/modules/exploits/http/wordpress_rce

Load a Module

POST /api/modules/use
Content-Type: application/json

{
  "module_path": "exploits/http/wordpress_rce"
}

Get Module Options

GET /api/modules/options

Response:

{
  "options": {
    "RHOST": ["", true, "Target host", false],
    "RPORT": [80, true, "Target port", false]
  }
}

Set an Option

POST /api/modules/set
Content-Type: application/json

{
  "option": "RHOST",
  "value": "192.168.1.100"
}

Execute a Module

POST /api/modules/run

Response:

{
  "success": true,
  "message": "Module executed successfully",
  "session_id": "session_123" // If a session is created
}

Sessions

List Sessions

GET /api/sessions

Response:

{
  "sessions": [
    {
      "id": "session_1",
      "type": "shell",
      "target": "192.168.1.100:4444",
      "info": "..."
    }
  ]
}

Get a Session

GET /api/sessions/<session_id>

Interact with a Session

POST /api/sessions/<session_id>/interact
Content-Type: application/json

{
  "command": "whoami"
}

Response:

{
  "output": "root\n"
}

Execute a Command in a Session

POST /api/sessions/<session_id>/execute
Content-Type: application/json

{
  "command": "ls -la"
}

Close a Session

DELETE /api/sessions/<session_id>

Listeners

List Listeners

GET /api/listeners

Start a Listener

POST /api/listeners/start
Content-Type: application/json

{
  "module_path": "listeners/multi/reverse_tcp",
  "options": {
    "LHOST": "192.168.1.50",
    "LPORT": 4444
  }
}

Stop a Listener

POST /api/listeners/<listener_id>/stop

Workspaces

List Workspaces

GET /api/workspaces

Create a Workspace

POST /api/workspaces
Content-Type: application/json

{
  "name": "project1"
}

Switch Workspace

POST /api/workspaces/switch
Content-Type: application/json

{
  "name": "project1"
}

Delete a Workspace

DELETE /api/workspaces/<name>

Database

Get Hosts

GET /api/db/hosts

Add a Host

POST /api/db/hosts
Content-Type: application/json

{
  "address": "192.168.1.100",
  "os": "Linux"
}

Get Vulnerabilities

GET /api/db/vulns

Streaming

Stream Events

GET /api/stream

Returns a Server-Sent Events (SSE) stream with real-time events.

Interpreter

Execute CLI Command

POST /api/interpreter/execute
Content-Type: application/json

{
  "command": "use exploits/http/wordpress_rce"
}

Response:

{
  "output": "...",
  "success": true
}

Usage Examples

Python

import requests

API_URL = "http://localhost:5000/api"
API_KEY = "my_secret_key"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Load a module
response = requests.post(
    f"{API_URL}/modules/use",
    headers=headers,
    json={"module_path": "exploits/http/wordpress_rce"}
)

# Configure options
requests.post(
    f"{API_URL}/modules/set",
    headers=headers,
    json={"option": "RHOST", "value": "192.168.1.100"}
)

# Execute
response = requests.post(f"{API_URL}/modules/run", headers=headers)
print(response.json())

cURL

# Load a module
curl -X POST http://localhost:5000/api/modules/use \
  -H "X-API-Key: my_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"module_path": "exploits/http/wordpress_rce"}'

# Set an option
curl -X POST http://localhost:5000/api/modules/set \
  -H "X-API-Key: my_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"option": "RHOST", "value": "192.168.1.100"}'

# Execute
curl -X POST http://localhost:5000/api/modules/run \
  -H "X-API-Key: my_secret_key"

JavaScript (Node.js)

const axios = require('axios');

const API_URL = 'http://localhost:5000/api';
const API_KEY = 'my_secret_key';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json'
};

// Load a module
axios.post(`${API_URL}/modules/use`, {
  module_path: 'exploits/http/wordpress_rce'
}, { headers })
  .then(() => {
    // Configure options
    return axios.post(`${API_URL}/modules/set`, {
      option: 'RHOST',
      value: '192.168.1.100'
    }, { headers });
  })
  .then(() => {
    // Execute
    return axios.post(`${API_URL}/modules/run`, {}, { headers });
  })
  .then(response => {
    console.log(response.data);
  });

Response Codes

  • 200 OK - Success
  • 201 Created - Resource created
  • 400 Bad Request - Invalid request
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

Error Format

{
  "error": "Error message",
  "code": 400
}

WebSockets

Some features use WebSockets for real-time communication:

const ws = new WebSocket('ws://localhost:5000/api/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

Rate Limiting

The API may implement rate limiting to prevent abuse. Check the documentation specific to your version.

Security

  • Always use HTTPS in production
  • Protect your API key - Never share it
  • Use strong keys - Generate random keys
  • Limit network access - Use a firewall

Next Steps

Note: This reference may not include all endpoints. Check the source code for the complete list.

Clone this wiki locally