README.md

metadata

title: Kali Remote Shell
emoji: 💀
colorFrom: blue
colorTo: green
sdk: docker
pinned: false

💀 Kali Remote Shell (HF Spaces Edition)

A high-performance, secure Remote Shell server based on Kali Linux, specifically optimized for Hugging Face Spaces. It provides a full interactive terminal, file management, and process monitoring with a built-in web UI.

🚀 Features

• Full Interactive Terminal: WebSocket-based PTY with xterm.js support.
• Kali Linux Headless: Pre-installed with core pentesting tools (nmap, masscan, sqlmap, ffuf, etc.).
• Session Isolation: Each agent/user gets a dedicated isolated workspace in /tmp/remote-shell/<session_id>.
• File Manager: Upload, download, read, write, and even extract ZIP files directly via API/UI.
• Process Monitor: Real-time process tree visualization and management.
• Security: Bearer token authentication and path-traversal protection.

🛠️ Deployment on HF Spaces

1. Create a new Docker Space.
2. Upload the following files: server.py, Dockerfile, and the static/ directory.
3. Configure Secrets in Space Settings:
   • API_TOKEN: Your custom access token.
4. Open the Space URL and start hacking!

📡 API Overview

Endpoint	Method	Description
/ws/terminal	WS	Full interactive terminal
/exec	GET	Execute command and stream output
/files	GET	List files (session-aware)
/files/upload-zip	POST	Upload and extract ZIP to workspace
/processes	GET	Get hierarchical process tree

🛡️ Security Note

This tool is designed for security research and authorized testing only. When running on Hugging Face Spaces, it operates within a secure sandbox environment. Always set a strong API_TOKEN to prevent unauthorized access.

---

Built with ❤️ for the security community.