Polski

Sentinel

Sentinel is an AI agent for security-auditing other agents, skills, prompt bundles, plugins, hooks, and MCP servers. It runs inside Codex or Claude Code, so it uses the invoking user's signed-in account and model. It does not require an API key belonging to the project author.

Hybrid audit engine

Sentinel is not merely a bundle of prompt-only skills. Every audit combines contextual AI reasoning with a substantial deterministic security phase that runs automatically for the Sentinel agent:

• 25 catalogued, reproducible checks for prompt injection, credentials, command execution, permissions, network access, TLS, paths, persistence, supply-chain risks, deserialization, archives, and cross-file attack signals;
• bounded read-only inventory with per-file and whole-package SHA-256 hashes, explicit skipped-file limitations, secret redaction, and stable finding fingerprints;
• multilingual text indicators, including common instruction-override phrases in Hungarian, Polish, German, French, Spanish, Russian, Ukrainian, Chinese, and Japanese;
• Python AST checks for real eval/exec, shell APIs, shell=True, unsafe YAML, disabled certificate verification, archive extraction, secret sources, and network sinks;
• a second deterministic snapshot immediately before the verdict. If the package changed, stale conclusions are discarded and the review restarts once; another change produces INCONCLUSIVE.

These checks produce evidence, not an automatic verdict. The AI independently reviews relevant content in any language, tests whether flagged paths are actually reachable, correlates evidence across files, and dismisses justified false positives. A clean regex result never suppresses contextual review.

The agent includes nine focused skills:

• target-recon — inventories the target, entry points, declared capabilities, trust boundaries, external integrations, and files that could not be inspected. It establishes the audit scope before any verdict is made.
• prompt-injection — finds attempts to override instruction hierarchy, extract hidden prompts, promote untrusted content to instructions, or load remote and encoded instructions. It also evaluates whether the agent keeps data and commands separated.
• tool-safety — reviews tool definitions, permissions, confirmation gates, parameter validation, filesystem and network reach, destructive actions, and the consequences of hostile tool or MCP output.
• code-security — traces untrusted inputs to sensitive sinks and reviews command execution, dynamic evaluation, path traversal, unsafe deserialization, archive extraction, secret handling, TLS settings, and related implementation flaws.
• supply-chain — checks dependencies, version pinning, install and update hooks, downloaded executables, remote code, package integrity, and whether a compromised dependency could gain agent authority.
• agent-behavior — reasons about multi-step autonomy: scope control, approval boundaries, loops, retries, partial failures, persistence, self-modification, misleading success states, and recovery behavior.
• deterministic-testing — runs Sentinel's bounded read-only scanner, preserves hashes and redacted evidence, records coverage limitations, and treats machine findings as signals that still require contextual AI review.
• risk-correlation — connects evidence across prompts, code, manifests, and tools into credible attack paths; verifies controls, removes duplicates and false positives, and assigns a defensible verdict and priority.
• security-reporting — produces the final user-facing audit in the user's language using a table-first layout: verdict and coverage at a glance, followed by exactly what is wrong, where, its priority, what to change, and an offer to provide the full evidence-level report.

The default result is designed for quick decisions rather than raw scanner output:

A shared local MCP server gives the agent access to bounded deterministic security checks. The scanner never executes, imports, installs, or invokes the audited target.

Installation

Python 3.11 or newer is required.

pipx install sentinel-ai-auditor

Upgrade an existing PyPI installation:

pipx upgrade sentinel-ai-auditor

Install directly from a pushed repository branch on another computer:

pipx install "git+https://github.com/KacperStasieluk/sentinel.git@BRANCH_NAME"

Use pipx install --force when reinstalling the same branch. After the release tag is published, use its version tag in place of BRANCH_NAME.

Install the agent in Claude Code:

sentinel install claude
claude --agent sentinel

You can also ask Claude in a regular conversation:

Use the Sentinel agent to audit ./path/to/skill

Install the agent in Codex:

sentinel install codex

Then ask Codex:

Use the Sentinel agent to audit ./path/to/agent

Install both host adapters:

sentinel install all

The installer adds the native agent definition, the shared skills, and the local MCP server registration. It does not store any API key. --dry-run shows destination paths, --force replaces modified Sentinel-managed files, and --skip-mcp skips MCP registration.

Local tools

Run only the deterministic scanner, without an AI verdict:

sentinel scan ./target --json

List the bundled skills and deterministic checks:

sentinel skills
sentinel checks

Run the MCP server manually:

sentinel mcp

Deterministic signals are evidence for the agent, not a standalone security verdict. A PASS result is not a guarantee of safety.

Development and publishing

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check src tests
python -m ruff format --check src tests
python -m build
python -m twine check --strict dist/*

Publishing to PyPI uses GitHub Trusted Publishing after a version-matching tag is pushed.