API, RPC, External Portal, and Access Security

KittySploit is not limited to kittyconsole. Programmatic interfaces enable CI/CD automation, SIEM integration, and AI assistants through MCP. This chapter documents API surface import, REST/XML-RPC exposure, and deployment hardening.

External Ecosystem Overview

  Sources                    Framework                 Destinations
  ---------                  ---------                 ------------

openapi.json ----+
  graphql.json ----+        +-------------+
  traffic.har -----+---->   | KittySploit | ----+
                   |        |  Framework  |     |
                   |        +------+------+     +----> kittyapi (REST :5000)
                   |               |          |
                   |        api_import         +----> kittyrpc (XML-RPC :8888)
                   |               |          |
                   +-- modules/    |          +----> kittymcp_server (MCP)
                      generated/   |
                                   v
                            api_security.py
                            (RBAC, tokens, limits)

api_import Command

api_import transforms an API description or traffic capture into KittySploit modules (scanners, fuzzers) via ApiModuleGenerator.

Syntax

api_import <source_file> [options]
api_import openapi.json
api_import swagger.yaml --type openapi --name internal_api
api_import graphql-introspection.json --type graphql --name internal_graphql
api_import kittyproxy_traffic.har --type traffic --kind scanner
api_import capture.har --type traffic --kind scanner,fuzzer --force
api_import spec.json --preview

Input Types (--type)

Options

• --name --- friendly name for the generated module pack.
• --kind --- scanner, fuzzer, or scanner,fuzzer (default).
• --module-dir --- output directory for modules (default modules/generated/api).
• --artifact-dir --- manifests, fixtures, tests (default artifacts/api_module_packs).
• --preview --- normalized inventory without writing files.
• --force --- overwrite existing files.

Recommended Workflow

1. Collect the OpenAPI spec (developer documentation, http GET /openapi.json) or export traffic via KittyProxy.
2. api_import spec.json --preview --- validate endpoints, verbs, parameters.
3. api_import spec.json --name client_acme_api --force.
4. sync then search generated/api --- index the new modules.
5. use <generated_module> ; configure rhost, tokens ; run.
6. Suggested unit tests in output: python -m unittest discover -s artifacts/api_module_packs/<pack>/tests

OpenAPI Example

api_import ./exports/petstore-openapi.json \
  --type openapi --name petstore --kind scanner,fuzzer

search petstore
show options
set rhost api.target.local
set ssl true
run

The generated module name depends on the OpenAPI operation IDs and is created under modules/generated/api/.

GraphQL Example

api_import ./dumps/graphql-introspection.json \
  --type graphql --name corp_gql --kind scanner

api_import ./dumps/graphql-introspection.json --preview

The generator normalizes queries and mutations into HTTP test points.

HAR Traffic Example

# From KittyProxy or browser export
api_import ./captures/session-audit.har \
  --type traffic --kind scanner --name replay_har

api_import ./captures/kittyproxy-export.json \
  --type traffic --force

HAR entries preserve method, URL, headers, and body for replaying targeted probes.

Generated Tree Structure

• modules/generated/api/ --- .py files importable via use.
• artifacts/api_module_packs/<name>/ --- JSON manifest, fixtures, tests/ directory.

Version these artifacts in Git for reproducible API audits.

REST Server --- interfaces/api_server.py

ApiServer exposes a unified Flask API: health, authentication, modules, sessions, pipelines, events, workspaces, registry (optional server mode).

Starting via kittyapi.py

export KITTYSPLOIT_API_KEY="long-random-key"
python kittyapi.py -H 127.0.0.1 -p 5000 -k "KITTYSPLOIT_API_KEY"
python kittyapi.py -H 0.0.0.0 -p 8443 -k "KITTYSPLOIT_API_KEY" -d

• -H / --host --- listen interface (default 127.0.0.1).
• -p / --port --- port (default 5000).
• -k / --api-key --- bootstrap key (or KITTYSPLOIT_API_KEY variable).
• -m / --master-key --- database encryption unlock.
• -d / --debug --- Flask debug mode.

Starting from the Main Console

