# SentinelMCP

[![CI](https://github.com/ateeqdesktop-dot/sentinel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ateeqdesktop-dot/sentinel-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

**Deterministic Policy Firewall & Runtime Governance Engine for Model Context Protocol (MCP)**

---

## Overview

**SentinelMCP** is a production-grade security gateway and runtime governance framework designed specifically for **Model Context Protocol (MCP)** servers and multi-agent AI swarms [1]. As AI agents increasingly gain autonomous access to enterprise filesystems, databases, and APIs via MCP, security risks such as prompt injections, unauthorized tool invocations, and data exfiltration have surged. 

SentinelMCP acts as an inline policy firewall, intercepting JSON-RPC MCP tool calls, inspecting arguments against declarative AST-based rules, enforcing security limits, and recording an immutable, cryptographically verifiable audit trail.

---

## Key Architecture & Features

- **Policy-as-Code Engine**: Declarative JSON/YAML policy definitions supporting glob pattern matching on tool names, regex inspections on argument values, and strict argument schema validation [2].
- **Cryptographic Provenance Ledger**: Append-only audit logging where each execution record is chained with SHA-256 hashes, ensuring tamper-proof traceability for compliance and auditing.
- **High-Performance Proxy Gateway**: Built on FastAPI and Pydantic v2, delivering sub-millisecond interception latency with async request handling.
- **CLI & Testing Toolchain**: Built-in CLI for evaluating tool calls against policies, running the gateway server, and verifying ledger integrity.
- **Enterprise-Grade CI/CD**: Fully tested with pytest, matrix tested across Python 3.11 and 3.12, and integrated with GitHub Actions workflows.

---

## Installation

Clone the repository and install in editable mode with development dependencies:

```bash
git clone https://github.com/ateeqdesktop-dot/sentinel-mcp.git
cd sentinel-mcp
pip install -e .[dev]
```

---

## Usage

### 1. Evaluating a Tool Call via CLI

You can test how SentinelMCP evaluates any MCP tool call against your security policies:

```bash
sentinel-mcp evaluate --tool fs_delete --args '{"path": "/home/user/document.txt"}' --policy policy.json
```

### 2. Running the Gateway Server

Start the SentinelMCP proxy server locally:

```bash
sentinel-mcp serve --host 127.0.0.1 --port 8000 --policy policy.json
```

### 3. Verifying Audit Ledger Integrity

Verify that the append-only audit trail has not been tampered with:

```bash
sentinel-mcp verify --ledger sentinel_audit.jsonl
```

---

## Policy Configuration Example (`policy.json`)

```json
{
  "version": "1.0",
  "default_action": "allow",
  "rules": [
    {
      "id": "block-destructive-fs",
      "tool_pattern": "fs_*",
      "action": "deny",
      "forbidden_arguments": [
        "rm\\s+-rf",
        "/etc/passwd",
        "drop\\s+database"
      ]
    },
    {
      "id": "limit-sql-queries",
      "tool_pattern": "db_*",
      "action": "allow",
      "max_string_length": 500
    }
  ]
}
```

---

## Testing

Run the test suite with pytest and code coverage:

```bash
pytest --cov=sentinel tests/ -v
```

---

## License

Distributed under the MIT License. See `LICENSE` for more information.

---

## References

1. Anthropic Model Context Protocol (MCP) Specification. [Online Available](https://modelcontextprotocol.io/).
2. Open Policy Agent (OPA) Principles for Cloud-Native Security. [Online Available](https://www.openpolicyagent.org/).