# MCP-SOC Middleware

**MCP-Based Middleware for Integrating Agentic AI with Legacy SOC Infrastructure**

> PMICS Batch 05 | University of Dhaka, Department of CSE  
> CSE-810: Project on Cyber Security  
> Authors: Md. Abdullah Bin Salaam (H-28) · Ovishek Pal (H-54)  
> Supervisor: Prof. Dr. Mamun Or Rashid

---

## One-Command Startup

```bash
git clone https://github.com/your-org/mcp-soc-middleware.git && cd mcp-soc-middleware
cp .env.example .env          # fill in ANTHROPIC_API_KEY at minimum
docker compose up -d          # starts all 5 services
```

Wait ~90 seconds for Splunk and TheHive to initialise, then visit:

| Service | URL | Default credentials |
|---|---|---|
| MCP Middleware API | http://localhost:8000/docs | Bearer: `mcp-dev-token-change-me-in-production-abc123` |
| Splunk Web UI | http://localhost:8001 | `admin` / `changeme123!` |
| TheHive | http://localhost:9000 | `admin@thehive.local` / `secret` |
| Cortex | http://localhost:9001 | (first-run wizard) |
| Elasticsearch | http://localhost:9200 | (no auth in dev) |

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                   AI Agent Layer                     │
│         (SOCOrchestrator + Anthropic Claude)         │
└───────────────────────┬─────────────────────────────┘
                        │  MCP  (Bearer Token)
┌───────────────────────▼─────────────────────────────┐
│          MCP Unified Access Layer  :8000             │
│   FastAPI · ToolRegistry · AuditLog · RateLimit      │
└──────────┬────────────────────────┬─────────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│   SplunkAdapter     │  │   TheHiveAdapter         │
│  5 MCP tools        │  │  7 MCP tools             │
└──────────┬──────────┘  └──────────┬───────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│  Splunk Enterprise  │  │  TheHive 5 + ES 7        │
│  REST API :8089     │  │  REST API :9000          │
└─────────────────────┘  └─────────────────────────┘
```

---

## Project Structure

```
mcp-soc-middleware/
├── mcp_server/                  # FastAPI MCP server package
│   ├── main.py                  # App factory, lifespan, MCP endpoints
│   ├── core/
│   │   ├── registry.py          # Dynamic tool registry and adapter loader
│   │   └── auth.py              # Bearer token authentication dependency
│   ├── adapters/
│   │   ├── base_adapter.py      # Abstract adapter contract
│   │   ├── splunk_adapter.py    # Splunk SIEM adapter (5 tools)
│   │   └── thehive_adapter.py   # TheHive SOAR adapter (7 tools)
│   ├── middleware/
│   │   ├── audit.py             # JSONL audit logging middleware
│   │   └── rate_limit.py        # slowapi rate limiter
│   ├── models/
│   │   ├── tool_models.py       # MCP ToolDefinition, Request, Response models
│   │   └── alert_models.py      # Normalised alert / observable schemas
│   └── utils/                   # (extensible — logging helpers, etc.)
│
├── agent/
│   ├── orchestrator.py          # ReAct loop + MCP client + Anthropic API
│   ├── workflows/
│   │   └── triage_workflow.py   # Pre-built task strings for common workflows
│   └── prompts/                 # (extensible — prompt template files)
│
├── config/
│   └── settings.py              # Pydantic-Settings configuration model
│
├── tests/
│   ├── unit/adapters/
│   │   ├── test_splunk_adapter.py
│   │   └── test_thehive_adapter.py
│   ├── integration/             # (full end-to-end tests against live services)
│   └── fixtures/                # Shared test data and factory-boy factories
│
├── scripts/
│   ├── bootstrap.sh             # One-time local setup (venv + .env)
│   └── splunk_bootstrap.sh      # Generate Splunk API token post-startup
│
├── docker/
│   ├── Dockerfile               # Multi-stage image for mcp-middleware service
│   ├── splunk/
│   │   ├── inputs.conf          # Splunk monitor stanza for sample data
│   │   └── sample_alerts.json   # Synthetic SOC alerts for dev seeding
│   └── thehive/
│       └── application.conf     # TheHive minimal config pointing to ES
│
├── logs/                        # Audit JSONL logs (git-ignored)
├── docs/                        # Architecture diagrams and runbooks
├── docker-compose.yml           # Full local dev stack (5 services)
├── requirements.txt             # Pinned Python dependencies
├── pyproject.toml               # Build config, ruff, mypy, pytest settings
├── .env.example                 # All required environment variables with defaults
└── README.md                    # This file
```

---

## Local Development (without Docker)

```bash
# 1. Bootstrap virtual environment
bash scripts/bootstrap.sh
source .venv/bin/activate

