Homelab MCP Server

# Security Policy

**Version:** 1.0.0
**Last Updated:** 2026-02-10

## Reporting Security Vulnerabilities

If you discover a security vulnerability in synapse-mcp, please report it responsibly:

1. **Do NOT** open a public GitHub issue
2. Email security details to: jmagar@users.noreply.github.com (or open a private security advisory on GitHub)
3. Include:
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact
   - Suggested fix (if any)

We will acknowledge receipt within 48 hours and provide a timeline for remediation.

---

## Known Security Issues

### Critical Vulnerabilities

#### SEC-C1: @modelcontextprotocol/sdk CVE (GHSA-345p-7cg4-v4c7)

**Severity:** Critical (CVSS 8.2)
**Status:** Fix available - upgrade required
**Affected Versions:** All versions using `@modelcontextprotocol/sdk` <= 1.25.3

**Description:**
The MCP SDK has a cross-client data leak vulnerability when using HTTP transport mode. In multi-client scenarios, one client's Docker management commands, container details, or SSH outputs could leak into another client's response.

**Impact:**

- Sensitive container environment variables exposed to other clients
- SSH command outputs visible across sessions
- Host configurations leaked to unauthorized clients

**Remediation:**

```bash
# Update package.json
"@modelcontextprotocol/sdk": "^1.26.0"

# Reinstall dependencies
pnpm install

# Rebuild
pnpm run build
```

**Verification:**

```bash
# Check installed version
pnpm list @modelcontextprotocol/sdk

# Should show >= 1.26.0
```

**Workaround (if upgrade not possible):**
Use stdio transport mode only (default). Avoid HTTP transport until upgraded.

---

### High Severity Issues

#### SEC-H2: Command Allowlist Bypass (Historical - Fixed)

**Severity:** High (CVSS 7.2) - historical
**Status:** Fixed
**Affected:** Older builds that supported bypass behavior
**Risk:** Arbitrary command execution (historical)

**Description:**
Current behavior enforces a fixed command allowlist in
`src/utils/command-security.ts` using `ALLOWED_COMMANDS` from `src/constants.ts`.
`SYNAPSE_ALLOW_ANY_COMMAND` no longer disables validation and is ignored.

**Default Allowed Commands:**

- Read operations: `cat`, `head`, `tail`, `grep`, `rg`, `find`, `ls`, `tree`
- Info operations: `stat`, `file`, `du`, `df`, `pwd`, `hostname`, `uptime`, `whoami`
- Text processing: `wc`, `sort`, `uniq`, `diff`

**Current Risk Model:**

- Only allowlisted base commands are permitted (`cat`, `grep`, `find`, `ls`, etc.)
- Disallowed commands (`rm`, `curl`, `sudo`, shells) are rejected
- Base command character validation blocks shell metacharacter injection

**Remediation Status:**

- Keep `ALLOWED_COMMANDS` restricted to read-oriented operations
- Review allowlist changes as security-sensitive modifications

**Detection:**

```bash
# Validate fixed behavior (command should be rejected)
pnpm test src/utils/command-security.test.ts
```

---

#### SEC-H4: Insecure SSH Host Key Acceptance

**Severity:** High (CVSS 6.8)
**Affected:** All SSH connections to new hosts
**Risk:** Man-in-the-middle attacks

**Description:**
The server uses `StrictHostKeyChecking=accept-new` for SSH connections, which automatically trusts the **first** key presented by any host. An attacker performing MITM on the first connection can inject their own SSH key.

**Attack Scenario:**

1. Attacker performs ARP spoofing or DNS hijacking
2. First connection to host, attacker presents malicious SSH key
3. Server trusts it without verification
4. All subsequent traffic intercepted and modifiable

**Remediation:**

**Option 1: Pre-seed known_hosts (Recommended)**

```bash
# Add host keys before first connection
ssh-keyscan -H hostname >> ~/.ssh/known_hosts
ssh-keyscan -H 192.168.1.100 >> ~/.ssh/known_hosts

# For all hosts in config
for host in host1 host2 host3; do
  ssh-keyscan -H $host >> ~/.ssh/known_hosts
done
```

**Option 2: Manual verification on first connection**

```bash
# Connect manually first, verify fingerprint
ssh user@hostname

# Compare fingerprint with out-of-band verification:
# - Console/IPMI access
# - Physical access
# - Trusted admin confirmation
```

**Option 3: Use certificate-based SSH (Advanced)**

