KittyProtocol

KittyProtocol is a KittySploit marketplace UI extension for PCAP analysis, live network capture, and protocol investigation. It turns packet captures into flows, security findings, IOCs, and actionable playbooks tied to KittySploit modules.

Features

• Offline analysis — Upload or analyze PCAP/PCAPNG files with display filters, BPF filters, and protocol scoping.
• Live capture — Sniff traffic on a chosen interface with real-time updates over WebSocket (/ws).
• Flow reconstruction — Group packets into conversations with per-flow detail, hex dumps, and subset export (PCAP or JSON).
• Security findings — Heuristic detection of cleartext credentials, missing authentication, replayable requests, sensitive endpoints, and related patterns.
• Investigation workflow — Session annotations, saved filter views, recordings (save/load/replay), and case bundles for handoff.
• IOC extraction — Hosts, domains, URLs, hashes, and MITRE ATT&CK mapping; export as JSON or CSV.
• PCAP comparison — Diff two captures (flows, findings, protocol stats).
• Payload search — Full-text search across indexed payloads when enabled.
• TLS insights — Optional TLS key log path for decryption-oriented analysis (Scapy-backed; status is best-effort).
• Playbooks — Per-finding checklists and suggested KittySploit auxiliary modules for follow-up testing.
• Reports — Export investigation summaries as JSON or HTML.
• Insights — Explain capture, copilot, attack paths, evidence graph, attack surface (UI + API).
• Profiles — Predefined analysis presets (Web, IoT, AD, Cloud, Malware triage).
• STIX export — IOC bundle as STIX 2.1 JSON.
• Async jobs — Long PCAP analyses via background job queue (?async=1 or JSON async: true).
• Read-only public bind — Mutating API blocked when bound on 0.0.0.0 (configurable).

Developer setup

git clone https://github.com/SIA-IOTechnology/KittyProtocol.git
cd KittyProtocol
make install-dev    # creates .venv and installs requirements-dev.txt
make validate       # pytest + compileall + smoke

requirements-dev.txt includes pytest, scapy, flask, flask-cors. Tests stub kittysploit so the suite runs outside the full KittySploit tree.

Make targets

Target	Description
make install-dev	Create .venv and install dev dependencies
make test	Run pytest (tests/)
make lint	compileall on src/kittyprotocol
make smoke	Health endpoint smoke test
make validate	All of the above

Requirements

Component	Notes
KittySploit	≥ 1.0.0 (marketplace host)
Python	3.10+ recommended
Scapy	Required for capture and PCAP parsing
Root / Administrator	Required for live interface capture
Flask stack	flask, flask_cors, flask_socketio (optional; polling fallback)

Offline PCAP analysis may work without root depending on file access; live sniffing does not.

Installation

From the KittySploit console:

kittysploit> market install kittyprotocol

Then launch the extension (KittySploit resolves the entry point from extension.toml):

python launch_kittyprotocol.py

The web UI is served at http://127.0.0.1:8004 by default.

Development install

Install from a local checkout inside your KittySploit apps tree:

kittysploit> market install ./apps/kittyprotocol

Or symlink/copy this repository into apps/kittyprotocol and use the same command.

Usage

Web UI