# 2. Start only the platform dependencies via Docker
docker compose up -d splunk elasticsearch thehive

# 3. Generate a Splunk API token (first time only)
bash scripts/splunk_bootstrap.sh
# → Paste the printed token into .env as SPLUNK_TOKEN=...

# 4. Run the MCP server
python -m mcp_server.main
# Server starts at http://localhost:8000

# 5. In a separate terminal: run the AI agent on a triage task
python - <<'EOF'
import asyncio
from agent.orchestrator import SOCOrchestrator
from agent.workflows.triage_workflow import alert_triage_task

async def main():
    agent = SOCOrchestrator()
    result = await agent.run(alert_triage_task(time_window="-4h", severity="high"))
    print(result)

asyncio.run(main())
EOF
```

---

## Running Tests

```bash
pytest                          # all tests with coverage
pytest tests/unit -v            # unit tests only (no live services needed)
pytest tests/integration -v     # requires docker compose up -d
```

---

## MCP API Reference

All endpoints require `Authorization: Bearer <MCP_BEARER_TOKEN>`.

### `GET /tools/list`
Returns the full tool catalogue (12 tools across Splunk + TheHive adapters).

### `POST /tools/call`
```json
{
  "name": "splunk.search_alerts",
  "arguments": {
    "severity": "high",
    "earliest": "-4h",
    "limit": 50
  }
}
```

### Available Tools

| Tool | Platform | Description |
|---|---|---|
| `splunk.search_alerts` | Splunk | Search notable events by severity/time |
| `splunk.get_alert_details` | Splunk | Full field set for one event ID |
| `splunk.search_events` | Splunk | Arbitrary SPL query |
| `splunk.get_index_summary` | Splunk | Available indexes and sourcetypes |
| `splunk.acknowledge_notable` | Splunk | Update notable event status/owner |
| `thehive.create_case` | TheHive | Create a new case |
| `thehive.get_case` | TheHive | Retrieve case by ID |
| `thehive.list_cases` | TheHive | List cases by status/severity |
| `thehive.create_alert` | TheHive | Create an alert from external data |
| `thehive.add_observable` | TheHive | Add IP/domain/hash/URL to a case |
| `thehive.update_case_status` | TheHive | Update status and add summary note |
| `thehive.add_task` | TheHive | Create an analyst task inside a case |

---

## Extending with a New Adapter

1. Create `mcp_server/adapters/my_tool_adapter.py` inheriting `BaseAdapter`.
2. Implement `register_tools()` returning your `ToolDefinition` list.
3. Expose module-level `register_tools()`, `adapter_setup()`, `adapter_teardown()` functions.
4. Add the module path to `ADAPTER_MODULES` in `mcp_server/main.py`.

No changes to the registry, middleware, or AI agent are required.

---

## Environment Variables

See `.env.example` for the full annotated list. Minimum required for local dev:

```bash
ANTHROPIC_API_KEY=sk-ant-api03-...   # required for AI agent
MCP_BEARER_TOKEN=...                  # any strong random string
SPLUNK_TOKEN=...                      # from scripts/splunk_bootstrap.sh
THEHIVE_API_KEY=...                   # from TheHive UI → Admin → Users
```

---

## License

MIT © 2026 Md. Abdullah Bin Salaam & Ovishek Pal