XSSGEN

XSSGEN is an advanced framework for generating and testing Cross-Site Scripting (XSS) payloads. It is designed to work in tandem with Large Language Models (LLMs) through the Machine-readable Command Protocol (MCP), acting as a powerful backend for AI-driven security testing.

The system provides a rich set of primitives for payload construction, encoding, mutation, and analysis, enabling an AI agent to intelligently explore and bypass web application firewalls (WAFs) and security filters.

Architecture

The framework is composed of two main components:

1. XSS Server (xss_server.py): A FastAPI and MCP server that acts as the core engine. It hosts all the tools for payload generation, analysis, and strategic knowledge resources. It runs as a persistent background service.

2. XSS Client (xss_client.py): A lightweight MCP client that acts as a proxy between a command-line environment (like Gemini CLI) and the XSS Server. It translates standard I/O commands from the CLI into HTTP requests to the server, allowing seamless integration.

This decoupled architecture allows the heavy lifting to be done by the server, while the client remains simple and easy to integrate into various environments.

Features

• Payload Construction: Build complex payloads from basic HTML and JavaScript components.
• Advanced Encoding & Mutation: A wide array of encoding (Base64, URL, HTML Entity) and mutation (case, whitespace) tools to evade filters.
• Active Scanning & Analysis: Tools to inject payloads into a target URL and analyze the reflection context and transformations.
• Strategic Knowledge Base: Provides the LLM with high-level concepts on bypass techniques, browser parsing, and WAF evasion strategies.

Installation

Prerequisites

• Python 3.10+
• Git

Setup

1. Clone the repository:

   git clone https://github.com/pikpikcu/xssgen.git
   cd xssgen

2. Install Python dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

Running the Server

python3 xss_server.py

The server will be available at http://127.0.0.1:8000. To check the health of the server:

curl http://127.0.0.1:8000/health

Gemini MCP Server Configuration

To use this tool with an MCP-compatible client like Gemini CLI, you need to configure it as a remote tool server.

Edit ~/.gemini/settings.json

{
  "mcpServers": {
    "xssgen": {
      "command": "python3",
      "args": [
        "/path/to/xssgen/xss_client.py",
        "--server",
        "http://127.0.0.1:8000"
      ],
      "description": "XssGen AI v0.0.1 - Advanced XSS Payload Generator"
    }
  }
}

Usage Workflow

1. Start the XSS server.
2. Ensure your Gemini CLI is configured with the ~/.gemini/settings.json file.
3. You can now invoke the tools from the /mcp within the Gemini CLI to construct, mutate, and test XSS payloads. The xss_client.py will automatically proxy the requests to the running server.