diff --git a/README.md b/README.md index a959c5a..247135e 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,33 @@ -# sentinel +
-**MCP security scanner by Helixar** +# ๐Ÿ›ก๏ธ Sentinel MCP Scanner -sentinel scans Model Context Protocol (MCP) server configurations, live endpoints, and Docker containers for security misconfigurations. It surfaces findings with severity ratings, remediation guidance, and integrates into CI/CD pipelines via GitHub Actions. +**Security scanner for Model Context Protocol servers** -> **sentinel detects misconfigurations. For runtime protection, see [Helixar](https://helixar.ai).** +[![CI](https://github.com/Helixar-AI/sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/Helixar-AI/sentinel/actions/workflows/ci.yml) +[![GitHub Stars](https://img.shields.io/github/stars/Helixar-AI/sentinel?style=social)](https://github.com/Helixar-AI/sentinel/stargazers) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) +[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/helixar-sentinel) +[![PyPI](https://img.shields.io/pypi/v/helixar-sentinel?color=blue)](https://pypi.org/project/helixar-sentinel) +[![Marketplace](https://img.shields.io/badge/GitHub%20Action-Marketplace-2088FF?logo=github-actions&logoColor=white)](https://github.com/marketplace/actions/sentinel-mcp-security-scanner) + +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](https://helixar.ai).** + +
--- ## 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 +- ๐Ÿ” **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 --- @@ -26,7 +37,7 @@ sentinel scans Model Context Protocol (MCP) server configurations, live endpoint pip install helixar-sentinel ``` -Or install from source: +Or from source: ```bash git clone https://github.com/Helixar-AI/sentinel @@ -57,20 +68,7 @@ sentinel config mcp.json --format sarif --output sentinel.sarif.json --- -## 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 | - ---- - -## CI Integration - -### GitHub Actions +## GitHub Actions ```yaml - uses: Helixar-AI/sentinel@v1 @@ -87,85 +85,93 @@ sentinel config mcp.json --format sarif --output sentinel.sarif.json sarif_file: sentinel.sarif.json ``` -### Fail-on threshold +### Inputs -```bash -# Exit 1 if any HIGH or CRITICAL findings (default) -sentinel config mcp.json --fail-on high +| 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 | -# Stricter: exit 1 on MEDIUM+ -sentinel config mcp.json --fail-on medium +--- -# Lenient: exit 1 on CRITICAL only -sentinel config mcp.json --fail-on critical -``` +## 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) +### 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) +| 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 | +| 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) +### 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 | +| 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 | --- -## Adding a New Rule +## Fail-on Threshold -Rules are data, not code. Adding a rule takes three steps: - -**1. Add to `sentinel/rules/rules.yaml`:** -```yaml -- id: CFG-011 - module: config - severity: HIGH - check_key: no_egress_filter - title: No egress filtering configuration found - rationale: Without egress filtering, MCP tools can make arbitrary outbound connections. - remediation: Add an egress_filter block specifying allowed outbound destinations. - reference: net-003 +```bash +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 ``` -**2. Add detection logic in the appropriate module scanner.** +--- + +## Adding a New Rule + +Rules are data, not code โ€” adding one takes three steps: -**3. Add a test.** +**1.** Add to `sentinel/rules/rules.yaml` +**2.** Add a `_check_` method in the relevant module scanner +**3.** Add tests See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. @@ -174,22 +180,19 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow. ## Running Tests ```bash -# All unit tests python -m pytest tests/unit/ -v - -# With coverage -python -m pytest tests/unit/ --cov=sentinel --cov-report=html +python -m pytest tests/ --cov=sentinel --cov-report=html ``` --- -## Roadmap (v0.2.0) +## Roadmap -- `sentinel watch` โ€” continuous monitoring mode -- Kubernetes manifest scanning -- Additional probe checks: JWT algorithm confusion, replay attacks -- `--diff` flag: compare scan results across runs -- Integration test suite +- [ ] `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 --- @@ -199,4 +202,10 @@ MIT โ€” see [LICENSE](LICENSE) --- -*sentinel by [Helixar Security Research](https://helixar.ai) ยท Runtime protection: [helixar.ai](https://helixar.ai)* +
+ +Built by [Helixar Security Research](https://helixar.ai) • Runtime protection: [helixar.ai](https://helixar.ai) + +โญ **Star this repo** if sentinel is useful to you โ€” it helps others find it. + +
diff --git a/pyproject.toml b/pyproject.toml index c3cccca..4a8a7ce 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta" [project] name = "helixar-sentinel" version = "0.1.0" -description = "MCP security scanner by Helixar" +description = "Sentinel MCP Scanner โ€” security scanner for Model Context Protocol servers" readme = "README.md" license = { file = "LICENSE" } authors = [{ name = "Helixar Security Research", email = "security@helixar.ai" }]