```bash
# Configure SSH certificate authority
# See: https://smallstep.com/blog/use-ssh-certificates/
```

**Detection:**

```bash
# Check if host key exists in known_hosts
ssh-keygen -F hostname

# View host key fingerprint
ssh-keygen -l -f ~/.ssh/known_hosts | grep hostname
```

---

#### SEC-M1: HTTP Mode Authentication Is Optional (Configuration Risk)

**Severity:** Medium (CVSS 6.5)
**Affected:** HTTP transport mode (`--http` flag)
**Risk:** Unauthorized access to Docker/SSH operations

**Description:**
HTTP mode (`node dist/index.js --http`) supports API-key authentication via
`SYNAPSE_API_KEY` (`X-API-Key` header). If `SYNAPSE_API_KEY` is not set,
authentication is disabled and requests are accepted.

**Current State:**

- Default bind address: `127.0.0.1` (localhost only) - provides network isolation
- Setting `SYNAPSE_HOST=0.0.0.0` exposes server to all network interfaces
- CSRF protection middleware is enabled on `/mcp`
- API key auth is available and strongly recommended for HTTP mode

**Remediation:**

**For Development (Local Only):**

```bash
# Bind to localhost only (default)
node dist/index.js --http

# Server accessible only from local machine
# http://127.0.0.1:53000/mcp
```

**Enable built-in auth:**

```bash
export SYNAPSE_API_KEY='replace-with-random-secret'
node dist/index.js --http
```

**For Production (Reverse Proxy with Auth):**

**Nginx Example:**

