PortunusMCP Sentinel

Build-time security scanning for MCP servers.

PortunusMCP Sentinel scans local MCP server source before deployment. It combines deterministic Python and TypeScript analysis, GPT-5.6 semantic review, optional Docker-isolated runtime probes, OWASP Agentic Top 10 mappings, and validated SARIF output for GitHub code scanning.

Install

Sentinel supports Python 3.10–3.13 on Linux, macOS, and Windows. Install the current package with pipx:

pipx install portunusmcp-sentinel

Or use uv:

uv tool install portunusmcp-sentinel

Rules-only commands below require 1.3.0 or newer. Upgrade an existing install with pipx upgrade portunusmcp-sentinel or uv tool upgrade portunusmcp-sentinel.

Quickstart

From a local Python or TypeScript MCP server repository:

sentinel scan . --rules-only

Rules-only needs no model credentials, review cache, network, Docker, target configuration, or target execution. It ignores inactive LLM settings even when credentials and endpoint overrides are present. Installation and dependency auditing need network access separately.

Optionally run sentinel init afterward to generate a deny-by-default sentinel.permissions.yaml; review scopes before granting them. It never imports or executes source and needs no main guard or launch inference. Existing files require --force for replacement; symlinks are rejected.

For Python runtime scaffolding, run sentinel init --dynamic, then sentinel scan . --no-rules-only. Adding missing runtime configuration preserves and validates an existing permissions file. Dynamic scans require Docker, model credentials, source-context transmission, and model cost; dependency installation also needs network access. TypeScript does not support --dynamic.

Exit 0 and exit 1 both mean the scan completed: 0 means no finding reached the configured threshold, while 1 means at least one did. Exit 2 is a target or configuration error; exit 3 means analysis was incomplete.

Analysis tiers

--allow-degraded permits unavailable review; it still calls the model when a key is available. Use --rules-only to disable review explicitly. Completion describes the selected analysis tier and does not prove a server is secure.

TypeScript support is static-only and covers .ts, .mts, and .cts sources using the official MCP SDK v1 and server v2 shapes. JavaScript, TSX, declaration files, workspaces, cross-file dataflow, imported handlers or schemas, and Node execution are outside the supported boundary. Dynamic targets are local Python 3.10–3.12 MCP servers.

Version 1.3.0 includes Phase 16 static-correctness changes: same-file named-helper execution flows and value-specific validation, authentication, integrity, and configured-sanitizer checks. Unsupported flows remain unresolved; see the rule boundaries and verification record.

Phase 17 source changes add validated dynamic baselines, explicit probe outcomes, and proof-preserving review in native JSON 1.5.0. The current replay bundle uses one approved runtime-review refresh and four unchanged static captures. See the Phase 17 verification record for gates and acceptance status.

Rules

Every finding uses a stable rule ID and maps to the OWASP Agentic Top 10.

Published IDs are compatibility contracts: an ID is never renumbered or reused for a different detection. The rule catalog documents each engine, boundary, false-positive risk, evidence, and remediation.

GitHub Action

The Marketplace Action runs the full Python pipeline, validates SARIF before upload, and preserves Sentinel's exit contract.

name: PortunusMCP Sentinel

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  sentinel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - id: sentinel
        uses: BashaarJavaid/MCP-Sentinel@v1
        with:
          target-path: .
          fail-on: high
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}

The Action exposes sarif-path, findings-count, and highest-severity. Forked pull requests, where secrets are withheld, run visibly degraded analysis and skip upload. High-assurance consumers can replace @v1 with the immutable commit SHA for the selected release.

Architecture

flowchart LR
    A[Untrusted MCP repository] --> B[AST + Semgrep rules]
    B --> C[Canonical candidates]
    C --> D[GPT-5.6 semantic review]
    D --> E[Constrained four-probe plan]
    E --> F[Docker sandbox]
    F --> G[Reviewed dynamic evidence]
    D --> H[Deduplication + provenance merge]
    G --> H
    H --> I[Console]
    H --> J[JSON 1.5.0]
    H --> K[SARIF 2.1.0]
    K --> L[GitHub code scanning]

Static analysis never imports or executes target code. GPT receives bounded, redacted context and can only review existing candidates or order four permanent inert probes. Dynamic analysis mounts local Python source read-only in fresh containers with no runtime network, resource limits, and forced cleanup. All stages feed one canonical Finding model consumed by console, JSON, and SARIF.

PortunusMCP Sentinel is the build-time plane of the PortunusMCP family. The PortunusMCP Gateway provides runtime enforcement in a separate repository, while PortunusMCP Identity is the separate short-lived credential-broker plane. Neither is required by Sentinel.

Configuration and adoption

Configuration precedence is CLI → SENTINEL_* environment → target-root sentinel.toml → built-in defaults. A normal full scan also requires sentinel.target.yaml and sentinel.permissions.yaml; --static-only does not require launch configuration.

Create a baseline from a complete native JSON report, then compare later scans:

sentinel scan . --allow-degraded --format json --output sentinel-baseline.json
sentinel scan . --allow-degraded --baseline sentinel-baseline.json

Matched findings remain visible but do not affect --fail-on. Sentinel never updates a baseline automatically.

Suppress a reviewed static source finding with a reason-bearing directive:

# sentinel: ignore[SENT-005] reason=test credential is inert and rotated
api_key = "ghp_example"

Only static SENT-001–SENT-007 findings can be suppressed. Applied suppressions remain visible in every report; malformed, duplicate, unknown-rule, or reasonless directives fail configuration validation.

Use Sentinel from pre-commit:

repos:
  - repo: https://github.com/BashaarJavaid/MCP-Sentinel
    rev: v1.3.0
    hooks:
      - id: mcp-sentinel

See the configuration guide for LLM endpoint trust, rule selection, baselines, suppressions, and pre-commit.

CLI and report reference

# Full static, GPT, and Docker analysis
sentinel scan ./path/to/server

# Static analysis with required GPT review
sentinel scan ./path/to/server --static-only

# Validated SARIF
sentinel scan ./path/to/server --format sarif --output results.sarif

# Select rules and change the failure threshold
sentinel scan ./path/to/server --rules SENT-001,SENT-005 --fail-on critical

# Exercise the packaged reference pipeline
sentinel demo --replay-review --verbose

--fail-on accepts critical, high, medium, low, or informational. Console output is the default; --format json and --format sarif are stable machine-readable paths. Validate reports offline with:

python -m sentinel.schema check
python -m sentinel.report.validate_sarif results.sarif

The production reviewer uses GPT-5.6 Sol through the Responses API with store: false, medium reasoning effort, strict Structured Outputs, bounded context, and host-validated evidence. Sentinel's public OpenAI cost calculation uses the rates recorded on 2026-09-04: $4/M input, $0.40/M cached input, and $20/M output, with cache writes at 1.25× input. See the official GPT-5.6 Sol model and pricing page and Responses API create reference. Compatible endpoints retain token usage but report pricing as unavailable.

Project resources

• Scan a real MCP server before release
• Marketplace Action
• Documentation
• Architecture contract
• Roadmap
• Contributing
• SARIF guide
• Changelog
• Security policy
• Project history

PortunusMCP Sentinel is MIT licensed. Dependency licenses and packaged notices are recorded in THIRD_PARTY_NOTICES.md.