# 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

```bash
npm install
npm run build
```

### Running the Server

```bash
npm start
```

Or for development:

```bash
npm run dev
```

### Demo

Experience all features with the interactive demo:

```bash
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:

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

## Available Tools

### scan_project
Comprehensive security scan of project directory.

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

### scan_network
Network scanning within project boundaries.

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

### pentest_application
Penetration testing of deployed applications.

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

### check_compliance
Compliance framework validation.

```json
{
  "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

```bash
npm run build
```

### Testing

```bash
npm test
npm run test:coverage
```

### Linting

```bash
npm run lint
npm run format
```

## Container Usage

### Build Scanner Containers

```bash
# 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

```bash
# 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:

```yaml
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