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

• 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

npm install npm run build

npm start

Or for development:

npm run dev

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

Configure in your MCP-compatible client:

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

Comprehensive security scan of project directory.

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

Network scanning within project boundaries.

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

Penetration testing of deployed applications.

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

Compliance framework validation.

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

• Automatic discovery of Docker Compose networks
• Kubernetes service detection
• Package.json analysis for Node.js apps
• Local service enumeration

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

• System path access (/etc, /usr, /var)
• External network scanning
• Management port access (22, 3389, 445)
• Privilege escalation attempts

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 

npm run build

npm test npm run test:coverage

npm run lint npm run format

# Build Semgrep scanner docker build -f containers/Dockerfile.semgrep -t shamash-semgrep . # Build all scanners docker-compose -f containers/docker-compose.scanners.yml build

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

• 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)

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

• 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

• Inventory and Control of Assets
• Access Control Management
• Continuous Vulnerability Management
• Network Infrastructure Management
• Data Protection

• Identify: Asset management, governance
• Protect: Access control, data security
• Detect: Security monitoring, detection processes
• Respond: Response planning, incident management
• Recover: Recovery planning, improvements

• No offensive capabilities
• Read-only filesystem operations
• No credential harvesting
• Audit trail for all operations

• Multiple validation layers
• Real-time monitoring
• Automatic violation detection
• Emergency shutdown capability

• Per-scan limits (1000 tokens)
• Rate limiting (5000/minute, 50000/hour)
• Usage tracking and reporting

MIT License

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

For issues and questions:

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