◇ sentinel
Documentation

How Sentinel works.

The playground, CLI, MCP server, and agent skill all share one engine. This page covers every surface: what each one does, how to configure it, and how to read a verdict.

Overview

Sentinel is a universal security verification framework for AI agent installations. It sits between an agent (or a human) and any installer: nothing installs until the target has been acquired (download-only, never executed), analyzed, risk-scored, policy-checked, and explicitly approved.

The pipeline is always the same:

pipeline
Acquire  ->  Analyze  ->  Score  ->  Policy  ->  Approve  ->  Install

This website is the playground: a sandboxed browser UI that exposes verify for npm and github only. The full package also ships a CLI for your terminal, an MCP server for AI agents, and an agent skill that intercepts install requests and routes them through MCP.

Playground

Type a command into the console on the playground. A leading sentinel is tolerated, so sentinel verify npm lodash works too.

verify npm <package>
verify npm lodashA version is optional: lodash@4.17.21
verify github <owner/repo>
verify github expressjs/expressPublic repositories only
help
helpList every command
clear
clearClear the console output

The playground is verify-only. It cannot install packages or scan your local filesystem. See the security model below.

Reading the report

Every verification renders the same structure. The banner leads with the decision; color always encodes risk.

Decision

The policy engine resolves the findings into one verdict:

AUTO_APPROVE / APPROVENo policy violations. Safe to proceed.
WARNMinor signals worth a glance before installing.
REQUIRE_APPROVALNotable risk. A human should review the findings.
BLOCKStrong indicators of malicious or unsafe code.

Risk & confidence

risk is a level plus a 0-100 score. confidence reflects how much data the engine had to work with. signals counts positive and negative indicators (for example, a long publish history versus a non-HTTPS source).

Finding severities

Each finding carries a severity. A test tag marks findings located in test files, which usually matter less.

CRITICALDirect evidence of harmful behavior.
HIGHDangerous pattern that usually warrants action.
MEDIUMSuspicious, but context-dependent.
LOWMinor hygiene or informational signal.
INFONeutral metadata, including positive signals.

Verification flow

What happens between pressing enter and seeing a verdict:

  1. 01
    Parse

    The command is validated client-side, then the target is sent to /api/verify.

  2. 02
    Guard

    The route enforces the npm/github allowlist, input regex, a per-IP rate limit, and a 25s timeout.

  3. 03
    Download

    The engine fetches the npm tarball or GitHub repo archive into an ephemeral temp directory.

  4. 04
    Analyze

    Static analyzers inspect metadata, source, scripts, network calls, secrets, and permissions. Nothing runs.

  5. 05
    Report

    A JSON verdict is returned and rendered, then the temp files are discarded.

Security model

The serverless function imports a single entry point: verify(). Capabilities that touch your shell, filesystem, or untrusted archives are never wired in. What you can reach is the whole attack surface.

verify · npm / githubDownload, then static analysis onlyreachable
installWould spawn npm / gitnever imported
local · skill · scan_directoryWould read the server filesystemexcluded
scan_archiveZip-bomb surfaceexcluded

npm package

Everything ships in one package: @rexymayderio/sentinel. Installing it gives you both binaries, the programmatic engine, and the agent skill files under skills/sentinel/. Requires Node.js 20 or later.

install
$ npm install -g @rexymayderio/sentinel

Two entry points, one shared engine:

sentinel
Command-line verifier and installernpx -y -p @rexymayderio/sentinel sentinel verify npm express
sentinel-mcp
MCP server over stdio for AI agentsnpx -y -p @rexymayderio/sentinel sentinel-mcp

Supported targets

The CLI and MCP support more ecosystems than the playground. Unimplemented targets fail acquisition and typically escalate to REQUIRE_APPROVAL for manual review.

npmRegistry metadata + tarball extraction
githubRepo metadata + tarball download
skillLocal AI skill folder / SKILL.md
localAny local directory
pip, uv, cargo, go, docker, vscode, mcp, git, zipAcquisition may fail and escalate to REQUIRE_APPROVAL

Set GITHUB_TOKEN in your environment to lift GitHub's unauthenticated rate limit on the github path.

CLI

The sentinel binary is the manual verification path. Use verify to analyze without installing, or install to verify first and then install behind an approval gate. Install scripts are never executed during analysis.