kittysploit --api --api-host 127.0.0.1 --api-port 5000 --api-key "$KITTYSPLOIT_API_KEY"

Identical behavior: the process remains attached to the HTTP server.

Main Endpoints

Pipeline, events, resources, and registry routes are available if the kernel runtime is loaded.

HTTP Authentication

# 1. Obtain an access token (curl example)
curl -s -X POST http://127.0.0.1:5000/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"'"KITTYSPLOIT_API_KEY"'"}'

# 2. Authenticated call
curl -s http://127.0.0.1:5000/api/modules \
  -H "Authorization: Bearer <access_token>"

# Alternative: direct bootstrap key (depending on configuration)
curl -s http://127.0.0.1:5000/api/health \
  -H "X-API-Key: KITTYSPLOIT_API_KEY"

Module Execution via REST

curl -s -X POST http://127.0.0.1:5000/api/modules/auxiliary/scanner/portscan/tcp/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"options":{"rhosts":"127.0.0.1","ports":"22,80","threads":"10"}}'

Consult /api/openapi.json for the exact JSON body schema.

CORS

Environment variable KITTYSPLOIT_API_CORS_ORIGINS:

export KITTYSPLOIT_API_CORS_ORIGINS="https://dashboard.client.com"
# or disabled if empty; "*" for explicit wildcard (not recommended in prod)

RPC Server --- interfaces/rpc_server.py

RpcServer exposes an XML-RPC interface for legacy clients, Python scripts, and the internal MCP layer.

Starting via kittyrpc.py

export KITTYSPLOIT_API_KEY="long-random-key"
python kittyrpc.py -H 127.0.0.1 -p 8888 -k "KITTYSPLOIT_API_KEY"
python kittyrpc.py -H 127.0.0.1 -p 8888 -k "KITTYSPLOIT_API_KEY" -d

Starting from the Console

kittysploit --rpc --rpc-host 127.0.0.1 --rpc-port 8888 --api-key "$KITTYSPLOIT_API_KEY"

RPC Authentication

Each POST request must include:

X-API-Key: <key>
# or
Authorization: Bearer <access_token>

Without a valid key, the handler returns 401 Unauthorized. The server refuses to start if api_key is empty.

Minimal Python Client

import xmlrpc.client

proxy = xmlrpc.client.ServerProxy(
    "http://127.0.0.1:8888",
    headers=[("X-API-Key", "your_key")],
    allow_none=True,
)

print(proxy.system.listMethods())
# Framework methods: execute_command, list_modules, run_module, etc.

Exact names depend on registration in RpcServer.register_functions(); inspect with system.listMethods().

REST vs RPC --- When to Choose

Shared Security --- interfaces/api_security.py

api_security.py centralizes authentication, RBAC roles, rate limiting, and token rotation for ApiServer, RpcServer, and MCP.

Roles and Permissions

Main Components

• RotatingTokenManager --- issues access/refresh tokens from the bootstrap key.
• RequestAuthenticator --- validates Bearer or X-API-Key, resolves AuthContext.
• ApiRateLimiter --- sliding windows per tier (public, auth, read, mutate, admin).
• secrets_equal --- constant-time secret comparison.
• parse_cors_origins --- parses KITTYSPLOIT_API_CORS_ORIGINS.

Rate Limiting Tiers (Defaults)

Token Lifetimes

• Access token: 15 minutes (DEFAULT_ACCESS_TTL_SECONDS).
• Refresh token: 24 hours (DEFAULT_REFRESH_TTL_SECONDS).

Useful Environment Variables

export KITTYSPLOIT_API_KEY="bootstrap-secret-min-32-chars"
export KITTYSPLOIT_API_CORS_ORIGINS="https://ops.example.com"
# Default roles for bootstrap principal (depending on deployment)
export KITTYSPLOIT_API_ROLES="operator"

Best Practices

1. Generate the bootstrap key with openssl rand -hex 32.
2. Never commit KITTYSPLOIT_API_KEY to Git.
3. Prefer short access token + refresh rather than the bootstrap key on every request.
4. Bind -H 127.0.0.1 and place a TLS reverse proxy (nginx, Caddy) if exposing on WAN.
5. Audit /api/auth/me after deployment to verify effective roles.

