convez.ai
MCP ServerSegurançaAvançado
ruth411

Ayiru – Validador de Comandos Shell para Agentes IA

ruth411/ayiru

Bloqueia alucinações de LLM em comandos shell com conhecimento verificado e citado

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que fornece vereditos de segurança verificáveis para agentes IA antes de executar comandos shell. Mantém um grafo de conhecimento citado com 2.800+ afirmações sobre 60+ ferramentas CLI, usando um motor de risco determinístico com 6 níveis de verificação e log de auditoria imutável.

Instalação

$npx convez-ai ruth411/ayiru

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
2
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 3 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Validar segurança de comandos antes de agentes IA executarem (kubectl, gh, docker, git)
  • Auditoria determinística com rastreabilidade de cada decisão de risco
  • Integração em pipelines de CI/CD com agentes autônomos que precisam de guardrails

Veredito

Solução sólida e necessária para produção: elimina o principal risco de agentes IA autônomos (execução de comandos perigosos baseada em alucinações). A arquitetura com grafo de conhecimento citado, 790 testes passando e suporte MCP nativo é profissional. Recomendado para quem executa agentes com shell access em ambientes críticos.

README

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

   █████╗ ██╗   ██╗██╗██████╗ ██╗   ██╗
  ██╔══██╗╚██╗ ██╔╝██║██╔══██╗██║   ██║
  ███████║ ╚████╔╝ ██║██████╔╝██║   ██║
  ██╔══██║  ╚██╔╝  ██║██╔══██╗██║   ██║
  ██║  ██║   ██║   ██║██║  ██║╚██████╔╝
  ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝ ╚═════╝

Stop your AI agent from hallucinating CLI commands.

A verified, cited knowledge graph that AI agents query before they act.2,800+ claims across 60+ tools — every fact has a citation, no LLM guessing.

Python 3.12+ Tests License MIT

Claims Tools Perfect probes MCP


🚀 Get started in 30 seconds

git clone https://github.com/ruth411/ayiru.git && cd ayiru
docker build -t ayiru . && docker run --rm -p 8000:8000 ayiru

Then open http://localhost:8000/docs in your browser. That's it. ✨


🤔 What is this?

You're building an AI agent. It needs to run real commands on real systems — kubectl delete, gh repo delete, docker rm, git push --force. What could go wrong?

😱 Without Ayiru

# The LLM "thought" this was safe.
# It wasn't.
agent.run(
  "gh repo delete prod --yes"
)
# Production. Gone. 💀

Your agent guesses from training data. That training data is months old, contains deprecated flags, and has no citations.

✅ With Ayiru

from ayiru_client import Ayiru

with Ayiru() as a:
    v = a.validate_command(
        "github-cli",
        "gh repo delete prod --yes"
    )
    if not v.safe_to_auto_execute:
        ask_human(v.reasons)  # blocked ✋

Every fact comes from official docs, with citations and a deterministic risk score.


📥 Install Ayiru

Pick your path. Each one ends with a running Ayiru server on http://localhost:8000.

🐳 Docker

~3 minutes Zero Python setup Full catalog (2,800 claims) → Jump to Docker

🐍 Python

~5 minutes Hackable + local files Best for SDK users → Jump to Python

🛠 Source

~10 minutes Edit + test changes Best for contributors → Jump to source


🐳 Path 1: Docker (easiest)

Best if: you just want to try Ayiru. No Python knowledge needed.

✅ Before you start

You need Docker Desktop (macOS / Windows) or docker (Linux). Verify:

docker --version
# Docker version 27.x or newer ✓

Step 1 — Clone the repo

git clone https://github.com/ruth411/ayiru.git
cd ayiru

Step 2 — Build the image

docker build -t ayiru .

What's happening? Docker is building a self-contained image with Python, Ayiru, and the full 2,800-claim catalog. Takes ~2 minutes the first time.

Step 3 — Run it

docker run --rm -p 8000:8000 ayiru

The published image defaults AYIRU_STRICT_TOOL_LOCK=1, so network-exposed container deployments reject unknown tool_ids by default. Opt out only if you intentionally want uncurated tool ingestion:

docker run --rm -p 8000:8000 -e AYIRU_STRICT_TOOL_LOCK=0 ayiru

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Step 4 — Try your first query ✨

In a new terminal:

curl -X POST http://localhost:8000/v1/query/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "how do I force-push safely after rebase?"}'

Or open the interactive docs at http://localhost:8000/docs in your browser.

🎉 Done. Skip to Your First Query to see what Ayiru can do.


