Skip to content

docs: rebrand to Sentinel MCP Scanner + fancy README #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
asiridalugoda merged 1 commit into from
Mar 9, 2026
Merged

docs: rebrand to Sentinel MCP Scanner + fancy README #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 100 additions & 91 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,33 @@
# sentinel
<div align="center">

**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).**

</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
- 🔍 **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

---

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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_<key>` method in the relevant module scanner
**3.** Add tests

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.

Expand All @@ -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

---

Expand All @@ -199,4 +202,10 @@ MIT — see [LICENSE](LICENSE)

---

*sentinel by [Helixar Security Research](https://helixar.ai) · Runtime protection: [helixar.ai](https://helixar.ai)*
<div align="center">

Built by [Helixar Security Research](https://helixar.ai) &bull; Runtime protection: [helixar.ai](https://helixar.ai)

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

</div>
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }]
Expand Down