MCP Shamash - Security Audit & Compliance Server

A Model Context Protocol (MCP) server for security auditing, penetration testing, and compliance validation with strict project boundary enforcement.

Features

• Project-Scoped Security Scanning: Never escapes project boundaries

• Multiple Security Tools: Semgrep, Trivy, Gitleaks, OWASP ZAP, and more

• Network Penetration Testing: Safe network scanning within project scope

• Compliance Validation: OWASP, CIS, NIST, ISO 27001 frameworks

• Containerized Execution: Isolated scanner execution with Docker

• Parallel Processing: Concurrent scanner execution for speed

• Intelligent Caching: Results cached for performance optimization

• Token Efficiency: <1000 tokens per operation with monitoring

• Comprehensive Audit Logging: Complete operation trails

• Real-Time Boundary Enforcement: Multi-layer security isolation

Quick Start

Installation

npm install
npm run build

Running the Server

npm start

Or for development:

npm run dev

Demo

Experience all features with the interactive demo:

node demo.js

This demonstrates:

• Real security tool integration (Semgrep, Trivy, Gitleaks, OWASP ZAP)

• Boundary enforcement (prevents external access)

• Network scanning within project scope

• Compliance validation (OWASP, CIS, NIST)

• Caching performance improvements

• Parallel scanner execution

MCP Integration

Configure in your MCP-compatible client:

{
  "mcpServers": {
    "shamash": {
      "command": "node",
      "args": ["/path/to/mcp_shamash/dist/index.js"]
    }
  }
}

Available Tools

scan_project

Comprehensive security scan of project directory.

{
  "name": "scan_project",
  "arguments": {
    "path": "/path/to/project",
    "profile": "standard",
    "tools": ["semgrep", "trivy", "gitleaks"]
  }
}

scan_network

Network scanning within project boundaries.

{
  "name": "scan_network",
  "arguments": {
    "target": "127.0.0.1",
    "ports": "80,443",
    "serviceDetection": true
  }
}

pentest_application

Penetration testing of deployed applications.

{
  "name": "pentest_application",
  "arguments": {
    "targetUrl": "http://localhost:3000",
    "testTypes": ["sql_injection", "xss", "csrf"],
    "depth": "thorough"
  }
}

check_compliance

Compliance framework validation.

{
  "name": "check_compliance",
  "arguments": {
    "path": "/path/to/project",
    "frameworks": ["OWASP", "CIS", "NIST"]
  }
}

Security Boundaries

Project Scope Detection

• Automatic discovery of Docker Compose networks

• Kubernetes service detection

• Package.json analysis for Node.js apps

• Local service enumeration

Multi-Layer Enforcement

1. Path Validation: Prevents directory traversal

2. Network Boundaries: CIDR-based network restrictions

3. Container Isolation: Docker security hardening

4. Resource Limits: Memory, CPU, and process constraints

Blocked Operations

• System path access (/etc, /usr, /var)

• External network scanning

• Management port access (22, 3389, 445)

• Privilege escalation attempts

Architecture

mcp-shamash/
├── src/
│   ├── core/           # MCP server core
│   ├── boundaries/     # Scope enforcement
│   ├── scanners/       # Tool integrations
│   ├── compliance/     # Framework validators
│   └── utils/          # Token management, audit logging
├── containers/         # Docker configurations
├── rules/             # Security rules
└── tests/            # Test suites

Development

Building

npm run build

Testing

npm test
npm run test:coverage

Linting

npm run lint
npm run format

Container Usage

Build Scanner Containers

# Build Semgrep scanner
docker build -f containers/Dockerfile.semgrep -t shamash-semgrep .

# Build all scanners
docker-compose -f containers/docker-compose.scanners.yml build

Run Isolated Scan

# Set target path and run scan
export SHAMASH_TARGET_PATH=/path/to/project
docker-compose -f containers/docker-compose.scanners.yml up semgrep

Configuration

Environment Variables

• SHAMASH_MAX_TOKENS_PER_SCAN: Token limit per scan (default: 1000)

• SHAMASH_MAX_TOKENS_PER_HOUR: Hourly token limit (default: 50000)

• SHAMASH_AUDIT_LOG_PATH: Audit log location (default: ./audit.log)

Project Configuration

Create .shamash.yml in project root:

networks:
  allowed:
    - 172.20.0.0/16
    - 127.0.0.1/32
  blocked:
    - 10.0.0.0/8

ports:
  allowed: [80, 443, 3000, 8080]
  blocked: [22, 3389, 445]

tools:
  semgrep:
    config: "auto"
    timeout: 300
  trivy:
    severity: "HIGH,CRITICAL"
  gitleaks:
    entropy_threshold: 4.5

Compliance Frameworks

OWASP Top 10 Coverage

• A01: Broken Access Control

• A02: Cryptographic Failures

• A03: Injection

• A04: Insecure Design

• A05: Security Misconfiguration

• A06: Vulnerable Components

• A07: Authentication Failures

• A08: Software/Data Integrity

• A09: Security Logging

• A10: Server-Side Request Forgery

CIS Controls

• Inventory and Control of Assets

• Access Control Management

• Continuous Vulnerability Management

• Network Infrastructure Management

• Data Protection

NIST Cybersecurity Framework

• Identify: Asset management, governance

• Protect: Access control, data security

• Detect: Security monitoring, detection processes

• Respond: Response planning, incident management

• Recover: Recovery planning, improvements

Security Considerations

Defensive Only

• No offensive capabilities

• Read-only filesystem operations

• No credential harvesting

• Audit trail for all operations

Boundary Enforcement

• Multiple validation layers

• Real-time monitoring

• Automatic violation detection

• Emergency shutdown capability

Token Management

• Per-scan limits (1000 tokens)

• Rate limiting (5000/minute, 50000/hour)

• Usage tracking and reporting

License

MIT License

Contributing

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass

5. Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub

• Check the audit logs for troubleshooting

• Review boundary enforcement logs