Content
# Tool List
## Overview
This project integrates OWASP ZAP vulnerability scanning tool with MCP (Model Context Protocol) to enable AI assistants (such as Claude Desktop, Kiro) to directly execute website security scans and generate reports.
## Features
- 🔍 **Automated Vulnerability Scanning** - Supports Baseline (quick) and Full (comprehensive attack) scanning modes
- 🕷️ **Aggressive Mode** - Enables AJAX Spider, Alpha rules, and high-intensity attacks
- 📊 **Chinese Report** - Automatically generates Word format report with risk statistics charts
- 🐳 **Docker Containerization** - Completely containerized deployment, no additional dependencies required
## System Requirements
- Docker Desktop (macOS / Windows / Linux)
- Claude Desktop or Kiro IDE (MCP-enabled AI clients)
## Project Structure
```
zap-auto/
├── build.sh # One-click build script
├── README.md
├── zap-mcp/
│ ├── Dockerfile.mcp # MCP Server image file
│ └── zap_mcp_server.py # MCP Server main program
└── zap-reporter/
├── Dockerfile.reporter # Report generator image file
├── requirements.txt # Python dependencies
└── zap_report_gen.py # Word report generator
```
## Installation Steps
### 1. Build Docker Images
```bash
# Give execution permission
chmod +x build.sh
# Run build script
./build.sh
```
This will automatically:
- Create a shared Docker Volume (`zap_shared_data`)
- Build `zap-reporter` image
- Build `zap-mcp-server` image
### 2. Create Report Output Folder
```bash
mkdir -p ~/Documents/zap-output
```
### 3. Configure MCP Client
#### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or corresponding path:
```json
{
"mcpServers": {
"zap-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
"-v", "zap_shared_data:/app/data",
"-v", "/Users/YOUR_USERNAME/Documents/zap-output:/output",
"zap-mcp-server"
]
}
}
}
```
> ⚠️ Please replace `YOUR_USERNAME` with your actual username
#### Kiro IDE
Edit `~/.kiro/settings/mcp.json`:
```json
{
"mcpServers": {
"zap-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v", "/var/run/docker.sock:/var/run/docker.sock",
"-v", "zap_shared_data:/app/data",
"-v", "/Users/YOUR_USERNAME/Documents/zap-output:/output",
"zap-mcp-server"
]
}
}
}
```
### 4. Restart AI Client
After configuration, restart Claude Desktop or Kiro IDE to load MCP Server.
## Usage
### Available Tools (MCP Tools)
| Tool Name | Description |
|---------|------|
| `scan_job` | 【Step 1】Initiate ZAP vulnerability scanning task |
| `get_analysis` | 【Step 2】Check scanning progress, generate report after completion |
| `ai_insights` | 【Step 3】Export report to local folder |
### Operating Process
#### Step 1: Initiate Scanning
Tell AI assistant:
```
Please perform vulnerability scanning on http://example.com
```
Or specify advanced options:
```
Please perform Full scanning on http://example.com and enable Aggressive mode
```
**Parameter Description:**
| Parameter | Description | Default Value |
|-----|------|-------|
| `target_url` | Target URL | (Required) |
| `scan_type` | `baseline` (quick) or `full` (comprehensive attack) | `baseline` |
| `aggressive` | Enable aggressive mode | `false` |
**Scanning Mode Comparison:**
| Mode | Description | Estimated Time |
|-----|------|---------|
| Baseline | Passive scanning, no attack requests sent to target | 1-5 minutes |
| Full | Active attack scanning, testing various vulnerabilities | 10-60 minutes |
| Full + Aggressive | Includes AJAX Spider, Alpha rules, high-intensity attacks | 30 minutes - several hours |
#### Step 2: Check Progress
```
Check scanning status
```
System will report current progress:
- 🕷️ Performing spidering
- 👀 Performing passive scanning
- 🔥 Performing active scanning
After scanning completion, report will be generated and summary displayed:
```
✅ Task completed!
🔴 High Risk: 2 | 🟠 Medium Risk: 15
```
#### Step 3: Export Report
```
Please export report
```
Report will be saved to:
- **Word Report**: `~/Documents/zap-output/Scan_Report_YYYYMMDD.docx`
- **JSON Raw Data**: `~/Documents/zap-output/ZAP-Report.json`
## Report Content
Generated Word report includes:
1. **Cover Page** - Company name, scanning tool, date, target URL
2. **Scanning Result Summary** - Risk distribution pie chart, statistics table
3. **Vulnerability Analysis** - Each vulnerability's:
- Vulnerability name (English and Chinese)
- Risk level (color-coded)
- Vulnerability description
- Recommended fix
## Advanced Settings
### Custom Company Name
Edit `zap-reporter/zap_report_gen.py`, modify `company_name` parameter:
```python
generate_word_report(json_file, word_file, company_name="Your Company Name")
```
### Add Logo
Place `logo.png` in Docker Volume:
```bash
docker run --rm -v zap_shared_data:/data -v $(pwd):/src alpine cp /src/logo.png /data/
```
## Troubleshooting
### MCP Server Connection Issue
1. Confirm Docker Desktop is running
2. Check MCP configuration file path
3. Rebuild images: `./build.sh`
4. Restart AI client
### Scanning Failure
1. Confirm target URL is accessible
2. Check Docker container logs:
```bash
docker logs zap-scanner-job
```
### Report Export Issue
1. Confirm output folder exists:
```bash
mkdir -p ~/Documents/zap-output
```
2. Check Volume content:
```bash
docker run --rm -v zap_shared_data:/data alpine ls -la /data
```
## Technical Architecture
```
┌─────────────────┐ MCP Protocol ┌──────────────────┐
│ Claude/Kiro │ ◄──────────────────► │ zap-mcp-server │
│ (AI Client) │ │ (Docker) │
└─────────────────┘ └────────┬─────────┘
│
│ Docker API
▼
┌─────────────────────────────────────────┐
│ Docker Engine │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ zaproxy/ │ │ zap-reporter │ │
│ │ zap-stable │ │ (Word Report) │ │
│ └──────┬──────┘ └────────┬────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ zap_shared_data (Volume) │ │
│ │ - ZAP-Report.json │ │
│ │ - Scan_Report_YYYYMMDD.docx │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘
```
## Prompt Example
You are a seasoned automated penetration testing expert. Your task is to follow the SOP to detect the target:
【Phase 1: Reconnaissance】
1. Please use `nmap_recon` tool on http://nl-bwapp.turn2cloud.net with `force_rescan=True`.
2. Analyze returned results (xml), identify all entry points, and target OS version (revealed by web service), CVE list.
【Phase 2: Scanning Strategy】
1. Based on nmap-scanned ports, combine FQDN to form various connection methods and write to report.
2. If login page exists, call `login_and_get_cookie` to obtain credentials. `Account` bee `Password` bug
3. Login URL - http://nl-bwapp.turn2cloud.net/portal.php
4. If Cookie exists, prepare for next step call using `auth_header='Cookie'`.
5. Use aggressive scanning: `scan_type='full', aggressive=True`.
6. Save combined connection methods and URI from step 3 for phase 3.
【Phase 3: Execution】
1. Call `scan_job` for phase 2 step 6 connection methods.
2. Monitor progress using `check_status`.
【Phase 4: Analysis and Reporting】
1. After scanning completion, call `get_analysis` to obtain Markdown data.
2. Analyze vulnerabilities using your cybersecurity knowledge (don't just repeat data).
- Analyze potential business impact.
- Provide specific code fix examples.
3. Summarize analysis (Executive Summary) and detailed fix suggestions (Solutions JSON), pass to `ai_insights` tool.
4. Finally, execute `export_report` to download graphical report.
* Important rule: When generating solutions JSON, Key (key) must strictly use English vulnerability original name from scanning report, don't translate to Chinese, and don't simplify.
Value content should be written in Traditional Chinese.
Example command:
"Please analyze report and generate solutions JSON. Note: JSON Key must be English original name like 'Absence of Anti-CSRF Tokens', don't write as 'CSRF missing'. Content should be in Chinese."
## License Statement
This project uses MIT License.
OWASP ZAP is an open-source project, please refer to [OWASP ZAP official website](https://www.zaproxy.org/).
## Contribution
Welcome to submit issues or pull requests!
