dhqanh-rcc/stackrox-mcp

StackRox MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure access to StackRox security data and alerts.

🚀 Features

• Security Alerts: List and query security alerts from StackRox
• Alert Counting: Get total count of security alerts
• MCP Protocol: Standard MCP interface for AI assistant integration
• Secure Authentication: Token-based authentication with StackRox API

📋 Prerequisites

• Go 1.23 or later
• Access to a StackRox/Red Hat Advanced Cluster Security (RHACS) instance
• StackRox API token with appropriate permissions

🔧 Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/stackrox-mcp.git
cd stackrox-mcp

# Build the binary
go build -o stackrox-mcp ./cmd/main.go

# Run the server
./stackrox-mcp

Using Go Install

go install github.com/yourusername/stackrox-mcp/cmd@latest

⚙️ Configuration

The server requires the following environment variables:

Creating a StackRox API Token

1. Log in to your StackRox Central instance
2. Navigate to Platform Configuration → Integrations
3. Click API Token → Generate Token
4. Assign appropriate roles (minimum: read access to alerts)
5. Copy the generated token

Configuration File

Create a .env file in the project root:

STACKROX_ENDPOINT=https://stackrox.example.com
STACKROX_API_TOKEN=your-api-token-here

🎯 Usage

Running the Server

# With environment variables
export STACKROX_ENDPOINT="https://stackrox.example.com"
export STACKROX_API_TOKEN="your-api-token"
./stackrox-mcp

# With .env file
./stackrox-mcp

Available MCP Tools

The server exposes the following tools via the MCP protocol:

1. list_alerts

List security alerts from StackRox.

Parameters:

• limit (optional, number): Maximum number of alerts to return (default: 10)

Example:

{
  "name": "list_alerts",
  "arguments": {
    "limit": 20
  }
}

2. count_alerts

Get the total count of security alerts.

Parameters: None

Example:

{
  "name": "count_alerts",
  "arguments": {}
}

🔌 Integrating with AI Assistants

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stackrox": {
      "command": "/path/to/stackrox-mcp",
      "env": {
        "STACKROX_ENDPOINT": "https://stackrox.example.com",
        "STACKROX_API_TOKEN": "your-api-token"
      }
    }
  }
}

Other MCP Clients

The server implements the standard MCP protocol and works with any MCP-compatible client:

# Start the server (stdio mode)
./stackrox-mcp

🏗️ Architecture

┌─────────────────┐
│   AI Assistant  │
│   (Claude, etc) │
└────────┬────────┘
         │ MCP Protocol
         │ (stdio)
┌────────▼────────┐
│  StackRox MCP   │
│     Server      │
└────────┬────────┘
         │ HTTPS/REST
         │
┌────────▼────────┐
│   StackRox      │
│   Central API   │
└─────────────────┘

Components

• cmd/main.go: Entry point and MCP server setup
• internal/config: Configuration management
• internal/service: StackRox API client and business logic
• generated/http: Auto-generated HTTP client from OpenAPI spec

🔐 Security

Best Practices

1. Token Security

   • Store API tokens securely (use environment variables or secret managers)
   • Never commit tokens to version control
   • Rotate tokens regularly
   • Use read-only tokens when possible

2. Network Security

   • Always use HTTPS for StackRox connections
   • Validate TLS certificates in production
   • Use network policies to restrict access

3. Least Privilege

   • Grant minimal required permissions to API tokens
   • Use separate tokens for different environments

Security Scanning

This project uses:

• Trivy: Container vulnerability scanning
• Gosec: Go security code analysis
• Dependabot: Dependency vulnerability alerts

See for CI/CD security details.

🧪 Development

Prerequisites

• Go 1.23+
• Docker (for container builds)
• Make (optional)

Setup Development Environment

# Clone repository
git clone https://github.com/yourusername/stackrox-mcp.git
cd stackrox-mcp

# Install dependencies
go mod download

# Run tests
go test -v ./...

# Run with race detection
go test -race ./...

# Build
go build -o stackrox-mcp ./cmd/main.go

Project Structure

stackrox-mcp/
├── cmd/
│   └── main.go              # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go        # Configuration loading
│   └── service/
│       └── stackrox.go      # StackRox API client
├── generated/
│   └── http/                # Generated API client code
├── .github/
│   └── workflows/           # CI/CD workflows
├── Dockerfile               # Container image definition
├── go.mod                   # Go module definition
└── README.md               # This file

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific package
go test ./internal/service/...

Code Quality

# Run linter
golangci-lint run

# Format code
go fmt ./...

# Check for security issues
gosec ./...

📦 Building

Binary

# Build for current platform
go build -o stackrox-mcp ./cmd/main.go

# Build with optimizations
go build -ldflags="-s -w" -trimpath -o stackrox-mcp ./cmd/main.go

# Cross-compile for different platforms
GOOS=linux GOARCH=amd64 go build -o stackrox-mcp-linux-amd64 ./cmd/main.go
GOOS=darwin GOARCH=arm64 go build -o stackrox-mcp-darwin-arm64 ./cmd/main.go
GOOS=windows GOARCH=amd64 go build -o stackrox-mcp-windows-amd64.exe ./cmd/main.go

Docker Image

# Build image
docker build -t stackrox-mcp:latest .

# Run container
docker run -e STACKROX_ENDPOINT="https://stackrox.example.com" \
           -e STACKROX_API_TOKEN="your-token" \
           stackrox-mcp:latest

# Build multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 -t stackrox-mcp:latest .

🚢 Deployment

Docker Compose

version: '3.8'
services:
  stackrox-mcp:
    image: yourusername/stackrox-mcp:latest
    environment:
      - STACKROX_ENDPOINT=https://stackrox.example.com
      - STACKROX_API_TOKEN=${STACKROX_API_TOKEN}
    restart: unless-stopped

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: stackrox-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: stackrox-mcp
  template:
    metadata:
      labels:
        app: stackrox-mcp
    spec:
      containers:
      - name: stackrox-mcp
        image: yourusername/stackrox-mcp:latest
        env:
        - name: STACKROX_ENDPOINT
          value: "https://stackrox.example.com"
        - name: STACKROX_API_TOKEN
          valueFrom:
            secretKeyRef:
              name: stackrox-mcp-secret
              key: api-token

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write tests for new features
• Follow Go best practices and idioms
• Run go fmt and golangci-lint before committing
• Update documentation for API changes
• Add examples for new features

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• MCP Go SDK - Model Context Protocol implementation
• StackRox - Kubernetes security platform
• Red Hat Advanced Cluster Security - Enterprise Kubernetes security

📚 Additional Resources

• Model Context Protocol Specification
• StackRox API Documentation
• - CI/CD documentation
• MCP SDK Documentation

🐛 Troubleshooting

Common Issues

Issue: Connection refused to StackRox

Solution: Verify STACKROX_ENDPOINT is correct and accessible
Check: curl -k https://your-stackrox-instance/v1/ping

Issue: Authentication failed

Solution: Verify API token is valid and has correct permissions
Check: Token hasn't expired and has read access to alerts

Issue: No alerts returned

Solution: Check if alerts exist in StackRox
Check: Verify token has permission to view alerts

Issue: MCP client can't connect

Solution: Ensure server is running in stdio mode
Check: Verify client configuration path to binary

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report security issues to security@example.com

📈 Status

Made with ❤️ for secure Kubernetes deployments