# GhostMap v2

> AI-Augmented Autonomous Network Reconnaissance & Evasion Framework

![Python](https://img.shields.io/badge/Python-3.11+-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Status](https://img.shields.io/badge/Status-Active-brightgreen)

> **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:**
```bash
sudo apt install nmap arp-scan hydra
```

**Python:** 3.11 or higher

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

---

## Setup

```bash
# 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

```bash
# 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):
```bash
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](https://www.linkedin.com/in/samir-pandey23/) · [GitHub](https://github.com/Samir12218415)