MCP Shamash

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

Path Validation: Prevents directory traversal
Network Boundaries: CIDR-based network restrictions
Container Isolation: Docker security hardening
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

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Support

For issues and questions:

Create an issue on GitHub
Check the audit logs for troubleshooting
Review boundary enforcement logs

Deploy Server

HTTP connection URL

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables security auditing, penetration testing, and compliance validation with tools like Semgrep, Trivy, Gitleaks, and OWASP ZAP. Features strict project boundary enforcement and supports OWASP, CIS, and NIST compliance frameworks.

Appeared in Searches

CodeQL static analysis tool and semantic code analysis platform