🐍 Path 2: Python + pip (for developers)

Best if: you want to write Python code against Ayiru locally.

✅ Before you start

You need Python 3.12+. Check:

python3 --version
# Python 3.12.x ✓
  • macOS: brew install python@3.12
  • Linux (Ubuntu): sudo apt install python3.12 python3.12-venv
  • Windows: Download from python.org

Step 1 — Clone + enter the repo

git clone https://github.com/ruth411/ayiru.git
cd ayiru

Step 2 — Create a virtual environment

python3.12 -m venv backend/.venv
source backend/.venv/bin/activate    # macOS/Linux
# .\backend\.venv\Scripts\activate   # Windows PowerShell

What's a venv? A folder that holds Ayiru's dependencies, so it doesn't conflict with anything else on your system.

Step 3 — Install Ayiru

pip install -e 'backend[dev]'

Why -e? "Editable install" — changes you make to the code show up immediately.

Step 4 — Start the server

Two flavors depending on what you want:

# (a) Demo graph — small, offline-safe (~47 claims, 5 tools)
ayiru seed --reset
ayiru serve --reload

# (b) Full catalog — 2,800 claims, 60+ tools
AYIRU_DATABASE_URL="sqlite:///$(pwd)/backend/ayiru_v0.2_bulk.db" \
    ayiru serve --reload

ayiru serve auto-applies pending Alembic migrations before boot. If migration fails, the server exits non-zero instead of starting against a stale schema. Pass --no-migrate only if you manage schema changes out of band.

You should see:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Started server process
INFO:     Application startup complete.

Step 5 — Try it

Open http://localhost:8000/docs in your browser or run the curl command from Path 1 above.

🎉 Done. Skip to Your First Query.


🛠 Path 3: From source (for contributors)

Best if: you want to modify Ayiru, run tests, add tools to the catalog.

Same as Path 2, plus:

# Run the test suite (~55 seconds, 790 tests)
cd backend
.venv/bin/python -m pytest -q

# Lint
.venv/bin/ruff check app tests

For adding a new tool to the catalog, see Growing the Catalog.


✨ Your First Query

Once Ayiru is running on http://localhost:8000, try these:

1️⃣ Ask a natural-language question

curl -s -X POST http://localhost:8000/v1/query/ask \
  -H 'Content-Type: application/json' \
  -d '{"question": "trim a video without re-encoding"}' | jq

Expected response:

{
  "answers": [{
    "statement": "Cut a section of video instantly. `ffmpeg -ss 00:01:30 -to 00:02:00 -i in.mp4 -c copy out.mp4`. `-c copy` skips re-encoding (no quality loss, near-instant)...",
    "tool_id": "ffmpeg-recipes",
    "confidence": 0.95,
    "verification_level": "L2_source_verified",
    "evidence": [{
      "source_uri": "https://ffmpeg.org/ffmpeg.html",
      "trust_level": "high"
    }]
  }],
  "fallback_recommended": false
}

2️⃣ Check if a command is safe

curl -s -X POST http://localhost:8000/v1/query/validate-command \
  -H 'Content-Type: application/json' \
  -d '{"tool_id": "github-cli", "command": "gh repo delete prod --yes"}' | jq

Expected response:

{
  "safe_to_auto_execute": false,
  "risk_level": "critical",
  "requires_human_confirmation": true,
  "verification_level": "L2_source_verified",
  "reasons": [
    "Deleting a GitHub repository is an irreversible remote mutation.",
    "Safety policy blocks auto-execution at risk level 'critical'."
  ]
}

3️⃣ Use the Python SDK

from ayiru_client import Ayiru

with Ayiru(base_url="http://localhost:8000") as client:
    # Ask anything
    answer = client.ask("how do I copy files between docker containers")
    if answer.is_useful:
        print(answer.top.statement)
        print(f"📎 Source: {answer.top.evidence[0].source_uri}")

    # Or check command safety
    v = client.validate_command("kubectl", "kubectl delete ns production")
    print(f"Safe to auto-execute: {v.safe_to_auto_execute}")

🤖 Use it with Claude, Cursor, Cline (MCP)

Ayiru speaks Model Context Protocol out of the box — any MCP-aware client can use it.

Claude Desktop (macOS)

Step 1 — Find your ayiru binary:

which ayiru
# /Users/you/path/to/ayiru/backend/.venv/bin/ayiru

Step 2 — Edit Claude's config:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 3 — Add Ayiru as an MCP server:

{
  "mcpServers": {
    "ayiru": {
      "command": "/absolute/path/to/ayiru",
      "args": ["mcp"],
      "env": {
        "AYIRU_DATABASE_URL": "sqlite:////absolute/path/to/ayiru/backend/ayiru_v0.2_bulk.db"
      }
    }
  }
}

Step 4 — Restart Claude Desktop. You'll see 7 new tools in the tool list. Ask Claude:

"Is it safe to run gh repo delete my-org/prod --yes?"

Claude will query Ayiru, see it's flagged critical, and warn you. 🛡️

Same config shape — consult your client's docs for the JSON location. The seven tools Ayiru exposes:

ToolWhat it does
🔥 askNatural-language question → ranked, cited answers
🛡️ validate_commandSafety verdict for {tool_id, command}
📋 get_tool_specFull canonical spec for a tool
🔍 search_toolsSearch across published tools
⚠️ explain_riskRisk classification with reasons
🗺️ get_safe_workflowGoal-matched workflows, safest first
✏️ submit_claimAdd a new claim to the graph (write tool)

📦 Tool Catalog

Ayiru indexes 2,800+ claims across 60+ tools with full per-command depth. Each "deep" tool is decomposed into five surfaces so an agent's query can target the right slice:

SurfaceWhat's on it
🟦 {tool}-cliPer-command pages from official docs (docker run, git rebase)
🟪 {tool}-configConfig-file format, environment, runtime options
🟩 {tool}-recipesReal-world workflows: "trim a video", "force-push safely"
🟥 {tool}-errorsActual error messages with diagnosis + fix steps
🟨 {tool}-{topic}Tool-specific extras: docker-build, git-workflows, kubectl-resources, go-stdlib, ansible-modules

🏆 Deep-coverage tools

⭐ = perfect probe (50/50 questions returned actionable cited answers)

ToolClaimsProbeHighlights
ansible63425/25 ⭐Modules (499), playbook, vault, inventory
docker13644/45CLI + Dockerfile + buildx + compose
gh (GitHub)12949/50auth, pr, repo, workflows, codespaces
helm12848/50Charts + template guide + OCI registry
kubectl12750/50 ⭐43 per-command + RBAC + debugging
openai-api12550/50 ⭐Chat / embeddings / vision / whisper
awk11840/40 ⭐Language + builtins + scripting
git10946/5031 per-command + hooks + submodules
go10850/50 ⭐30 stdlib + generics + reasoning models
pip10549/50PEP 668, hash-pinning, uv migration
cargo10540/40 ⭐Build profiles, workspaces, features
openssl10050/50 ⭐Keys, certs, CSR, TLS debugging
postgresql10150/50 ⭐23 CLIs + WAL + replication + recovery
postgresql-psql9150/50 ⭐Meta-commands + variables + scripting
pnpm10750/50 ⭐Workspaces, catalogs, patch deps
poetry9950/50 ⭐Groups, lockfile, deploy patterns
sqlite39650/50 ⭐SQL + WAL + JSON1 + FTS5 + pgvector
sed8450/50 ⭐Substitution + regex + GNU vs BSD
jq7445/45 ⭐Filters + functions + real pipelines
journalctl7544/45Filters, fields, persistent storage
apt16449/49 ⭐CLI + sources + dpkg interop
rust11348/50Lang + stdlib + cargo errors
supabase9849/50CLI + migrations + RLS + edge fns
ffmpeg9238/45Filters + recipes (trim, hwaccel, GIF)
imagemagick8643/45Resize, watermark, PDF→PNG
gpg8242/45Key gen, sign/verify, smartcard
rsync7048/50Mirror, hardlinks, daemon, SSL
ssh6645/45 ⭐Keys, config, tunnels, hardening
curl7340/40 ⭐Protocols, auth, debugging
brew7133/33 ⭐Formulae, taps, troubleshooting
dnf5737/37 ⭐Repos, history, modules

Plus thin-coverage entries carried from earlier seeding: terraform, vercel, systemctl, wget, vim, tmux, uv, yarn — next depth-pass targets.


🛠️ How It Works

flowchart LR
    CLI[CLI help]
    DOCS[Official Docs]
    OAS[OpenAPI]
    MCP[MCP Servers]

    ORCH[Orchestrator]
    RISK[Risk engine]
    CONF[Confidence scoring]

    GRAPH[(Knowledge graph)]
    AGENT[AI Agent]

    CLI --> ORCH
    DOCS --> ORCH
    OAS --> ORCH
    MCP --> ORCH

    ORCH --> RISK
    ORCH --> CONF
    ORCH --> GRAPH

    AGENT -->|ask| GRAPH
    GRAPH -->|cited answer| AGENT