1. Start KittyProtocol (via marketplace launcher or CLI below).
2. Open the UI (default: http://127.0.0.1:8004).
3. Upload a PCAP or start live capture; use Insights for explain/copilot/attack paths.
4. Select an analysis profile to pre-fill BPF/protocol filters.

CLI

Run without starting the server to scan a file and print a short summary:

python -m kittyprotocol capture.pcapng
python -m kittyprotocol capture.pcap --display-filter http --protocol-filter http,dns --max-packets 5000

Start the API and UI:

python -m kittyprotocol --host 127.0.0.1 --port 8004
# Bind on all interfaces:
python -m kittyprotocol --host 0.0.0.0 --port 8004

API overview

Endpoint	Description
GET /api/health	Service health, Scapy, realtime mode, read-only flag
GET /api/config	Read-only runtime limits (no secrets)
POST /api/analyze	Analyze PCAP (sync); add async: true for job queue
GET /api/jobs/<id>	Async analysis job status
GET /api/explain · /api/copilot · /api/attack-paths	Game-changer insights
GET /api/attack-surface · /api/evidence-graph	Attack surface & graph
POST /api/evidence-pack	Short evidence bundle for tickets
GET /api/iocs/stix	STIX 2.1 IOC export
GET /api/profiles	Analysis presets
POST /api/filter-assistant	Natural-language → filters
PATCH /api/detectors/<name>	Enable/disable a detector

See also: flows, live capture, compare, annotations, export, case-room, rule-lab, environment memory.

Example curl

# Sync analyze
curl -s -X POST http://127.0.0.1:8004/api/analyze -H 'Content-Type: application/json' \
  -d '{"pcap":"/path/to/capture.pcapng","max_packets":5000}'

# Async analyze
curl -s -X POST 'http://127.0.0.1:8004/api/analyze?async=1' -H 'Content-Type: application/json' \
  -d '{"pcap":"/path/to/capture.pcapng"}'

curl -s http://127.0.0.1:8004/api/jobs/<job_id>

curl -s http://127.0.0.1:8004/api/attack-surface
curl -s -X POST http://127.0.0.1:8004/api/evidence-pack -H 'Content-Type: application/json' -d '{}'
curl -s http://127.0.0.1:8004/api/iocs/stix -o iocs.stix.json

Filter syntax: GET /api/docs/filters.

Environment variables

Variable	Default	Purpose
KITTYPROTOCOL_SESSION_DIR	~/.local/share/kittyprotocol	Session, uploads, tags, rules
KITTYPROTOCOL_STRICT_PATHS	true	Restrict PCAP paths to session dirs (+ optional roots)
KITTYPROTOCOL_READONLY_PUBLIC	true	Block mutating API on 0.0.0.0 bind
KITTYPROTOCOL_MAX_UPLOAD_BYTES	512MB	Upload size cap
KITTYPROTOCOL_MAX_EXPORT_BYTES	50MB	Export payload cap
KITTYPROTOCOL_JOB_RETENTION	50	Max retained async jobs

Architecture

src/main.py              # Marketplace entry (path setup, privilege elevation)
src/kittyprotocol/
  __init__.py            # Flask app, routes, CLI
  core.py                # KittyProtocolAnalyzer (capture, flows, findings)
  protocol_intel.py      # Layer-aware protocol extraction (TLS, HTTP, DNS, …)
  compare_engine.py      # PCAP diff logic
  investigation_store.py # Views and annotations persistence
  payload_index.py       # Payload full-text index
  playbooks.py           # Finding → checklist + KittySploit modules
  provenance.py          # Analysis provenance metadata
  static/ · templates/   # Web UI assets

Permissions & security

• Declared in extension.toml: network access enabled, standard sandbox.
• Read-only mode when bound on 0.0.0.0 blocks POST/PUT/PATCH/DELETE on /api/* except safe read-only POST endpoints (/api/query, /api/export, …).
• Strict paths (KITTYPROTOCOL_STRICT_PATHS=true): PCAP/keylog paths must live under session/uploads/recordings unless extra roots are configured.
• Uploads accept only .pcap, .pcapng, .cap.
• Findings are heuristic—validate before operational use.
• TLS/QUIC parsing is Scapy best-effort, not Wireshark-grade.

Troubleshooting

Issue	Suggestion
Scapy is required	Install Scapy in the KittySploit Python environment
Live capture fails	Run as root/admin or allow sudo when prompted
Empty or invalid upload	Ensure the file is a valid PCAP/PCAPNG (≥ 24 bytes)
pytest missing locally	Run make install-dev then make validate

Repository & license

• Repository: https://github.com/SIA-IOTechnology/KittyProtocol
• License: MIT — Copyright (c) 2026 IOTechnology

Related

Part of the KittySploit extension ecosystem. For framework documentation and other marketplace apps, see the KittySploit project.