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

Use portunusmcp-sentinel==1.2.1 for exact reproducibility.

Quickstart

From a local Python or TypeScript MCP server repository:

sentinel init
# Review the generated sentinel.permissions.yaml and grant only required scopes.
sentinel scan . --static-only --allow-degraded

sentinel init inspects source without importing or executing it. Generated permissions deny access until reviewed, and existing configuration is preserved unless --force is supplied. The scan above needs neither an OpenAI API key nor Docker and keeps deterministic candidates visible for review.

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

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.

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.4.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.2.1
    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.