<div align="center">

🛡️ Sentinel MCP Scanner

Security scanner for Model Context Protocol servers

Sentinel scans MCP server configurations, live endpoints, and Docker containers for security misconfigurations — surfacing findings with severity ratings, remediation guidance, and CI/CD integration.

Sentinel detects misconfigurations. For 360° enterprise runtime protection, see Helixar.

</div>

---

Features

• 🔍 Config scanner — static analysis of MCP server config files (10 checks)
• 🌐 Probe scanner — live endpoint security analysis (8 checks)
• 🐳 Container scanner — Docker container/image inspection (8 checks)
• 📋 26 detection rules across all modules
• 🎨 4 output formats — terminal (Rich), HTML, JSON, SARIF 2.1
• ⚙️ GitHub Action — drop-in CI integration with SARIF upload support
• 🚦 Fail-on threshold — block PRs on HIGH/CRITICAL findings

---

Installation

pip install helixar-sentinel

Or from source:

git clone https://github.com/Helixar-AI/sentinel
cd sentinel
pip install -e ".[dev]"

---

Quick Start

# Scan a config file
sentinel config mcp.json

# Probe a live endpoint
sentinel probe https://your-mcp-server.example.com

# Inspect a Docker container
sentinel container my-mcp-image:latest

# Run all scanners in one pass
sentinel scan --config mcp.json --endpoint https://mcp.example.com --container my-image:latest

# Output as SARIF for GitHub Code Scanning
sentinel config mcp.json --format sarif --output sentinel.sarif.json

---

GitHub Actions

- uses: Helixar-AI/sentinel@v1
  with:
    config: ./mcp.json
    endpoint: ${{ secrets.MCP_ENDPOINT }}
    container: my-mcp-image:latest
    fail-on: high
    format: sarif
    output: sentinel.sarif.json

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sentinel.sarif.json

Inputs

| Input | Required | Default | Description | |-------|----------|---------|-------------| | config | No | — | Path to MCP server config file | | endpoint | No | — | Live MCP endpoint URL to probe | | container | No | — | Docker container name or image | | fail-on | No | high | Minimum severity to fail the build | | format | No | sarif | Output format (terminal/json/sarif/html) | | output | No | sentinel.sarif.json | Report output path |

---

Output Formats

| Format | Flag | Use case | |--------|------|----------| | Terminal | --format terminal (default) | Local development | | JSON | --format json | Custom tooling | | SARIF | --format sarif | GitHub Code Scanning | | HTML | --format html | Stakeholder reports |

---

Detection Rules

Config module — 10 rules

| ID | Severity | Check | |----|----------|-------| | CFG-001 | 🔴 CRITICAL | No authentication configured | | CFG-002 | 🔴 CRITICAL | Plaintext secrets in config | | CFG-003 | 🟠 HIGH | Wildcard tool permissions | | CFG-004 | 🟠 HIGH | No rate limiting | | CFG-005 | 🟡 MEDIUM | Debug mode enabled | | CFG-006 | 🟠 HIGH | No TLS configuration | | CFG-007 | 🟠 HIGH | Wildcard CORS origin | | CFG-008 | 🟡 MEDIUM | No input validation | | CFG-009 | 🟡 MEDIUM | Sensitive data logging | | CFG-010 | 🔵 LOW | No request timeout |

Probe module — 8 rules

| ID | Severity | Check | |----|----------|-------| | PRB-001 | 🔴 CRITICAL | TLS certificate invalid/expired | | PRB-002 | 🟠 HIGH | Weak TLS version (< TLS 1.2) | | PRB-003 | 🔴 CRITICAL | No authentication required | | PRB-004 | 🟡 MEDIUM | Server version disclosed in headers | | PRB-005 | 🟡 MEDIUM | Missing security headers | | PRB-006 | 🟠 HIGH | Tool listing publicly exposed | | PRB-007 | 🔵 LOW | Verbose error messages | | PRB-008 | 🟠 HIGH | No rate limiting detected |

Container module — 8 rules

| ID | Severity | Check | |----|----------|-------| | CTR-001 | 🟠 HIGH | Container running as root | | CTR-002 | 🔴 CRITICAL | Privileged container mode | | CTR-003 | 🟡 MEDIUM | No CPU/memory resource limits | | CTR-004 | 🟠 HIGH | Sensitive env vars exposed | | CTR-005 | 🟡 MEDIUM | Writable root filesystem | | CTR-006 | 🔵 LOW | No health check configured | | CTR-007 | 🟡 MEDIUM | Outdated base image | | CTR-008 | 🟠 HIGH | Dangerous ports exposed |

---

Fail-on Threshold

sentinel config mcp.json --fail-on critical   # exit 1 on CRITICAL only
sentinel config mcp.json --fail-on high        # exit 1 on HIGH+ (default)
sentinel config mcp.json --fail-on medium      # exit 1 on MEDIUM+
sentinel config mcp.json --fail-on low         # exit 1 on any finding

---

Adding a New Rule

Rules are data, not code — adding one takes three steps:

1. Add to sentinel/rules/rules.yaml 2. Add a _check_<key> method in the relevant module scanner 3. Add tests

See CONTRIBUTING.md for the full workflow.

---

Running Tests

python -m pytest tests/unit/ -v
python -m pytest tests/ --cov=sentinel --cov-report=html

---

Roadmap

• [ ] sentinel watch — continuous monitoring mode
• [ ] Kubernetes manifest scanning
• [ ] JWT algorithm confusion + replay attack probe checks
• [ ] --diff flag for regression detection across runs
• [ ] Additional output: JUnit XML for legacy CI systems

---

License

Apache-2.0 — see LICENSE and NOTICE.

---

<div align="center">

Built by Helixar Security Research • Runtime protection: helixar.ai

⭐ Star this repo if sentinel is useful to you — it helps others find it.

</div>