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