Run Kali Linux security tools by describing what you want in natural language. This web-based MCP (Model Context Protocol) Agent turns prompts into safe, executable commands using Gemini 2.5 Pro with RAG enhancement, streams live results, and can execute remotely on your own Kali machine via WebSocket.
Developed an AI-powered pentesting tool, 'AI MCP', featuring a professional terminal interface with advanced RAG capabilities. The frontend was built with React, TypeScript, and Tailwind CSS, while the backend utilized Express with enhanced WebSocket stability. Implemented Gemini AI with Data Pool integration to translate natural language prompts into executable commands, with real-time output streamed via WebSockets and optional integration with a Telegram bot."
https://joelindra.gitbook.io/all-tools/hera
- Natural language → Kali command: Gemini 2.5 Pro converts prompts into precise commands.
- Data Pool (RAG System): Use markdown files as knowledge base to reduce AI hallucinations and improve command accuracy.
- Remote Kali execution (WebSocket): Pair the app with your Kali box using the included Python client.
- Real-time streaming output: Watch command output as it happens in the browser.
- Dual modes: Remote (Kali client) or Local (server) execution with clear status badges.
- Safety guardrails: Context-aware validation to prevent obviously destructive system commands.
- Professional terminal UI: Dark-first theme, terminal styling, result collapse/expand, and history.
- Enhanced Settings Management: Comprehensive configuration with real-time status monitoring.
- Personal API key support: Use your own Gemini API key (per-user setting).
- Telegram bot integration (optional): Send prompts using Telegram.
- Improved WebSocket Stability: Persistent connections across page navigation.
- You enter a prompt (e.g., "Scan ports 80 and 443 on example.com").
- If Data Pool is enabled, the system loads relevant context from markdown files.
- Backend asks Gemini to generate the exact Kali command with RAG context.
- Command is validated for safety and tool availability.
- If a Kali client is connected, the command is sent via
/kali-wsand executed on your machine; otherwise runs locally on the server. - Output streams back over WebSocket to the browser in real-time.
High-level flow:
Prompt → Data Pool Context → Gemini (command + safety + RAG) → choose mode (remote/local) → execute → stream results
- Client: React 18, TypeScript, Vite 7, TailwindCSS, shadcn/ui, Radix UI, TanStack Query
- Server: Node.js, Express, WebSocket (
ws), Passport (future-ready), Drizzle ORM (future-ready) - AI:
@google/genai(Gemini 2.5 Pro) with RAG enhancement - Data Pool: File system-based RAG system for markdown files
- Remote client: Lightweight Python script using
websocket-client - Integration: Optional Telegram bot via
node-telegram-bot-api
Repo layout:
client/ # React app (UI, pages, components)
server/ # Express server, routes, Gemini integration, WebSocket, pool reader
pool/ # Markdown files for RAG knowledge base
kali-client.py # Remote client for your Kali machine
Key server files:
server/gemini.ts: prompt → command, safety analysis, RAG integrationserver/executor.ts: process execution and streamingserver/routes.ts: REST APIs + WebSocket endpoints (/ws,/kali-ws)server/telegram.ts: Telegram bot integrationserver/poolReader.ts: Data Pool file scanning and processingserver/storage.ts: Settings and data persistence
Prereqs:
- Node.js 18+ (or 20+ recommended)
- npm 9+
- Install
npm install- Run in development
# Starts Express with tsx and serves the Vite client
npm run dev- Build for production
npm run build- Start production server
npm startThe dev script uses
tsxto runserver/index.ts. Build bundles the client with Vite and the server with esbuild.
Set these in your environment (or a .env you load before starting):
GEMINI_API_KEY(required): Google Gemini API key. You can set a personal key in Settings; the server will fall back to this env var if not provided.SESSION_SECRET(recommended): Express session secret. If omitted, it is auto-generated at runtime.
Get a Gemini API key from Google AI Studio: https://aistudio.google.com/app/apikey
The Data Pool feature uses markdown files as a knowledge base to enhance AI command generation:
- Setup: Create a
pooldirectory in your project root - Add Files: Place
.mdfiles with relevant information (penetration testing playbooks, tool documentation, etc.) - Enable: Go to Settings → Data Pool tab and toggle the switch
- Monitor: View real-time status including file count, size, and last scanned time
Example pool files:
penetration-testing-playbook.md- Comprehensive pentesting methodologytool-documentation.md- Detailed tool usage guidesvulnerability-database.md- Common vulnerabilities and exploitation techniques
Execute commands on your own Kali machine. Steps:
- In the web app, open Settings and create a new client to get a token.
- On your Kali box:
# Download the client script
wget https://your-server.example.com/kali-client.py
# Install dependency
pip install websocket-client
# Run the client
python3 kali-client.py --token YOUR_TOKEN --server wss://your-server.example.com- Verify:
- Browser shows "Kali: Connected" with your client name.
- Terminal output on Kali: "Authenticated successfully".
The client auto-reconnects, sends heartbeats, and streams results back.
Security notes:
- Keep your token secret. Revoke and reissue if compromised.
- Run the client under the user with the permissions you intend to grant.
Detailed guide: see
README_KALI_CONNECTION.md.
- Configure in Settings with your Telegram bot token and chat ID.
- Available commands:
/start,/help,/ping,/status,/history. - Send any natural-language message to execute a command and receive the result.
- Open the app in your browser, type a prompt like:
- "Scan port 80 and 443 on google.com" →
nmap -p 80,443 google.com - "Check DNS records for google.com" →
dig google.com - "Lookup whois for facebook.com" →
whois facebook.com
- "Scan port 80 and 443 on google.com" →
- Watch live output; expand/collapse results; view command history.
- Switch execution mode per command: Auto, Local, Remote.
- Configure Data Pool: Go to Settings → Data Pool to enable RAG enhancement
- Monitor Status: View real-time connection status and pool data statistics
- Manage clients and API keys in Settings.
- The app performs basic safety validation and tool availability checks.
- Pen-testing tools are allowed in local environments.
- You are responsible for complying with laws and policies when using security tools.
New Features:
- Data Pool (RAG System): Use markdown files as knowledge base to reduce AI hallucinations
- Enhanced Settings UI: Comprehensive configuration with real-time status monitoring
- Improved WebSocket Stability: Persistent connections across page navigation
Bug Fixes:
- Fixed WebSocket disconnection issues when navigating between pages
- Resolved UI blank screen when enabling Data Pool feature
- Fixed race conditions in settings updates
- Improved error handling and user feedback
Technical Improvements:
- Centralized WebSocket management in App component
- Custom event system for inter-component communication
- Optimized React Query cache management
- Enhanced error handling and debugging
- Data Pool (RAG System)
- Enhanced Settings Management
- Improved WebSocket Stability
- Persistent database storage (PostgreSQL)
- Multi-user auth and roles
- Command templates and saved prompts
- Export results (PDF/JSON/CSV)
- Multi-session parallel execution
- Full MCP protocol implementation
- Output syntax highlighting
- Advanced RAG features (semantic search, file categorization)
Original: MIT
Legend: Hades [ Joel Indra ]
- Google Gemini 2.5 Pro (
@google/genai) - React, Vite, TailwindCSS, Radix UI, shadcn/ui
- ws, express, tanstack/query
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. If you have a suggestion that would make this project better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
Getting Started
1. Fork the project repository.
2. Create your feature branch:
git checkout -b feature/AmazingFeature
3. Install dependencies (if you haven't already):
npm install
4. Make your changes and commit them with a descriptive message:
git commit -m 'feat: Add some AmazingFeature'
5. Push your changes to your forked repository's branch:
git push origin feature/AmazingFeature
6. Open a Pull Request against the main branch of the original repository.
Guidelines:
- Please provide a clear and detailed description of your changes in the pull request.
- If your PR addresses an open issue, please link to it (e.g., "Closes #123").
- Ensure your code is well-formatted and follows the existing style.
If you like this project:
- Star the repo on GitHub
- Share your screenshots and tag the author