Error Responses

• 401 Unauthorized --- invalid or expired key or token.
• 403 Forbidden --- insufficient RBAC permission for the route.
• 429 Too Many Requests --- rate limit exceeded; exponential backoff on client side.

Link with MCP (Model Context Protocol)

MCP reuses the same security model as API and RPC interfaces:

Architecture

  [Cursor / IDE / AI Assistant]
              |
              |  MCP (stdio or SSE)
              v
       kittymcp_server.py
              |
              |  Internal RpcServer (ephemeral port)
              v
       KittySploit Framework
              |
              +--> same RBAC / api_security as external RPC

kittymcp_server.py instantiates a local RpcServer to expose MCP tools. Examples: ks_plan_natural_request, ks_run_module, etc.

Starting MCP (Reminder)

python kittymcp_server.py --host 127.0.0.1 --port 8765 \
  --dangerous-consent

Variables:

export KITTYSPLOIT_MASTER_KEY="..."
export KITTYMCP_DANGEROUS_CONSENT=1

Recommended Secure Flow

1. MCP plans (ks_plan_natural_request) --- mcp:read role.
2. Human validates target and module.
3. MCP executes (ks_run_module) --- mcp:execute / modules:run role.
4. Audit (ks_mcp_audit).

REST API vs MCP Differences

• REST --- generic integration, CI, orchestrators.
• MCP --- AI assistants, natural language, structured tools for LLMs.
• Both rely on api_security.py for effective permissions.

Use kittymcp_client.py and kittymcp_server.py for MCP client and server configuration.

Integrated Scenario --- Complete API Pipeline

1. workspace create acme-api-q2 ; workspace use acme-api-q2.
2. scope add api.acme.test.
3. api_import ./specs/acme-openapi.json --name acme --preview.
4. api_import ./specs/acme-openapi.json --name acme --force.
5. sync now.
6. Terminal 2: export KITTYSPLOIT_API_KEY=... ; python kittyapi.py -p 5000.
7. CI: POST /api/modules/.../run on generated scanners.
8. Console: host add api.acme.test ; vuln add ....

CI Scenario --- HAR Import + RPC

1. KittyProxy export after manual crawl: session.har.
2. api_import session.har --type traffic --kind fuzzer --name ci_replay.
3. python kittyrpc.py -k "\$KITTYSPLOIT_API_KEY" as user systemd service.
4. GitLab pipeline calls xmlrpc run_module with timeout.
5. Artifacts: RPC logs + artifacts/api_module_packs/ci_replay/tests.

Deployment Hardening

Production Checklist

1. Bootstrap key: 32 random bytes or more.
2. Listen on localhost only or behind VPN.
3. TLS terminated by reverse proxy; no -k on clients.
4. Minimal role (viewer for monitoring, operator for run).
5. Periodic rotation of KITTYSPLOIT_API_KEY + auth/revoke.
6. Centralized logs for 401/403/429.
7. Workspace separation per client before exporting or sharing results.

Anti-patterns

• kittyapi.py -H 0.0.0.0 without firewall or TLS.
• Same API key between dev and production.
• --dangerous-consent MCP on laptop without mandate.
• Export of out-of-scope data from the workspace.

Access Interface Comparison

Cross-Troubleshooting

• ApiServer requires non-empty api_key --- export KITTYSPLOIT_API_KEY or -k.
• Port 5000/8888 in use --- change -p; ss -tlnp | grep 5000.
• Generated module not found --- sync now; verify --module-dir.
• RPC 401 from MCP --- align key between MCP and kittyrpc.
• CORS blocked --- configure KITTYSPLOIT_API_CORS_ORIGINS.

Related Capabilities

• KittyProxy feeds api_import --type traffic.
• HTTP and GraphQL scanners complement generated modules.
• MCP, collaboration, and plugins expose the same workspace data to other tools.
• campaign and reporting commands consume validated findings.
• http validates endpoints before import.