# Offensive Security MCP Server

A professional-grade MCP server that provides an AI agent with structured, safe, and authorized penetration testing capabilities.

## Features
- **Engagement Management**: Track assessments, authorization, and status.
- **Strict Scope Engine**: Validate targets against domains, IPs, CIDRs, and wildcards.
- **Policy-Driven Execution**: Enforce risk levels (Passive $\rightarrow$ Safe $\rightarrow$ Intrusive $\rightarrow$ Destructive).
- **Controlled Executor**: Safe subprocess management with timeouts and scope validation.
- **Tool Integration**: Orchestrates industry-standard tools like Nmap, Nuclei, and Subfinder.
- **Finding Correlation**: (Phase 5+) Merge results from multiple tools into validated findings.

## Installation

### Prerequisites
- Python 3.10+
- Security tools installed in PATH (Nmap, Nuclei, etc.)

### Setup
1. Clone the repository.
2. Create a virtual environment:
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # Linux/macOS
   .venv\Scripts\activate     # Windows
   ```
3. Install dependencies:
   ```bash
   pip install .
   ```
4. Copy `.env.example` to `.env` and configure your database path.

## Connecting to OpenCode

Add the following to your MCP configuration:

```json
{
  "mcpServers": {
    "offsec-mcp": {
      "command": "python",
      "args": ["D:/offsec-mcp/src/server.py"],
      "env": {
        "PYTHONPATH": "D:/offsec-mcp/src"
      }
    }
  }
}
```

## Usage Example
1. **Create Engagement**: `engagement_create(name="Client-X-Web-Assessment", authorization_confirmed=true)`
2. **Set Scope**: `scope_add(target="example.test", entry_type="domain")`
3. **Verify Scope**: `scope_check(target="sub.example.test")`
4. **Check Tools**: `tool_status()`