Ai Assistant Chat With Nmap Tool Integration

🚀 AI Agent Chat Tool Integrated with Nmap Tool

This project provides a web-based Gradio chat interface for users to interact with an AI assistant powered by the OpenAI API. The assistant is equipped with tools for using the local file system and conducting network scans through a containerized Nmap server.

🚀 Quick Start

Ensure that the OpenAI API key is set, Docker is running, and the virtual environment is activated in the project root directory.

python app.py
# An example MCP server with several Nmap scanning functions.

✨ Features

• Conversational AI Assistant: Engage in natural conversations with the AI.
• File System Access Tool: Limited to the application directory for accessing local files.
• Nmap Network Scanning Tools:
  • ping_host [citation: 14]
  • scan_network (Top 100 ports) [citation: 16]
  • all_scan_network (Comprehensive scan) [-A] [citation: 18]
  • all_ports_scan_network (All 65535 ports) [citation: 20]
  • smb_share_enum_scan (SMB share enumeration) [citation: 22]
• Web-based UI using Gradio: Facilitates user interaction [citation: 11, 12].
• Containerized Nmap Tool Server using Docker: Ensures easy dependency management and isolation.

📚 Documentation

Overview

The application utilizes the OpenAI Agent SDK framework. User requests are handled by an AI agent that can understand requests and decide whether to use available tools. It features:

• A web-based interface provided by Gradio for convenient user interaction.
• An AI agent powered by an OpenAI model on the backend (API key required).
• A Model Context Protocol (MCP) server for file system access (@modelcontextprotocol/server-filesystem).
• An MCP server wrapped in a Docker container, offering Nmap scanning capabilities (ping, port scanning, service discovery, SMB share enumeration) [citation: 14, 16, 18, 20, 22].

The Nmap server runs in a Docker container for easy dependency management and isolation.

Architecture

1. Gradio UI (app.txt): Handles user input and displays conversation history.
2. Main Application (app.txt):
   • Initializes the Gradio interface.
   • Manages the conversation state.
   • Sets up and manages the MCP server.
   • Instantiates and runs the OpenAI agent.
3. OpenAI Agent (agents library): Processes user messages, invokes tools when necessary, and generates responses [citation: 1, 3].
4. MCP Server:
   • File System Server: Runs via npx to provide local file access [citation: 1].
   • Nmap Toolkit Server (nmap-server.txt in Docker): Runs in a Docker container and exposes Nmap scanning functions as tools through MCP [citation: 2, 14]. app.txt uses docker run to start this server for each request.

📦 Installation

Prerequisites

• Python: Version 3.9 or higher.
• Docker: Install the latest version and ensure it is running.
• Node.js/npm: Required for npx to run the file system MCP server.
• OpenAI API Key: Set as the environment variable OPENAI_API_KEY.

Steps

1. Clone the repository:

git clone <your-repository-url>
cd <your-repository-directory>

2. Set the OpenAI API key: Export your API key as an environment variable. Replace your_api_key_here with your actual key.

• Linux/macOS:

export OPENAI_API_KEY='your_api_key_here'

• Windows (Command Prompt):

set OPENAI_API_KEY=your_api_key_here

• Windows (PowerShell):

$env:OPENAI_API_KEY='your_api_key_here'

3. Build the Nmap Docker image: Navigate to the directory containing nmap-server.py and Dockerfile, then run:

docker build -t nmap-mcp-server .

(Ensure the Dockerfile content is correct, especially check the MCP package name if it is not modelcontextprotocol) 4. Install Python dependencies: It is recommended to use a virtual environment.

python -m venv venv
# Activate the virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
.\venv\Scripts\activate
# Install requirements
pip install -r requirements.txt