Metadata-Version: 2.4
Name: sentinel-ai-auditor
Version: 0.2.2
Summary: AI security audit agent for Codex, Claude Code, and MCP-compatible hosts
Author: Kacper Stasiełuk
License-Expression: MIT
Project-URL: Homepage, https://github.com/KacperStasieluk/sentinel
Project-URL: Issues, https://github.com/KacperStasieluk/sentinel/issues
Project-URL: Security, https://github.com/KacperStasieluk/sentinel/security/policy
Keywords: agent-security,ai-agents,claude-code,codex,mcp,prompt-injection
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=1.12
Provides-Extra: dev
Requires-Dist: build==1.2.2.post1; extra == "dev"
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: ruff==0.11.7; extra == "dev"
Requires-Dist: twine==6.1.0; extra == "dev"
Dynamic: license-file

[Polski](README.pl.md)

# 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:

| Result | Coverage | Deterministic checks | Findings |
|:---|:---:|:---:|:---:|
| ⚠️ **CONDITIONAL PASS** | `18/18 files` | `25 completed` | `2` |

| What is wrong | Where | Priority | What to do |
|---|---|:---:|---|
| Untrusted input reaches a shell | `handler.py:42` | 🟠 **P1** | Pass an argument list and keep `shell=False` |
| Dependency version is mutable | `requirements.txt:3` | 🟡 **P2** | Pin the reviewed version and integrity hash |

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.

```powershell
pipx install sentinel-ai-auditor
```

Upgrade an existing PyPI installation:

```powershell
pipx upgrade sentinel-ai-auditor
```

Install directly from a pushed repository branch on another computer:

```powershell
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:

```powershell
sentinel install claude
claude --agent sentinel
```

You can also ask Claude in a regular conversation:

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

Install the agent in Codex:

```powershell
sentinel install codex
```

Then ask Codex:

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

Install both host adapters:

```powershell
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:

```powershell
sentinel scan ./target --json
```

List the bundled skills and deterministic checks:

```powershell
sentinel skills
sentinel checks
```

Run the MCP server manually:

```powershell
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

```powershell
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.