Six ingestion lanes pull evidence from trusted sources. A deterministic orchestrator validates schema, classifies risk, scores confidence, deduplicates, and detects conflicts. Accepted claims compile into canonical ToolSpec records. A runtime sandbox verifies safe checks (e.g. git --version) and promotes claims. Agents query the result.


🎯 Core Principles

PrincipleWhat it means
📎 Evidence before publicationNo claim enters the graph without cited evidence. LLM reasoning is never primary evidence.
📐 Structured over proseAgents submit typed KnowledgeClaim objects, not free-form articles.
⚠️ Safety is first-classEvery command is classified by side effects, risk, auth, destructive potential.
🎚️ Verification levels are explicitClaims expose L0_unverified → L5_human_audited. No silent inflation.
🔗 Provenance is preservedEvery canonical spec traces back to source claims and source bytes.
🛡️ Sources are data, not instructionsDocs, CLI output, MCP metadata are scanned; their instructions are never executed.

🚨 Troubleshooting

"docker: command not found"

→ Install Docker Desktop. On Linux, sudo apt install docker.io.

"Port 8000 is already in use"

docker run --rm -p 8080:8000 ayiru   # use port 8080 instead

"Python 3.12 is too new / not available"

Install with pyenv or mise:

pyenv install 3.12 && pyenv local 3.12

"Ayiru returns fallback_recommended: true"

That's by design — Ayiru is being honest that it doesn't have a high-confidence answer. Your agent should escalate to web search.

"I can't find my Claude Desktop config"

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Tests pass locally but Docker build fails

Clear Docker cache: docker system prune -a then rebuild.


🏗️ Architecture

ayiru/
├── backend/
│   ├── app/                # FastAPI app, MCP server, services
│   ├── alembic/            # Migrations
│   ├── ayiru_v0.2_bulk.db  # 🌟 Full catalog (2,800 claims)
│   └── tests/              # 790 hermetic tests
├── clients/python/         # ayiru-client SDK + LangChain adapter
├── tools/                  # URL lists + seed scripts (per tool)
├── contracts/              # Versioned JSON trust + ingestion contracts
├── data/seed_artifacts/    # Demo seed for offline-safe install
└── Dockerfile              # Single-stage image
  • Contracts as ground truth. Trust allowlists, ingestion sources, risk taxonomies are versioned JSON files in contracts/. They can't drift from code without a test failing.
  • Five-surface tool decomposition. Each major tool splits into -cli, -config, -recipes, -errors, and one topic-specific surface. Lets agents direct queries and lets the matcher rank within the right neighborhood.
  • Protocol-based dependency injection. Every external dep (HTTP client, MCP runner, sandbox) is a typing.Protocol. Tests inject fakes; production injects real things. Hermetic test suite.
  • Adversarial tests, not happy-path tests. Every ingestion lane has tests for SSRF, redirect attacks, oversized responses, malformed inputs, structured 422s.
  • Semantic re-rank via fastembed. Hybrid lexical + cosine using BAAI/bge-small-en-v1.5 (~130 MB ONNX, no torch). Embeddings stored per-claim, re-ranked on top of lexical first pass.

🌐 API Reference

Live interactive docs at http://localhost:8000/docs when the server is running.

Agent-facing API (under /v1/query/)

EndpointPurpose
POST /v1/query/ask🔥 Headline. NL question → ranked, cited answers
POST /v1/query/validate-command🛡️ Safety verdict for a command
GET /v1/query/tools/{tool_id}Canonical ToolSpec
GET /v1/query/search-tools?q=Search published tools
POST /v1/query/explain-riskRisk classification with reasons
POST /v1/query/safe-workflowWorkflows for a goal, safest first

Claims — POST/GET /claims · POST /claims/{id}/verify Ingestion — POST /ingestion/{cli,docs,openapi,json_schema,graphql,mcp} Canonical — POST/GET /canonical/tools/{id} · /canonical/workflows/{id} Verification — POST /verification/runtime · POST /verification/human-review Audit — GET /audit/events · GET /audit/claims/{id}


🐍 Python SDK

from ayiru_client import Ayiru, AyiruAsync

# Sync
with Ayiru(base_url="http://localhost:8000") as c:
    a = c.ask("how do I remove a docker volume")
    if a.is_useful:
        print(a.top.statement)

# Async
async with AyiruAsync(base_url="http://localhost:8000") as c:
    a = await c.ask("...")

LangChain adapter — drop-in BaseTool:

pip install -e 'clients/python[langchain]'

See clients/python/README.md for the full reference.


📈 Growing the Catalog

Adding a new tool takes ~30 minutes:

  1. 📜 Add to contracts/tool_trust_sources.v1.json — declare official hosts
  2. 🔗 Build URL list in tools/v0.2_seed_<tool>.json
  3. 🛂 Patch contracts/docs_ingestion_sources.v1.json with URLs + subjects
  4. 🕷️ Crawl: ayiru ingest --tool-list tools/v0.2_seed_<tool>.json --source docs --resume
  5. ✍️ Synthesize errors + recipes in tools/scripts/seed_<tool>_errors_recipes.py (~30 errors + 35 recipes)

Probe with ~45 questions, check tests + ruff, commit. See tools/scripts/seed_*_errors_recipes.py for the pattern across 30+ tools.


✅ Verify it works

cd backend

# Run all 790 tests (~55 seconds)
.venv/bin/python -m pytest -q

# Lint
.venv/bin/ruff check app tests

🔐 Security

🌐 HTTP API

Set AYIRU_API_KEY env var to require Authorization: Bearer <key> on all write endpoints plus the sensitive read surfaces: audit history (/audit/*), ingestion artifacts (/ingestion/*), and verification-result listings (/verification-results*). Query / lookup reads stay public so agents can ask without coordinating creds. Timing-safe comparison.

🔌 MCP stdio

The MCP server is local-first. By default it assumes the caller is a trusted local process (Claude Desktop, Cursor), but you can require initialize.params.ayiru_shared_secret by setting AYIRU_MCP_SHARED_SECRET. Don't pipe ayiru mcp over SSH or expose it to untrusted callers without that secret.

⚠️ For any network-exposed deployment, set AYIRU_API_KEY, put it behind a reverse proxy with rate limiting, and only enable forwarded-client rate-limit keying when that proxy is trusted. See SECURITY.md.


VariableDefaultPurpose
AYIRU_DATABASE_URLsqlite:///./ayiru.dbSQLAlchemy URL. Point at backend/ayiru_v0.2_bulk.db for the full catalog.
AYIRU_API_KEYunsetRequired Bearer token for write endpoints plus /audit/*, /ingestion/*, and /verification-results* reads.
AYIRU_TRUSTED_HOSTSunsetOptional comma-separated host allowlist for inbound HTTP Host headers. Supports exact hosts and *.example.com wildcard entries.
AYIRU_MCP_SHARED_SECRETunsetWhen set, requires MCP clients to send params.ayiru_shared_secret in the initialize request before any other MCP method is allowed.
AYIRU_ASK_RATE_LIMIT_REQUESTSunsetWhen set to a positive integer, rate-limits POST /query/ask and POST /v1/query/ask per client key. By default this is the socket peer address.
AYIRU_ASK_RATE_LIMIT_WINDOW_SECONDS60Window size for AYIRU_ASK_RATE_LIMIT_REQUESTS. Ignored unless the ask limiter is enabled.
AYIRU_RATE_LIMIT_TRUST_FORWARDED_FORunsetWhen set to 1 / true, trust the first X-Forwarded-For hop for ask() rate-limit keying. Only enable behind a trusted reverse proxy.
AYIRU_REVIEWER_REGISTRYunsetComma-separated allowlist of reviewer IDs.
AYIRU_STRICT_TOOL_LOCKunset in source installs; 1 in Docker imageRefuses unknown tool_ids at POST /claims. Recommended for network-exposed deployments.
AYIRU_ALEMBIC_INIautodetectOverride path to alembic.ini.
AYIRU_SEED_SCRIPTautodetectOverride path to seed_examples.py.
  • PyPI publication. pip install ayiru doesn't work yet. Install from source for now.
  • Hosted version. No SaaS. Run it yourself.
  • ~15 tools have only thin coverage — terraform, vercel, wget, vim, etc. Next on the depth-pass queue.
  • Freshness story is manual. Re-running ayiru ingest --resume re-fetches changed pages, but no automated upstream change detection yet.
  • SQLite only in CI. Schema is Postgres-portable but no live Postgres tests in CI.
  • No external auth provider. Bearer-token only for now.

📚 More


📜 License

MIT — see LICENSE.

🙏 Built with

FastAPI · Pydantic v2 · SQLAlchemy 2 · Alembic · httpx · fastembed · the Model Context Protocol

⬆ back to top

Built because AI agents shouldn't have to guess.

Ver o original no GitHub

Bom para

Relacionados