sentinel verify npm <package>
Download and analyze an npm package. Never installs.
sentinel verify github <owner/repo>
Download and analyze a public GitHub repo.
sentinel verify skill <path>
Analyze a local AI skill folder or SKILL.md.
sentinel verify local <path>
Scan any local directory.
sentinel install npm <package>
Verify first, then install behind an approval gate.
sentinel install skill <path> --yes
Auto-approve non-BLOCK decisions. BLOCK cannot be overridden.
sentinel verify npm express --json
Output formats: terminal (default), json, markdown.
sentinel verify npm express --policy ./policy.json
Override block/warn thresholds and trusted publishers.
sentinel verify local ./app --score-tests
Scan test/fixture files with the full production ruleset.

Policy configuration

Pass --policy ./policy.json to override thresholds and publisher lists. Key fields include blockThreshold (default 80), warnThreshold (default 50), trustedPublishers, corporateWhitelist, and corporateBlacklist.

policy.json example
{  "blockThreshold": 70,  "minConfidence": 50,  "trustedPublishers": ["@myorg/"],  "corporateBlacklist": ["leftpad-evil"]}

MCP server

sentinel-mcp exposes Sentinel as an MCP server over stdio. AI agents call its tools to verify targets, read risk reports, and install only after explicit approval. The playground uses the same engine programmatically via verify().

run the server
$ npx -y -p @rexymayderio/sentinel sentinel-mcp

The -p @rexymayderio/sentinel flag is required. It tells npx to run the sentinel-mcp binary from the package, not the CLI with a stray argument.

cursor / claude desktop config
{  "mcpServers": {    "sentinel": {      "command": "npx",      "args": ["-y", "-p", "@rexymayderio/sentinel", "sentinel-mcp"]    }  }}

Available tools

verify_packageVerify an npm package. Returns a full JSON report.
verify_repositoryVerify a GitHub repository.
verify_skillVerify a local AI skill directory.
verify_mcpVerify an MCP server (acquisition not yet implemented).
verify_extensionVerify a VSCode extension (not yet implemented).
verify_dockerVerify a Docker image (not yet implemented).
scan_directoryScan a local directory (ecosystem: local).
scan_archiveScan a zip archive (not yet implemented).
calculate_riskQuick score summary: score, level, confidence, decision.
generate_reportFull verification with terminal, json, or markdown output.
approve_installCheck whether a target is approvable without installing.
installVerify and install. confirm must be true. BLOCK cannot be overridden.

install requires confirm: true. A BLOCK decision cannot be overridden, even with confirm set.

Agent skill

The Sentinel agent skill teaches your AI assistant to intercept install requests, verify through the MCP server above, explain risks in plain language, and only install after approval. The skill never performs analysis itself; it routes to MCP tools and interprets the JSON report.

Install the skill

Copy or symlink skills/sentinel/SKILL.md from the package into your agent's skills directory:

cursor
$ mkdir -p ~/.cursor/skills/sentinel$ cp node_modules/@rexymayderio/sentinel/skills/sentinel/SKILL.md ~/.cursor/skills/sentinel/

The MCP server must be configured first (see above). Without it, the skill has nothing to call.

What it does

  • Automatic interception: when you say "install express" or "install this GitHub repo", the skill verifies first instead of running the installer directly.
  • Manual commands: slash commands like /verify-package and /compare for on-demand analysis.
  • Never overrides BLOCK: if policy.decision is BLOCK, installation is refused regardless of user pressure.
  • Explain mode: every result includes an executive summary, technical breakdown, grouped findings, and a clear recommendation mapped from recommendedAction.

Manual commands

/verify-package express
verify_package({ name: "express" })
/verify-repository owner/repo
verify_repository({ owner, repo })
/verify-skill ./skills/my-skill
verify_skill({ path })
/verify-folder ./my-project
scan_directory({ path })
/verify-report npm express markdown
generate_report({ type, target, format })
/compare express hono fastify
verify_package for each, then synthesize

Every /verify-* command is read-only. Only the MCP install tool can install, and only after verification and explicit user approval.

Limits

Playground

  • Only npm and github targets are accepted; anything else returns a 400.
  • Verification aborts after 25 seconds so large targets fail gracefully.
  • A best-effort per-IP rate limit applies. If you hit it, wait a moment and retry.
  • Results are not stored. Each run is downloaded, analyzed, and discarded.

CLI / MCP

  • BLOCK decisions cannot be overridden by --yes or MCP confirm: true.
  • Unimplemented ecosystems (pip, docker, mcp, zip, etc.) may return REQUIRE_APPROVAL with insufficient-data reasons.
  • Test/fixture files use a narrower ruleset by default. Pass --score-tests to apply the full production ruleset.