# 🛡️ AgentSentinel MCP Gateway

> **Industrial-Grade Zero-Trust MCP Gateway, DLP Secret Firewall & Circuit Breaker for Autonomous AI Agents**

[![CI](https://github.com/opuhassan001-alt/agent-sentinel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/opuhassan001-alt/agent-sentinel-mcp/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Compliant-blue.svg)](https://modelcontextprotocol.io)

**AgentSentinel** is an enterprise-grade execution firewall and reliability gateway sitting between AI Agent clients (**Claude Desktop, Claude Code, Cursor, Antigravity, OpenCode, AutoGen, CrewAI**) and host capabilities. It solves the three most critical operational barriers facing autonomous agents in production.

---

## 🎯 The Three Core Pillars

```
                     [ Autonomous AI Agent / LLM Client ]
                    (Claude, Cursor, Antigravity, OpenCode)
                                       │
                                       │  JSON-RPC 2.0 (stdio)
                                       ▼
  ┌────────────────────────────────────────────────────────────────────────┐
  │                        AGENTSENTINEL GATEWAY                           │
  │                                                                        │
  │  1. ⚡ RELIABILITY & CIRCUIT BREAKER                                   │
  │     - Sliding-window rate limiter (60 RPM)                             │
  │     - Runaway failure detector (trips OPEN on 3 consecutive failures)  │
  │                                                                        │
  │  2. 🔒 ZERO-TRUST PRE-EXECUTION FIREWALL                               │
  │     - AST Command Sanitizer (blocks chaining ";", "&&", `subshell`)   │
  │     - Chroot Path Guard (rejects "../../" directory traversal)        │
  │     - SSRF Guard (blocks 169.254.169.254 metadata & private subnets)   │
  │                                                                        │
  │  3. 🔍 DATA LOSS PREVENTION (DLP) SECRET MASKING                       │
  │     - Scans inputs and outputs for 25+ secret patterns                 │
  │     - Redacts AWS, GitHub, OpenAI, Claude, JWT, DB URIs before LLM    │
  │                                                                        │
  │  4. 📜 STRUCTURED AUDIT LEDGER                                         │
  │     - Append-only JSONL log with duration, verdict & hash              │
  └────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
                         [ Sandboxed Host Execution ]
```

### 1. 🔒 Zero-Trust Pre-Execution Gateway & DLP Engine
* **Command Injection Defense**: Intercepts shell execution before it reaches the OS. Blocks command chaining (`;`, `&&`, `||`, `|`), subshell execution (`` `...` ``, `$(...)`), and denylisted destructive binaries (`rm`, `del`, `format`, `dd`, `mkfs`, `curl | sh`).
* **Path Traversal Containment**: Canonical path resolution strictly chroots execution within the approved workspace root directory.
* **SSRF Link-Local Protection**: Blocks outbound calls to cloud metadata IP (`169.254.169.254`), loopbacks (`127.0.0.1`, `localhost`, `::1`), and private RFC-1918 subnets (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`).
* **Automated DLP Redaction**: Pre-flight and post-execution token scanner with zero-trust redaction for:
  - AWS Access Keys (`AKIA...`)
  - GitHub Personal Access Tokens (`ghp_...`, `github_pat_...`)
  - Anthropic & OpenAI API Keys (`sk-ant-...`, `sk-proj-...`)
  - RSA & OpenSSH Private Keys (`-----BEGIN RSA PRIVATE KEY-----`)
  - JWT Tokens (`eyJ...`)
  - Database URI passwords (`postgres://user:password@host...`)
  - Slack Tokens & Stripe Secret Keys

### 2. ⚡ Circuit Breakers & Runaway Loop Prevention
* **Runaway Loop Breaker**: When an autonomous agent enters a broken loop (e.g., retrying an erroneous query repeatedly), the circuit breaker transitions from `CLOSED` to `OPEN` after $N$ consecutive failures.
* **Token Spend Protection**: Rejects all further tool invocations during cooldown, preventing catastrophic API token spend and CPU exhaustion.
* **Sliding-Window Rate Limiter**: Enforces strict requests-per-minute (RPM) limits per session to throttle runaway concurrency.
* **Self-Healing Recovery**: Automatically transitions to `HALF-OPEN` after cooldown, allowing probe attempts to restore normal operation.

### 3. 🚀 Local-First, Zero-Heavy-Infra Architecture
* **Zero Kubernetes or Heavy Cloud Setup**: Runs as a lightweight, single-process Node.js daemon directly on your workstation or server.
* **Native MCP Protocol Compliant**: Integrates instantly into **Claude Desktop**, **Claude Code**, **Cursor**, or custom AI agent loops over standard STDIO JSON-RPC 2.0.
* **Deterministic Structured Audit Ledger**: Writes an append-only JSONL audit log capturing caller session, duration, tool name, security verdict, and DLP metrics without external observability dependencies.

---

## 🛠️ Provided MCP Tools

| Tool Name | Description | Security Controls Applied |
| :--- | :--- | :--- |
| `sentinel_safe_exec` | Executes shell commands safely. | Allowlist, AST chaining block, timeout, DLP output redaction. |
| `sentinel_safe_fs` | Sandboxed file ops (`read`, `write`, `list`, `stat`). | Path chroot containment, traversal block, secret masking. |
| `sentinel_safe_fetch` | Secure HTTP client (`GET`, `POST`, etc.). | SSRF metadata blocker, header & body DLP redaction. |
| `sentinel_policy_check` | Pre-flight permission validator. | Lets agents query policy verdicts before attempting actions. |
| `sentinel_audit_inspect` | Query audit trail and circuit telemetry. | Read-only inspection of runtime logs and breaker state. |

---

## 🚀 Quickstart & Installation

### Option A: Use directly with npx or node
```bash
# Clone the repository
git clone https://github.com/opuhassan001-alt/agent-sentinel-mcp.git
cd agent-sentinel-mcp

# Install dependencies and build
npm install
npm run build

# Run the test suite (100% pass)
npm test
```

### Option B: Configure with Claude Desktop (`claude_desktop_config.json`)
Add AgentSentinel to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "agent-sentinel": {
      "command": "node",
      "args": [
        "E:/work station/opu-portfolio/agent-sentinel-mcp/dist/index.js"
      ],
      "env": {
        "SENTINEL_ROOT_DIR": "E:/work station/opu-portfolio",
        "SENTINEL_MAX_FAILURES": "3",
        "SENTINEL_RATE_LIMIT_RPM": "60"
      }
    }
  }
}
```

### Option C: Configure with Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "agent-sentinel": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}
```

---

## ⚙️ Configuration Reference

AgentSentinel can be configured via environment variables or a configuration object:

| Environment Variable | Default | Description |
| :--- | :--- | :--- |
| `SENTINEL_ROOT_DIR` | `process.cwd()` | Root boundary for filesystem operations and working directories. |
| `SENTINEL_AUDIT_LOG_PATH` | `.sentinel-audit.jsonl` | Filepath for append-only structured audit records. |
| `SENTINEL_MAX_FAILURES` | `3` | Number of consecutive tool errors before circuit trips OPEN. |
| `SENTINEL_COOLDOWN_MS` | `30000` | Cooldown duration in milliseconds before half-open retry. |
| `SENTINEL_RATE_LIMIT_RPM` | `60` | Maximum tool invocations allowed per minute. |

---

## 🧪 Testing & Verification

AgentSentinel includes an automated unit & integration test suite using the Node.js native test runner:

```bash
npm test
```

```text
▶ CircuitBreaker & Runaway Loop Protection (6 tests)
▶ DLP Secret Scanner & Redaction Engine (7 tests)
▶ PolicyEngine & AuditLogger (5 tests)
▶ Security Firewall Guards (12 tests)
▶ Industrial MCP Tools Suite (11 tests)
✔ All 41 tests passed cleanly
```

---

## 🐳 Docker Deployment

Run AgentSentinel inside a sandboxed container:

```bash
docker build -t agent-sentinel-mcp .
docker run -i --rm -v $(pwd):/workspace -e SENTINEL_ROOT_DIR=/workspace agent-sentinel-mcp
```

---

## 📄 License
Released under the [MIT License](LICENSE). Copyright © 2026 Estakball Hossain (Opu).