README.md

---
title: Vapt Agent
emoji: 👁
colorFrom: red
colorTo: green
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: AI-powered VAPT agent built with Claude, MCP, and Gradio.
tags:
  - mcp-in-action-track-enterprise
  - mcp-in-action-track-consumer
  - mcp-in-action-track-creative
  - building-mcp-track-enterprise
  - building-mcp-track-consumer
  - building-mcp-track-creative
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/66d9b98cec009ab887601d00/2x4OCbl46kVrGOh1a2S4z.png
---


# 🏆 VAPT Agent - Intelligent API Security Testing  
### *(Submission for MCP’s 1st Birthday Hackathon)*  
**Both the Tracks Covered:**  
- **MCP in Action**  
- **Building MCP**

> **MCP's 1st Birthday Hackathon Submission** 🎉  
> *Hosted by Anthropic & Gradio on Hugging Face*  
> [🔗 Hackathon Page](https://huggingface.co/MCP-1st-Birthday)

**LinkedIn Post** → **http://bit.ly/4p98LHy**   
**Demo Video – MCP in Action** → **https://youtu.be/wFgW_o48pw8?si=2lpag5I4zsUz8J2d**  
**Demo Video – Building MCP** → **https://youtu.be/JptGi7gHybY**

---

# 🎯 MCP in Action  
### Building an AI-powered VAPT workflow using multiple MCP servers

This part of the project demonstrates how a single agent orchestrates multiple MCP servers to plan, execute, and explain a complete API security assessment.

The Gradio application acts as an MCP client, coordinating:

- Postman MCP Server  
  Endpoint discovery, schema generation  
- Custom VAPT MCP Tools  
  SQLi, XSS, authentication, CORS, headers, rate limits  
- Claude Agent SDK (MCP-compatible)  
  Reasoning + tool invocation  
- RAG Security Tutor (Nebius + Chroma)  
  Report-specific education using embeddings

This produces a fully automated end-to-end VAPT workflow.

---

## 📋 Project Overview

The VAPT Agent is an autonomous system that performs API security testing and generates detailed audit-ready reports using:

- **Anthropic Claude Agent SDK** - Powers the core VAPT reasoning agent with Claude Haiku 4.5 from AWS Bedrock.
- **Postman MCP Server** - Enables automatic API discovery and OpenAPI specification generation
- **Custom VAPT MCP Tools** - Provides specialized security testing tools (SQL injection, XSS, auth testing, etc.)
- **Gradio Interface** - Provides an interactive, real-time UI for the VAPT workflow, enabling progress streaming, report visualization, dashboard analytics, and an integrated AI Security Tutor.
- **RAG tutor (Nebius LLM + Chroma DB)** - Provides context-aware education and analysis using embeddings.

The system is designed to execute full vulnerability assessments while also explaining findings in simple language.

---

## 🏗️ Architecture (MCP in Action)

```text
┌─────────────────────────────────────────────────────────────────┐
│                       Gradio Web Interface                      │
│       (Progress Stream • Dashboard • AI Security Tutor)         │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                      Claude Agent SDK
                     (MCP-aware Reasoning)
                               │
      ┌─────────────────────────────────────────────────────────┐
      │                 External MCP Servers                    │
      │                                                         │
      │  ┌───────────────┐      ┌───────────────────────────┐  │
      │  │ Postman MCP   │      │ Custom VAPT MCP Tools     │  │
      │  │ (Discovery)   │─────▶│ (Security Testing Suite)  │  │
      │  └───────────────┘      └───────────────────────────┘  │
      └─────────────────────────────────────────────────────────┘
                               │
                               ▼
                      Target API Under Test
```
### 🔄 How It Works

1. **User Input** → User provides API endpoint via Gradio interface
2. **Discovery** → Claude agent uses **Postman MCP** to discover endpoints and generate OpenAPI spec
3. **Testing** → Agent invokes **Custom VAPT MCP tools** to test for vulnerabilities
4. **Reasoning** → **Claude Haiku 4.5** through AWS Bedrock analyzes results and generates comprehensive security report
5. **Visualization** → Gradio dashboard displays risk scores and severity charts
6. **Education** → User asks questions

### 📊 Output

The agent generates a comprehensive **Markdown report** saved as `vapt_report_YYYYMMDD_HHMMSS.md` containing:

- **Executive Summary** with risk score
- **API Specification** (OpenAPI spec)
- **Vulnerability Details** (Severity, Description, Evidence, Remediation)
- **Security Headers Analysis**
- **CORS Policy Review**
- **Rate Limiting Assessment**
- **Recommendations** for fixes
---

## ✨ Key Capabilities (MCP in Action)
Automated Security Assessment:
- SQL Injection  
- XSS  
- Auth/Token checks  
- Path traversal  
- Rate limiting / DoS tests  
- CORS misconfigurations  
- Security headers audit  

Interactive Gradio UI:
- Real-time streaming logs  
- Downloadable markdown report  
- Visual risk dashboard (gauge + pie chart)  
- Tabbed layout  
- Styled UI  

RAG Security Tutor:
- Markdown-aware chunking  
- Embeddings via Nebius (Qwen3-Embedding-8B)  
- Chroma vector search  
- Context-grounded answers  
- Optional web search fallback  

---

## 🧩 MCP Integrations Demonstrated (MCP in Action)
Postman MCP Server  
Used for endpoint discovery and dynamic request generation.

Custom VAPT MCP Tools  
Implements targeted security tests.

Claude Agent SDK  
Provides reasoning and tool orchestration across multiple MCP servers.

---
## 🎁 Benefits & Impact

### For Security Professionals
- ⚡ **Save Time**: Automate repetitive VAPT tasks
- 📊 **Visual Insights**: Instantly understand risk posture with charts
- 🎓 **Learn On-the-Go**: AI tutor explains findings while you work
- 📄 **Audit-Ready Reports**: Comprehensive markdown reports with evidence

### For Developers
- 🛡️ **Shift-Left Security**: Test APIs during development
- 📚 **Security Education**: Learn secure coding through AI tutor
- 🔧 **Easy Integration**: Simple API endpoint input
- 🚀 **Fast Feedback**: Get results in minutes, not days

### For Organizations
- 💰 **Cost-Effective**: Reduce manual penetration testing costs
- 📈 **Scalable**: Test multiple APIs rapidly
- 📋 **Compliance**: Generate audit-ready security reports
- 🔄 **Continuous Testing**: Integrate into CI/CD pipelines

### Technical Innovation
- 🧩 **MCP Showcase**: Demonstrates multiple MCP server integration
- 🔬 **RAG Best Practices**: Production-ready context engineering
- 🎨 **UX Excellence**: Beautiful, intuitive Gradio interface
- 🔓 **Open Source**: Extensible architecture for custom tools

---
# 🟧 Building MCP  
### Converting the entire VAPT Agent into its own MCP server

For the Building MCP track, the same Gradio application was extended to expose an MCP server interface, allowing external AI tools, automation systems, and CI/CD pipelines to call the VAPT engine programmatically.

Following the guidelines from the **[Hugging Face blog on building MCP servers with Gradio](https://huggingface.co/blog/gradio-mcp)**, we transformed our application to support both web-based and programmatic access.

---
## 🔌 VAPT Agent as an MCP Server (Building MCP)

MCP Server URL (Streamable HTTP):

https://mcp-1st-birthday-vapt-agent.hf.space/gradio_api/mcp/

Supports:
- Streamable HTTP  
- STDIO  
- Claude Desktop  
- Scripts  
- CI/CD  

---
## 🛠️ Tools Exposed by VAPT Agent MCP Server

Below is the tool documentation used in the “Building MCP” track.

---

### 1. vapt_agent_run_security_test  
Primary tool exposed by the MCP server.

Purpose:
- Validates inputs  
- Discovers endpoints via Postman MCP  
- Executes internal security tests  
- Generates full markdown report  
- Streams progress in real time  
- Updates dashboard  

Parameters:
- api_endpoint (string): API target  
- http_method (string): GET / POST / PUT / DELETE  
- api_key (string): token  

Example (Python MCP client):

result = await session.call_tool(
    "vapt_agent_run_security_test",
    {
        "api_endpoint": "https://api.example.com/users",
        "http_method": "GET",
        "api_key": "Bearer xyz"
    }
)

---
### 2. vapt_agent_update_dashboard

Purpose:
Updates the visual dashboard with the latest report.

Parameter:
- report_md (string): Full markdown report

---

### 3. vapt_agent_tutor_respond

Purpose:
Provides contextual security explanations based on the VAPT report using RAG.

Inputs:
- question (string)  
- history (array)  
- report_md (string)

Capabilities:
- Handles file uploads  
- Performs vector search  
- Generates grounded answers  

---
## ⚙️ MCP Client Configuration Examples

Streamable HTTP:

```json
{
  "mcpServers": {
    "vapt_agent": {
      "url": "https://mcp-1st-birthday-vapt-agent.hf.space/gradio_api/mcp/"
    }
  }
}
```

STDIO (Claude Desktop):

```json
{
  "mcpServers": {
    "vapt_agent": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-1st-birthday-vapt-agent.hf.space/gradio_api/mcp/",
        "--transport",
        "streamable-http"
      ]
    }
  }
}
```

File upload support:

```json
"upload_files_to_gradio": {
  "command": "uvx",
  "args": ["--from", "gradio[mcp]", "gradio", "upload-mcp", "https://mcp-1st-birthday-vapt-agent.hf.space/", "<UPLOAD_DIRECTORY>"]
}
```
## 🎓 Use Cases

### For AI Assistants (Claude Desktop)
```
User: "Test the API at https://api.myapp.com/v1/products (GET method) 
       with API key Bearer abc123"
Claude: *Invokes vapt_agent_run_security_test* 
        "I've initiated a security test. The VAPT agent is now scanning 
        for vulnerabilities including injection attacks, authentication 
        issues, and security misconfigurations..."
```

### For CI/CD Pipelines
```bash
# Automated security testing in deployment pipeline
mcp-client call vapt_agent_run_security_test \
  --api_endpoint "https://staging.api.com/auth/login" \
  --http_method "POST" \
  --api_key "$STAGING_API_KEY"
```

### For Security Teams
```
# Remote security assessment without opening the web interface
# Get comprehensive reports programmatically
# Integrate with existing security workflow tools
```
---