GhostMap v2

AI-Augmented Autonomous Network Reconnaissance & Evasion Framework

Legal Disclaimer — This tool is intended strictly for authorized penetration testing, academic research, and lab environments. Always obtain explicit written permission before scanning any network. The author assumes no liability for unauthorized or illegal use.

---

Overview

GhostMap v2 is a modular AI-augmented red-team reconnaissance framework that autonomously orchestrates the full recon pipeline — from host discovery to exploitation chain synthesis — using Google Gemini Flash as the decision-making engine.

Unlike traditional static scanners, GhostMap v2 makes real-time evasion decisions per host, dynamically adapting its scanning posture based on vendor signatures and risk assessment.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                     GhostMap v2                         │
├─────────────────────────────────────────────────────────┤
│  Phase 1 │ ARP Host Discovery (arp-scan)                │
│  Phase 3 │ AI Evasion Assessment (Gemini Flash)         │
│          │ → Dynamic T1–T4 speed + MAC spoof decision   │
│  Phase 2 │ Service Fingerprinting (Nmap)                │
│  Phase 2 │ CVE Mapping (NVD API v2 + SQLite cache)      │
│  Phase 4 │ Attack Chain Synthesis (Gemini Flash)        │
│          │ → JSON report saved to disk                  │
└─────────────────────────────────────────────────────────┘

---

Features

• AI-Driven Evasion : Gemini Flash dynamically assigns Nmap timing profiles (T1–T4) and MAC spoofing decisions per host based on vendor risk signatures and ambiguity scoring
• CVE Mapping Pipeline : NVD API v2 integration with local SQLite caching (24h TTL), automatically correlating discovered service versions to CVSS ≥ 7.0 vulnerabilities sorted by severity
• Attack Chain Synthesis : AI-generated prioritized exploitation chain blueprints from per-host CVE findings for downstream red-team triage
• MCP Server : All recon capabilities exposed as callable FastMCP tools, enabling AI-agent interoperability and natural language orchestration
• Throttled Credential Auditing : Hydra integration with single-thread execution and 30s inter-attempt delays to evade standard SIEM detection thresholds
• Structured Reporting : Timestamped JSON reports per run capturing full topology, open services, CVE findings, and AI-generated attack chain blueprints

---

Tech Stack

Component	Technology
Language	Python 3.11+
AI Orchestration	Google Gemini 2.5 Flash (free)
MCP Server	FastMCP
CVE Intelligence	NVD API v2 + SQLite cache
Host Discovery	arp-scan
Service Fingerprint	Nmap
Credential Auditing	Hydra
Output Validation	Pydantic
CLI	argparse + colorama

---

Project Structure

GhostMap/
├── GhostMap.py          # CLI entry point
├── orchestrator.py      # Main pipeline coordinator
├── server.py            # FastMCP server — exposes tools to AI agents
├── cve_mapper.py        # NVD API v2 integration with SQLite caching
├── config.py            # Centralised configuration and constants
├── requirements.txt
├── tools/
│   ├── __init__.py
│   ├── network.py       # MAC spoofing + ARP discovery
│   ├── scanner.py       # Nmap XML parsing wrapper
│   └── auditor.py       # Hydra credential auditing wrapper
└── README.md

---

Prerequisites

System dependencies:

sudo apt install nmap arp-scan hydra

Python: 3.11 or higher

Gemini API key (free): https://aistudio.google.com/app/apikey

---

Setup

# Clone the repository
git clone https://github.com/Samir12218415/GhostMap.git
cd GhostMap

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set your Gemini API key
export GEMINI_API_KEY='your_google_ai_studio_key'

---

Usage

# Standard run — auto-detects hosts, applies AI evasion
sudo -E .venv/bin/python3 GhostMap.py -i wlan0

# Skip MAC spoofing (useful for isolated lab environments)
sudo -E .venv/bin/python3 GhostMap.py -i wlan0 --no-mac-spoof

# Debug mode — prints raw Nmap scan output per host
sudo -E .venv/bin/python3 GhostMap.py -i wlan0 --debug

# Run on a wired interface
sudo -E .venv/bin/python3 GhostMap.py -i eth0

MCP server (for AI-agent integration):

python3 server.py

---

Output

Each run produces a timestamped JSON report:

ghostmap_report_20260605_142300.json

Containing per-host: metadata, open services, CVE findings with CVSS scores, and AI-generated attack chain blueprint.

---

Evasion Profile Logic

Condition	Speed	MAC Spoof
Known security appliance / SIEM	T1	Yes
Unknown vendor / ambiguous host	T2	Yes
Confirmed consumer device (router/NAS)	T3	Optional
Confirmed isolated lab environment	T4	No

---

Legal

This tool is provided for educational and authorized security testing purposes only.

• Only use on networks you own or have explicit written permission to test
• Credential auditing features must only be used against systems you are authorized to assess
• The author accepts no responsibility for misuse or damage caused by this tool

---

Author

Samir Pandey
B.Tech CSE (Minor: Cybersecurity) — Lovely Professional University
ISC2 Certified in Cybersecurity (CC)
LinkedIn · GitHub