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.

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: a short summary, a table of findings with locations and priorities, concrete remediation proposals, and an offer to provide the full evidence-level report.

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, the stable repository URL will be git+https://github.com/KacperStasieluk/sentinel.git@v0.2.0.

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. The current release tag is v0.2.0.