convez.ai
MCP ServerSegurançaAvançado
itamarmeirovichai-source

Sentinel – Guardião com Kill Switch para Agentes IA

itamarmeirovichai-source/sentinel

Auditoria compliance-grade + kill switch para agentes IA com padrão default-deny

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que implementa guardrails em tempo de execução e trilha de auditoria à prova de adulteração para qualquer agente IA. Oferece política default-deny, detecção de flags e kill switch instantâneo, garantindo conformidade com regulações como EU AI Act Art. 12 através de logs hash-encadeados e verificáveis.

Instalação

$npx convez-ai itamarmeirovichai-source/sentinel

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Assegurar conformidade regulatória (EU AI Act) em sistemas IA de alto risco
  • Interceptar e auditar cada ação de agente antes de executar em ferramentas críticas
  • Parar agentes IA instantaneamente e manter trilha de evidência à prova de adulteração

Veredito

Sentinel endereça uma lacuna real de compliance: auditoria determinística e enforcement default-deny para agentes IA em sistemas críticos. MVP solid com threat model documentado; APIs ainda podem evoluir (v0.1 alpha).

README

A tradução para o português deste README ainda está na fila.

Sentinel

CI License: Apache-2.0 Python 3.11+

The compliance-grade flight recorder + kill switch for AI agents.

Sentinel sits between any AI agent (any framework) and its tools. Every action is checked against your policy before it runs, recorded into a tamper-evident audit trail you can replay and export as compliance evidence, and you can stop the agent instantly. The point is provability: knowing — and being able to prove — exactly what your agent did.

Status: MVP / alpha (v0.1). This is the narrow wedge of a larger vision (see RESEARCH.md and ROADMAP.md). It is not another prompt-injection filter — it leads with deterministic enforcement + provable audit.

⚠️ Disclaimer. Experimental; APIs may change; provided "as is", no warranty (Apache-2.0). Compliance mappings (EU AI Act Art. 12, OWASP) are indicative engineering aids — not legal advice or a certification. You remain responsible for your own compliance and for reviewing Sentinel before relying on it in high-stakes systems.

Why

Teams can't get sign-off to let agents touch high-stakes systems (trading, billing, prod DBs) because there's no audit-grade record of what the agent did, no enforcement of what it's allowed to do, and no instant stop. Regulation now forces the issue: EU AI Act Article 12 mandates automatic event logging for high-risk systems (enforcement from 2026-08-02). Sentinel is the layer that produces that evidence. Full market/competitive analysis: RESEARCH.md.

Core guarantees

  • Default-deny — an action with no matching allow rule is blocked.
  • Fail-closed — if the decision core itself errors, the action is blocked, not run.
  • Tamper-evident — the audit log is hash-chained; any edit/reorder/delete is detectable via verify.

Architecture (one glance)

agent ─tool_call─► Interceptor ─► KillSwitch? ─► Detector(flags) ─► Policy(default-deny)
                                                                         │
                              audit (hash-chained, redacted) ◄── execute / block

Interception is an SDK wrapper today, behind an Interceptor interface so an MCP-proxy adapter slots in later without touching the policy/audit/kill core. Details + threat model: ARCHITECTURE.md.

Quickstart

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

# run the tests (security-critical core is tested first)
pytest

# run the end-to-end demo (a generic agent; see DEMO.md)
python examples/generic_agent.py        # or: sentinel demo

# launch the control API + dashboard
sentinel serve            # then open http://127.0.0.1:8787

Shortcut: make install && make test && make demo. On PyPI the package is guardledger (the sentinel handle is taken); the import name and CLI stay sentinel — pip install guardledger → import sentinel.

Usage sketch

from sentinel import Sentinel

sentinel = Sentinel.from_files(policy="policies/starter.yaml", db="data/sentinel.db")

@sentinel.guard                      # every call is checked, logged, killable
def send_email(to: str, subject: str, body: str): ...

# …or guard a whole toolset at once:
tools = sentinel.wrap_all({"send_email": send_email, "search_web": search_web})

# over-policy / killed / suspicious calls raise BlockedError and are recorded;
# allowed calls run normally and are recorded with their outcome.

Works with any agent, any framework

Plain Python functions, LangChain, OpenAI Agents SDK, CrewAI, LlamaIndex, or MCP — guard your tools with @sentinel.guard / sentinel.wrap_all(...), or use the MCP proxy/server. See INTEGRATIONS.md. The default demo (sentinel demo) is a generic agent; examples/trading_agent.py is a vertical example.

Two interceptors, one core

The SDK wrapper is the default. For agents that reach tools over MCP, the same enforcement (Sentinel.enforce) runs behind a proxy — nothing the agent calls can bypass it:

from sentinel import MCPProxy, SentinelMCPServer

proxy = MCPProxy(sentinel, upstream=my_mcp_session)   # guard calls to upstream MCP servers
server = SentinelMCPServer(sentinel)                  # OR expose your own tools over MCP
server.add_tool("get_quote", get_quote)               #    with enforcement built in

Install the optional transports with pip install "guardledger[mcp,otel]".

Operating it

  • Monitor mode — SENTINEL_MODE=monitor (or Sentinel(mode="monitor")) logs the would-be verdict and never blocks — the kill switch still works. Deploy in front of a live agent, watch, build trust, then flip to enforce. (Try SENTINEL_MODE=monitor sentinel demo.)
  • Dashboard auth — set SENTINEL_API_TOKEN (or let sentinel serve generate one); mutating endpoints (kill / policy / approve) then require Authorization: Bearer ….
  • Human-in-the-loop — a require_approval call is parked; approve it from the dashboard or sentinel approve <id>, and the next identical call runs exactly once.
  • Interop — sentinel export --format otel emits OpenTelemetry GenAI spans (gen_ai.*) for Langfuse / Datadog / any OTel backend.
  • Compliance — sentinel compliance --all maps Sentinel to EU AI Act, GDPR, NIST AI RMF, ISO 42001, Colorado AI Act, and SEC/FINRA with honest full/partial/none coverage (COMPLIANCE.md); sentinel export --format art12 produces an EU AI Act Article 12 record-keeping report.
  • Housekeeping — sentinel gc purges stale approvals / rate-limit state (never the audit log).
  • Overhead — ~0.4 ms per guarded call on a dev laptop (policy + detector + two durable audit writes), well under the 20 ms target. Reproduce: python examples/benchmark.py.

Documents

FileWhat
RESEARCH.mdMarket & competitive research, wedge recommendation
PRD.mdProduct requirements for this MVP
ARCHITECTURE.mdComponents, data flow, threat model
DECISIONS.mdDecision log
INTEGRATIONS.mdAdd Sentinel to any framework (LangChain, OpenAI, CrewAI, MCP, …)
LAUNCH.mdThe honest go-to-market plan + ready-to-post launch assets (launch/, site/)
DEMO.mdHow to run the end-to-end demo
ROADMAP.mdWhat's next, and the known-limitation → feature map
SECURITY.mdDesign posture, self-check, known limitations
COMPLIANCE.mdMapping to AI/data law (EU AI Act, GDPR, NIST, ISO 42001, Colorado, SEC/FINRA)
CHANGELOG.mdRelease notes

License

Apache-2.0.

Ver o original no GitHub

Bom para

Relacionados