# Huntress SAT MCP Server

A Model Context Protocol (MCP) server for the Huntress SAT (formerly Curricula) Security Awareness Training API.

## Features

- **Full API Coverage**: Tools for managing organizations, learners, phishing campaigns, training courses, assignments, and reports
- **OAuth2 Authentication**: Secure client credentials flow for API access
- **RBAC Support**: Role-based access control (disabled by default, easily enabled)
- **Multiple Transports**: Supports both stdio and streamable-http transports
- **Docker Ready**: Production-ready Docker container with multi-transport support

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/example/huntress-sat-mcp.git
cd huntress-sat-mcp

# Install with pip
pip install -e .

# Or with uv (recommended)
uv pip install -e .
```

### Using Docker

```bash
# Build the image
docker build -t huntress-sat-mcp .

# Or use docker-compose
docker-compose build
```

## Configuration

The server is configured via environment variables. All variables are prefixed with `HUNTRESS_SAT_`.

### Required Variables

| Variable | Description |
|----------|-------------|
| `HUNTRESS_SAT_CLIENT_ID` | OAuth2 Client ID from Huntress SAT |
| `HUNTRESS_SAT_CLIENT_SECRET` | OAuth2 Client Secret from Huntress SAT |

### Optional Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `HUNTRESS_SAT_API_BASE_URL` | `https://api.curricula.com/api/v1` | API base URL |
| `HUNTRESS_SAT_TOKEN_URL` | `https://api.curricula.com/oauth/token` | OAuth2 token endpoint |
| `HUNTRESS_SAT_TRANSPORT` | `stdio` | Transport mode: `stdio` or `streamable-http` |
| `HUNTRESS_SAT_HOST` | `127.0.0.1` | Host for HTTP transport |
| `HUNTRESS_SAT_PORT` | `8000` | Port for HTTP transport |
| `HUNTRESS_SAT_RBAC_ENABLED` | `false` | Enable role-based access control |
| `HUNTRESS_SAT_RBAC_DEFAULT_ROLE` | `viewer` | Default RBAC role |
| `HUNTRESS_SAT_REQUEST_TIMEOUT` | `30.0` | Request timeout in seconds |
| `HUNTRESS_SAT_MAX_RETRIES` | `3` | Max retry attempts |

### Environment File

Create a `.env` file in the project root:

```env
HUNTRESS_SAT_CLIENT_ID=your_client_id
HUNTRESS_SAT_CLIENT_SECRET=your_client_secret
HUNTRESS_SAT_RBAC_ENABLED=false
```

## Usage

### Running with stdio Transport

```bash
# Direct execution
huntress-sat-mcp

# Or with Python
python -m huntress_sat_mcp.server

# With environment variables
HUNTRESS_SAT_CLIENT_ID=xxx HUNTRESS_SAT_CLIENT_SECRET=yyy huntress-sat-mcp
```

### Running with Streamable HTTP Transport

```bash
# Set transport mode
export HUNTRESS_SAT_TRANSPORT=streamable-http
export HUNTRESS_SAT_HOST=0.0.0.0
export HUNTRESS_SAT_PORT=8000

huntress-sat-mcp
```

### Using Docker

```bash
# HTTP Transport (default in docker-compose)
docker-compose up huntress-sat-mcp-http

# Stdio Transport
docker-compose --profile stdio up huntress-sat-mcp-stdio

# Development mode with RBAC enabled
docker-compose --profile dev up huntress-sat-mcp-dev
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "huntress-sat": {
      "command": "huntress-sat-mcp",
      "env": {
        "HUNTRESS_SAT_CLIENT_ID": "your_client_id",
        "HUNTRESS_SAT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

For HTTP transport:

```json
{
  "mcpServers": {
    "huntress-sat": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

For Docker Compose (stdio transport):

```json
{
  "mcpServers": {
    "huntress-sat": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/path/to/docker-compose.yml",
        "run", "--rm", "-i",
        "huntress-sat-mcp-stdio"
      ]
    }
  }
}
```

> **Note**: Replace `/path/to/docker-compose.yml` with the absolute path to your docker-compose.yml file. The `-i` flag is required for interactive stdin communication with the MCP server. Credentials are loaded from the `.env` file in the project directory.

## Available Tools

### Organization Management

| Tool | Description |
|------|-------------|
| `list_organizations` | List all organizations with pagination and search |
| `get_organization` | Get details of a specific organization |

### Learner Management

| Tool | Description |
|------|-------------|
| `list_learners` | List learners with filters (org, department, tag, status) |
| `get_learner` | Get learner details |
| `create_learner` | Create a new learner |
| `update_learner` | Update learner information |
| `delete_learner` | Delete a learner |

### Phishing Campaigns

| Tool | Description |
|------|-------------|
| `list_phishing_campaigns` | List campaigns with filters and sorting |
| `get_phishing_campaign` | Get campaign details and metrics |
| `get_phishing_results` | Get individual learner results for a campaign |
| `list_phishing_templates` | List available phishing templates |

### Training

| Tool | Description |
|------|-------------|
| `list_training_courses` | List available training courses |
| `get_training_course` | Get course details |
| `list_assignments` | List training assignments |
| `get_assignment` | Get assignment details |
| `create_assignment` | Create a new training assignment |

### Reports

| Tool | Description |
|------|-------------|
| `get_learner_progress` | Get training progress for learners |
| `get_report_summary` | Get summary statistics and metrics |

### Organization Structure

| Tool | Description |
|------|-------------|
| `list_departments` | List departments with learner counts |
| `list_tags` | List tags with learner counts |

### RBAC

| Tool | Description |
|------|-------------|
| `get_rbac_status` | Get current RBAC configuration and permissions |

## Role-Based Access Control (RBAC)

RBAC is disabled by default. When enabled, access to tools is restricted based on user roles.

### Available Roles

| Role | Description |
|------|-------------|
| `admin` | Full access to all tools |
| `manager` | Can read and write, but cannot delete learners |
| `analyst` | Can read all data and generate reports |
| `viewer` | Read-only access to all data |

### Permissions

- `org:read`, `org:write` - Organization management
- `learner:read`, `learner:write`, `learner:delete` - Learner management
- `phishing:read`, `phishing:write` - Phishing campaign access
- `training:read`, `training:write` - Training course access
- `assignment:read`, `assignment:write` - Assignment management
- `report:read`, `report:generate` - Report access

### Enabling RBAC

```bash
export HUNTRESS_SAT_RBAC_ENABLED=true
export HUNTRESS_SAT_RBAC_DEFAULT_ROLE=viewer
```

## Development

### Setup

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run linting
ruff check src/

# Run type checking
mypy src/

# Run tests
pytest
```

### Project Structure

```
huntress-sat-mcp/
├── src/
│   └── huntress_sat_mcp/
│       ├── __init__.py      # Package initialization
│       ├── config.py        # Configuration management
│       ├── models.py        # Pydantic models
│       ├── client.py        # API client with OAuth2
│       ├── rbac.py          # Role-based access control
│       └── server.py        # MCP server with tools
├── Dockerfile               # Multi-stage Docker build
├── docker-compose.yml       # Docker Compose configurations
├── pyproject.toml           # Project configuration
└── README.md
```

## API Reference

This MCP server wraps the Huntress SAT (Curricula) API. For detailed API documentation, visit:

- [Huntress SAT Support](https://support.huntress.io/hc/en-us/categories/22524323456659-Huntress-Managed-Security-Awareness-Training-SAT)
- [Curricula API Documentation](https://curricula.stoplight.io/docs/curricula-api/)

## License

MIT License