```nginx
# /etc/nginx/sites-available/synapse-mcp
server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    # TLS certificates (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    # HTTP Basic Authentication
    auth_basic "Synapse MCP Access";
    auth_basic_user_file /etc/nginx/.htpasswd;

    # Rate limiting
    limit_req_zone $binary_remote_addr zone=mcp_limit:10m rate=10r/s;
    limit_req zone=mcp_limit burst=20 nodelay;

    # Health check (no auth)
    location /health {
        auth_basic off;
        proxy_pass http://127.0.0.1:53000/health;
    }

    # MCP endpoint (requires auth)
    location /mcp {
        proxy_pass http://127.0.0.1:53000/mcp;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

**Create credentials:**

```bash
sudo apt install apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd mcpuser
sudo nginx -t
sudo systemctl reload nginx
```

**Caddy Example:**

```caddy
mcp.yourdomain.com {
    basicauth /mcp/* {
        mcpuser $2a$14$...hashed_password...
    }

    reverse_proxy /health 127.0.0.1:53000
    reverse_proxy /mcp 127.0.0.1:53000
}
```

**Detection:**

```bash
# Check if HTTP mode is running without auth
curl http://localhost:53000/health
# If accessible without credentials, auth is missing

# Check bind address
ss -tuln | grep 53000
# If 0.0.0.0:53000, exposed to all interfaces
```

---

## Security Best Practices

### 1. Connection Security

**SSH Configuration:**

- Use SSH protocol for all Docker connections (default)
- Never use HTTP protocol (port 2375) on untrusted networks
- Use HTTPS protocol if HTTP mode required
- Pre-seed `~/.ssh/known_hosts` with verified host keys

**Docker Socket Access:**

- Access to `/var/run/docker.sock` is equivalent to root access
- Only run synapse-mcp with Docker socket access in trusted environments
- Consider using Docker socket proxy with access controls

### 2. Authentication & Authorization

**HTTP Mode:**

- Set `SYNAPSE_API_KEY` for built-in authentication
- Always deploy behind authenticated reverse proxy (nginx/Caddy) for internet exposure
- Use TLS certificates (Let's Encrypt)
- Enable HTTP Basic Auth minimum
- Restrict source IPs via firewall rules

**SSH Access:**

- Use key-based authentication only (no passwords)
- Ensure SSH keys have 600 permissions
- Store keys outside web-accessible directories
- Rotate SSH keys regularly

### 3. Environment Configuration

**Sensitive Variables:**

```bash
# ✅ SAFE SETTINGS:
SYNAPSE_CONFIG_FILE=/etc/synapse-mcp/config.json
SYNAPSE_PORT=53000
SYNAPSE_HOST=127.0.0.1  # Localhost only
SYNAPSE_API_KEY=replace-with-random-secret
SSH_POOL_MAX_CONNECTIONS=5
```

**Config File Security:**

```bash
# Restrict permissions
chmod 600 /etc/synapse-mcp/config.json
chown mcp:mcp /etc/synapse-mcp/config.json

# Never commit to git
echo "synapse.config.json" >> .gitignore
echo ".env" >> .gitignore
```

### 4. Network Security

**Firewall Rules:**

```bash
# Allow only SSH from synapse-mcp server to managed hosts
sudo ufw allow from 192.168.1.10 to any port 22

# Block Docker API ports externally
sudo ufw deny 2375/tcp
sudo ufw deny 2376/tcp
```

**Host Isolation:**

- Run synapse-mcp on dedicated management network
- Use VPN for remote access to management network
- Implement network segmentation between hosts

### 5. Monitoring & Auditing

**Log Monitoring:**

```bash
# Monitor for security events
journalctl -u synapse-mcp.service | grep -i "error\|denied\|failed"

# Watch for unauthorized access attempts
tail -f /var/log/nginx/access.log | grep "401\|403"

# Check for failed auth attempts in app logs
journalctl -u synapse-mcp.service | grep -i "Missing or invalid X-API-Key"
```

**Health Check Monitoring:**

```bash
# Monitor uptime and unauthorized access
curl -f http://localhost:53000/health || alert "MCP server down"

# Rate limit violations indicate potential abuse
grep "rate limit" /var/log/nginx/error.log
```

### 6. Principle of Least Privilege

**User Permissions:**

- Run synapse-mcp as non-root user
- SSH user on remote hosts should have minimal permissions
- Use Docker group membership instead of sudo
- Avoid running containers with `--privileged`

**Systemd Hardening:**

```ini
[Service]
User=mcp
Group=mcp

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/synapse-mcp/.cache

# Resource limits
MemoryMax=512M
CPUQuota=50%
```

---

## Security Checklist

### Deployment

- [ ] Server runs as non-root user
- [ ] Config file has 600 permissions
- [ ] SSH keys have 600 permissions
- [ ] `synapse.config.json` and `.env` in `.gitignore`
- [ ] TLS certificates installed and auto-renewing
- [ ] HTTP Basic Auth enabled (if using HTTP mode)
- [ ] Rate limiting configured
- [ ] Firewall rules restrict SSH access
- [ ] `~/.ssh/known_hosts` pre-seeded with verified host keys
- [ ] `SYNAPSE_API_KEY` configured when using HTTP mode
- [ ] Health endpoint accessible for monitoring
- [ ] Log rotation configured

### Operational

- [ ] Monitor logs for security events
- [ ] Review unauthorized access attempts weekly
- [ ] Rotate SSH keys every 90 days
- [ ] Update dependencies monthly (`pnpm update`)
- [ ] Review firewall rules quarterly
- [ ] Test backup restoration quarterly
- [ ] Audit user access permissions quarterly

### Incident Response

- [ ] Document security incident response plan
- [ ] Maintain contact list for security issues
- [ ] Test incident response procedures annually
- [ ] Keep offline backups of critical configs

---

## Dependency Security

### Current Known Vulnerabilities

**Fixed in v1.0.0:**

- `@modelcontextprotocol/sdk` upgraded to 1.26.0 (fixes GHSA-345p-7cg4-v4c7)

**Monitor:**

```bash
# Check for new vulnerabilities
pnpm audit

# Update dependencies
pnpm update

# Check specific package
pnpm outdated @modelcontextprotocol/sdk
```

### Supply Chain Security

- All dependencies locked in `pnpm-lock.yaml`
- No `postinstall` scripts in production dependencies
- Dependencies override in `package.json` for known CVEs
- Regular security audits with `pnpm audit`

---

## Historical Vulnerabilities

### CVE-INTERNAL-2025-001: Compose Command Injection

**Status:** Fixed in commit 43a2e54
**Affected:** Versions < 0.9.0
**Description:** Shell metacharacters in compose project names could lead to command injection
**Fix:** Added `validateAlphanumeric()` validation for project names

**Details:** See `docs/SECURITY.md` (project-internal doc)

---

## Resources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [CWE Database](https://cwe.mitre.org/)
- [SSH Best Practices](https://www.ssh.com/academy/ssh/best-practices)
- [Docker Security](https://docs.docker.com/engine/security/)
- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)

---

**Questions or Concerns?**
For security-related inquiries, use the private reporting methods described above. For general questions, open a GitHub issue.