Shield KYA

Trilha de auditoria e rastreabilidade para agentes de IA. Portão MCP: avaliar, ingerir, solicitar aprovação.

Documentação

`@shield-agent/kya`

Trilha de auditoria e rastreabilidade para agentes de IA. Veja o que cada agente de codificação fez, com aprovação humana opcional e certificação assinada. Cada chamada de ferramenta é registrada em um painel local ao vivo e certificável contra a Linha de Base de Confiança do Agente. Localmente, o KYA é consultivo e falha aberto, exceto por uma pequena lista de nunca que é negada; a aplicação vive no caminho do portão MCP e no plano hospedado. Um comando. Gratuito para sempre sob MIT.

npm i -g @shield-agent/kya@latest && kya start

Requer Node.js 24+. Reinicie o Cursor / Claude Code / Codex uma vez para que o MCP carregue. Painel hospedado: shield-agent.com.

CLI e portão MCP local para o caminho Know Your Agent da Shield.

Um agente que pergunta à Shield primeiro recebe Allow, Review ou Deny: você registra o agente, envolve a ferramenta (ou a roteia pelo portão MCP ou pelo plano hospedado), e Review espera por uma pessoa. Hooks locais apenas registram e bloqueiam a lista de nunca (veja Interceptação de hook); o hospedado é onde a aplicação vive. Este pacote não escaneia sua rede. Agentes que nunca chamam evaluate permanecem invisíveis de propósito.

Passo a passo: como você usa.

npx @shield-agent/kya@latest --help

Requer Node.js 24+ (engines.node: >=24). Em um Node mais antigo, o CLI oferece instalar o 24 para você (via volta / fnm / nvm / brew), reinstalar a si mesmo e terminar o comando - recusar apenas imprime um aviso e continua.

Funciona com qualquer host que fale MCP ou OpenAPI. Pacotes verticais são opcionais. A Shield é o único ponto de decisão de política: este portão nunca aprova automaticamente um efeito colateral irreversível.

Se KYA_API_KEY estiver vazio contra um plano autenticado, comandos de rede saem com código não-zero. eval-tool, wrap e invoke saem com 0 em ALLOW, 4 em REQUIRE_APPROVE e 1 em DENY ou desconhecido, então uma linha como eval-tool && write não pode pular o portão.

--offline executa evaluate de amostra sem nuvem paga (útil para demonstrações de DENY e REQUIRE_APPROVE). Criar um agente é em si uma ferramenta: offline, kya.agent.register retorna REQUIRE_APPROVE. Modos Allow, break-glass e approve mint vivem no plano de controle.

Uma linha

npm i -g @shield-agent/kya@latest && kya start

Execute no diretório do seu projeto. (De um clone deste repositório, ./scripts/install-local.sh substitui o npm install.)

Mais formas de instalar (mesmo pacote; npm continua sendo o caminho de referência):

# Homebrew. Homebrew 7 may ask you to trust a third-party tap: run `brew tap The-Pixel-Boys/tap` first.
# The formula installs about 270MB because of the optional semantic-search runtime.
brew install The-Pixel-Boys/tap/shield-kya

# Scoop (not yet verified on Windows)
scoop bucket add The-Pixel-Boys https://github.com/The-Pixel-Boys/scoop-bucket.git
scoop install shield-kya

Usuários de Claude Code e GitHub Copilot CLI também podem instalar o plugin; usuários de Codex CLI o plugin Codex; usuários de Gemini CLI a extensão Gemini CLI.

Isso inicializa .kya/, conecta o MCP local (.mcp.json, mcp.json, .cursor/mcp.json → kya serve-mcp --stdio), também conecta configurações de nível de usuário para cada host instalado que detecta (~/.claude.json, ~/.kimi-code/, ~/.grok/, ~/.cursor/, …), e abre o relatório de atividade ao vivo. O relatório roda em segundo plano - você recupera seu terminal; kya stop o interrompe, kya receipt --open o reabre. Cursor, Kiro, Qwen, Amp, Droid, Cline e Grok captam o servidor ao vivo sem reiniciar (Kimi: apenas uma nova sessão); Claude Code, Codex, OpenCode, Gemini, Copilot CLI e Kilo CLI o carregam no próximo lançamento - claude --resume mantém sua conversa.

kya start --no-open   # wire only
kya start --force     # rewrite MCP blocks
# Receipt change previews (clipped + redacted): on by default for writes
# KYA_DIFF_PREVIEW=0 to disable

Um comando por host

kya start cobre Claude Code, Cursor e qualquer host que leia .mcp.json - e conecta automaticamente a configuração de nível de usuário de cada host instalado que detecta. Para o resto, kya connect escreve o dialeto de configuração do próprio host diretamente:

kya connect claude              # ~/.claude.json (merges mcpServers only)
kya connect grok                # ~/.grok/config.toml (appends [mcp_servers.shield-kya])
kya connect opencode            # ~/.config/opencode/opencode.json
kya connect qwen                # ~/.qwen/settings.json
kya connect amp                 # ~/.config/amp/settings.json
kya connect qwen --project      # project scope instead of global
kya connect kiro --force        # overwrite an existing shield-kya entry

Connect mescla - nunca reescreve uma configuração de host que não consegue analisar, e mantém seus outros servidores e chaves. Hosts suportados: claude, grok, opencode, kilo, kiro, qwen, kimi, mastracode, amp, copilot, cursor. Cada um conecta serve-mcp --stdio com KYA_OFFLINE=1 para que o portão comece sem chave; defina KYA_API_KEY no env do host quando apontar para um plano autenticado.

Hosts sem um alvo connect ainda funcionam: kya wrap --offline -- <agent command> coloca o mesmo portão de evaluate na frente de qualquer CLI. Receitas por host com etapas de verificação e solução de problemas vivem em docs/hosts/.

Interceptação de hook

kya start também conecta um hook PreToolUse em cada host com capacidade de hook instalado que detecta: Claude Code (~/.claude/settings.json, somente mesclagem), Grok (~/.grok/hooks/shield-kya.json, arquivo gerenciado por kya) e Kimi Code (~/.kimi-code/config.toml, anexo [[hooks]]). Cada chamada de ferramenta que o agente faz então passa por kya hook primeiro: avaliada localmente (offline, sub-segundo, sem rede) e registrada na trilha global. (Se você optou por estatísticas de uso anônimas, o hook também inicia um helper destacado no máximo uma vez por dia; veja Estatísticas de uso anônimas.)

Mapeamento de decisão: um DENY da lista de nunca local bloqueia a chamada de ferramenta (saída 2 mais JSON de negação hookSpecificOutput com permissionDecision: "deny"). ALLOW e REQUIRE_APPROVE são registrados na trilha como consultivos e a chamada prossegue. A conexão manual pode passar --strict no comando do hook para também bloquear REQUIRE_APPROVE.

Hooks falham abertos: qualquer erro ou timeout de hook permite a chamada. São alertas mais aplicação da lista de nunca local, não a única barreira - a aplicação do plano permanece no caminho MCP kya.policy_evaluate. Hooks entram em vigor em novas sessões; todos os três hosts carregam hooks no início da sessão.

kya connect claude --hooks   # wire the PreToolUse hook by hand
kya connect grok --hooks
kya connect kimi --hooks

Plugin Claude Code / GitHub Copilot CLI

Este repositório também é um mercado de plugins Claude Code chamado shield-kya com um plugin, kya:

/plugin marketplace add The-Pixel-Boys/shield-kya
/plugin install kya@shield-kya

O plugin é consultivo e falha aberto: registra cada chamada de ferramenta na trilha local (~/.kya/trail.jsonl) e bloqueia apenas a pequena lista de nunca. Se kya estiver ausente, travar ou expirar, a chamada de ferramenta prossegue e nada é registrado. Avalia offline, então não tem Hold nem aprovação; a aplicação hospedada é o caminho do portão MCP.

Implantação em equipe: faça commit de extraKnownMarketplaces (a fonte GitHub shield-kya) e enabledPlugins ("kya@shield-kya": true) no .claude/settings.json do repositório, ou force em toda a organização com configurações gerenciadas. Detalhes, limites e notas do Copilot CLI (suporte a hook lá não é verificado; kya connect copilot é o caminho verificado): docs/hosts/claude-plugin.md.

Plugin Codex

O mesmo repositório é um mercado de plugins Codex (.agents/plugins/marketplace.json) com o mesmo plugin kya:

codex plugin marketplace add The-Pixel-Boys/shield-kya
codex plugin add kya@shield-kya

Então abra /hooks no Codex CLI e confie nos dois hooks Shield KYA: o Codex não executa nenhum hook de plugin até você fazer isso. O Codex confia no comando do hook, não nos scripts que ele executa; o comando SessionStart carrega a versão do kya, então cada lançamento do kya pergunta novamente. O Codex também atualiza automaticamente mercados Git na inicialização, então quem puder enviar para este repositório pode mudar o que roda em seguida; equipes podem fixar uma ref de lançamento (veja o guia). Mesmo comportamento do plugin Claude Code: consultivo, falha aberto, registra cada chamada de ferramenta que o Codex envia pelos seus hooks (shell, apply_patch, MCP e outras ferramentas locais; não ferramentas hospedadas como busca web), bloqueia apenas a lista de nunca. Não inclui servidor MCP; adicione um com kya connect codex. Detalhes: docs/hosts/codex.md.

Extensão Gemini CLI

A raiz do repositório também é uma extensão Gemini CLI (gemini-extension.json + hooks/hooks.json):

gemini extensions install https://github.com/The-Pixel-Boys/shield-kya

Mesmo comportamento dos outros plugins: consultivo, falha aberto, registra cada chamada de ferramenta que o Gemini envia pelo seu hook BeforeTool, bloqueia apenas a lista de nunca. O Gemini executa hooks de extensão sem uma etapa de confiança separada. A extensão fixa a versão do kya com a qual foi lançada. Não inclui servidor MCP; veja os exemplos MCP. Detalhes: docs/hosts/gemini.md.

Portão (gateway MCP local)

kya gate coloca um único listener somente loopback (127.0.0.1, porta padrão 3930) na frente de qualquer servidor MCP que você já usa. Seu host fala com o gateway; o gateway distribui para os servidores reais. Política por ferramenta é gerada a partir da taxonomia de top-20 servidores - nomes destrutivos (drop/truncate/purge/transfer) e ferramentas de nível ADMIN de cada servidor são negadas diretamente (e filtradas de tools/list), todo o resto roda em modo de observação: permitido e auditado. Cada chamada é rastreada na trilha local e no relatório ao vivo, e pode ser encaminhada como OTLP para o intake hospedado.

Zero-touch: kya start já faz isso por você. Escaneia suas configurações de host detectadas em busca de servidores MCP de terceiros, importa-os para .kya/gateways.json (registrados com um campo de proveniência importedFrom), instala o binário do gateway, inicia o listener e reescreve cada host de origem para que os servidores importados roteiem pelo gateway - a configuração original do host é preservada sob .kya/backups/ antes que qualquer coisa seja removida. Nada encontrado → nada baixado, sem listener. Opte por sair com kya start --no-gate ou KYA_GATE=off. Se o download do binário falhar (offline, sem rede), kya start avisa uma vez e continua sem o gateway - as configurações do host permanecem intocadas. O caminho manual abaixo ainda está lá quando você quer controle total:

kya gate init     # scaffold .kya/gateways.json with ready-to-move recipes
# edit gateways.json: move a recipe into "servers", fill its placeholders
kya gate setup    # download the pinned gateway binary into .kya/bin
kya gate run      # generate the gateway config, start the listener detached
kya connect claude --gate   # point the host at the gateway (server key shield-kya-gate)
kya gate doctor   # binary, config, listener health, loopback-only posture

kya gate stop interrompe o supervisor e o binário junto. Notas honestas: kya gate setup (e o auto-bootstrap de kya start, apenas quando encontrou servidores para governar) baixa o binário do gateway fixado de nossos lançamentos - nada mais baixa qualquer coisa (o único outro uso de rede são as estatísticas de uso anônimas opcionais em docs/telemetry.md, desligadas a menos que você diga sim); run nunca baixa. Modo de observação significa que chamadas permitidas são registradas, não bloqueadas - o conjunto de negação acima é o único bloqueio rígido, e a aplicação do plano permanece com kya.policy_evaluate. kya connect <host> --gate cobre os mesmos hosts que connect simples - grok recebe uma tabela de URL [mcp_servers.shield-kya-gate] em seu config.toml (Grok suporta servidores MCP remotos sobre HTTP). Níveis por servidor e receitas: docs/mcp-servers.md.

Caminho mais longo (opcional)

# Offline sample evaluate
kya eval-tool --offline --tool-id org.sample.never.event --irreversible
kya wrap --offline --tool-id Write --irreversible --args '{"path":"src/x.ts","content":"hi"}'
kya receipt --open
# Org Hold: KYA_HOLD=1 kya wrap …
kya dash --once --offline

Instalar hub: https://shield-agent.com/install

Trilha de atividade (global)

Uma trilha para todos os projetos: ~/.kya/trail.jsonl (KYA_HOME substitui ~). kya receipt --open de qualquer diretório mostra atividade de todos os projetos. Cada evento carrega o nome da pasta do projeto - o relatório adiciona um resumo de Projetos quando dois ou mais projetos aparecem, e mostra o projeto em cada entrada do feed. Arquivos <project>/.kya/trail.jsonl mais antigos por projeto ainda são lidos e mesclados; sem migração. A trilha é limitada a 1 MB (leitura pela cauda: eventos mais antigos caem), compartilhada entre todos os projetos.

O relatório em si é um painel: uma linha hero no topo (resultado Certify ao vivo, mistura de veredictos, sparkline de atividade, showback) com seções em abas abaixo - Visão geral (análises, sessões, razões), Certify (a tabela completa de requisitos ao vivo - cada requisito agrupado por domínio com status, evidência e atestação), Atividade (o feed de eventos filtrável), Sistema (hosts conectados, sandboxes, ORR). Tudo é uma única página HTML offline autônoma (a visão ao vivo adiciona um único link externo: "Star on GitHub"); o daemon ao vivo de kya start a re-renderiza a cada evento.

Compartilhando um relatório

kya receipt --share publica um resumo editado da janela atual (contagens agregadas de veredictos, consolidações por produto e código de motivo, e o status de Certify - sem caminhos, sem argumentos de ferramentas, sem IDs de sessão) para shield-agent.com e imprime uma URL pública (/r/<id>, expira após 7 dias) que qualquer pessoa pode abrir - cada página compartilhada carrega a instrução de instalação de uma linha para que os leitores possam auditar seus próprios agentes. Aponte para um coletor diferente com --share-url <base> ou KYA_SHARE_URL.

O compartilhamento é uma única tentativa por design (à prova de tempestades: sem novas tentativas silenciosas contra o coletor); --share-retries <n> (máx. 3) opta por novas tentativas limitadas em falhas 429/5xx/rede com backoff exponencial + jitter, respeitando o Retry-After do servidor.

Pesquisa em linguagem natural

A caixa de pesquisa Activity entende inglês simples. Ela executa um híbrido de BM25 sobre IDs de ferramentas, resumos, códigos de motivo, veredictos, projetos e rótulos de servidores MCP, além de reclassificação semântica local MiniLM (enviada como dependência opcional; o relatório volta para apenas lexical se o runtime do modelo não estiver disponível). Um glossário de conceitos integrado mapeia palavras do dia a dia para o vocabulário que os eventos realmente usam, então dangerous encontra chamadas rm/kill/delete/sudo, blocked encontra negações, e held encontra solicitações de aprovação. Você também pode digitar coisas como failed stripe transfers, files written by grok, ou approval required production - stopwords e stemming são tratados automaticamente, e a mesma pesquisa funciona em todo o rastro global.

Offline ou KYA_OFFLINE=1 mantém a pesquisa puramente lexical (sem download de modelo).
Por padrão, o servidor ao vivo baixa BAAI/bge-small-en-v1.5 uma vez em ~/.kya/models e armazena em cache os vetores de eventos em ~/.kya/search-index.json.
KYA_SEARCH_SEMANTIC=off desativa o modelo enquanto mantém o BM25.

O console hospedado usa a mesma pesquisa híbrida no lado do servidor (Postgres full-text + embeddings opcionais compatíveis com OpenAI), então consultas digitadas em qualquer lugar se comportam da mesma maneira.

Plano duplo

 host=ide (authoring)          host=runtime (production)
        │                              │
        └────────── same agent ────────┘
                    identity
                    policy evaluate  → ALLOW | DENY | REQUIRE_APPROVE
                    approval + trail

Marque sessões com KYA_HOST=ide ou KYA_HOST=runtime. Mesmo caminho de política de qualquer forma.

Ambiente

Variável	Obrigatório	Significado
`KYA_BASE_URL`	Sim (comandos de rede)	Origem do plano de controle
`KYA_API_KEY`	Quando a autenticação está ativa	Chave de API (ou JWT Bearer para verbos de decisão)
`KYA_HOST`	Não (padrão `ide`)	`ide` \| `runtime`
`KYA_AGENT_ID`	Após registrar	ID do principal do agente
`KYA_MCP_PORT`	Não (padrão `3920`)	Porta de escuta HTTP MCP
`KYA_OFFLINE`	Não	`1`/`true` para avaliar amostra
`KYA_HOLD`	Não	`1`/`true` para o caminho Hold da organização (REQUIRE_APPROVE abre um ticket humano)
`KYA_DASH_PLAN`	Não	`enterprise` desbloqueia painéis TUI licenciados
`KYA_DIFF_PREVIEW`	Não	`0` desativa pré-visualizações de alterações cortadas no recibo
`KYA_RECEIPT_AUTO`	Não	`0` desativa abertura automática do recibo após wrap; `1` força
`KYA_SEARCH_SEMANTIC`	Não	`off` desativa a reclassificação semântica MiniLM (BM25 ainda funciona)
`KYA_SHARE_URL`	Não	`kya receipt --share` base do coletor (padrão `https://shield-agent.com`)
`KYA_TELEMETRY`	Não	`0`/`off` força estatísticas de uso anônimas desativadas (docs/telemetry.md); elas estão desativadas a menos que você opte por ativá-las
`DO_NOT_TRACK`	Não	`1` força estatísticas de uso anônimas desativadas, igual a `KYA_TELEMETRY=0`

O modo de portão também pode ser fixado no .kya/config.json do projeto: {"gateMode": "hold"} ou {"gateMode": "offline"} (apenas valores exatos - qualquer outra coisa é ignorada). O portão em si (wrap / hook / eval) o honra com a precedência flags > env > config > observe, e kya certify relata através do mesmo resolvedor, então uma aprovação de certify no modo de portão sempre reflete como o portão realmente executa.

Ferramentas MCP

Ferramenta	Papel
`kya.policy_evaluate`	`ALLOW` \| `DENY` \| `REQUIRE_APPROVE`
`kya.session_ingest`	Observar / risco apenas de elevação
`kya.request_approval`	Abrir um Hold humano. Não executa o efeito colateral

Entrada do Registro MCP: server.json mais pacote mcpName io.github.The-Pixel-Boys/shield-kya.

{
  "mcpServers": {
    "shield-kya": {
      "command": "npx",
      "args": ["--no-install", "@shield-agent/kya@0.27.0", "serve-mcp", "--stdio"],
      "env": {
        "KYA_BASE_URL": "http://127.0.0.1:8090",
        "KYA_API_KEY": "${KYA_API_KEY}",
        "KYA_HOST": "ide"
      }
    }
  }
}

Wrap e decidir

npx @shield-agent/kya wrap --offline --tool-id org.sample.data.write --irreversible
npx @shield-agent/kya approve --id <approval-id>
npx @shield-agent/kya reject --id <approval-id>

wrap avalia e pode abrir um ticket pendente. Nunca executa o efeito colateral. invoke pede ao plano ao vivo para autorizar após Allow ou APPROVED. Não executa a escrita nesta máquina. O TUI (dash) pode a/x decidir apenas após y confirmar com um JWT (sk_* recusado).

Shims de SDK em processo

Agentes construídos em LangGraph.js, Vercel AI SDK, Mastra, OpenAI Agents TS, ou Claude Agent SDK podem rotear chamadas de ferramentas pelo mesmo caminho de avaliação sem um gateway:

import { governed, governLangGraphTool, KyaDeniedError } from "@shield-agent/kya/sdk";

const run = governed({ toolId: "write_file", server: "filesystem", fn: myWrite });
await run({ path: "out.txt", content: "hi" }); // throws KyaDeniedError on DENY

Avaliação offline por padrão (sem rede, sem plano hospedado); uma configuração explícita honra o plano ao vivo. governA2aSend controla envios agente-a-agente em processo. Um shim Python fail-open com middleware LangChain está em desenvolvimento e ainda não foi lançado. Matriz de suporte e receitas: docs/sdk-integrations.md; scripts executáveis: examples/sdk/.

Conector Claude

Desktop / Claude Code (stdio local):

# Prefer a preinstalled package (no registry auto-install):
npx --no-install @shield-agent/kya@0.27.0 serve-mcp --stdio
# Or after npm i -g / local install:
kya serve-mcp --stdio

Copie claude/claude_desktop_config.example.json nas configurações MCP do Claude Desktop, ou use .mcp.json para Claude Code. Empacote uma extensão Desktop com npx @anthropic-ai/mcpb pack (veja manifest.json). Esse pacote executa o dist/cli.js empacotado, não npx -y.

Claude.ai / Cowork (hospedado): adicione um conector personalizado em https://shield-agent.com/mcp com cabeçalho de solicitação Authorization: Bearer <KYA_API_KEY> (ou X-API-Key). Ainda não está listado no Directory (autenticação por chave de API, sem OAuth DCR).

OpenAI (Codex / Responses)

Plugin Codex CLI (hooks): veja Codex plugin. Codex CLI / IDE (MCP): copie openai/codex.config.example.toml em ~/.codex/config.toml. Stdio local usa npx --no-install @shield-agent/kya@0.27.0 serve-mcp --stdio. Codex hospedado usa url = "https://shield-agent.com/mcp" com bearer_token_env_var = "KYA_API_KEY".

API Responses: veja openai/responses-mcp.example.json (server_url + Authorization: Bearer <KYA_API_KEY>).

ChatGPT Apps (chatgpt.com): adiado. Developer Mode quer OAuth. Use Codex até lá.

CLI Gemini

Mescle gemini/settings.example.json (stdio) ou gemini/settings.hosted.example.json (httpUrl + Bearer) em ~/.gemini/settings.json ou .gemini/settings.json. Não habilite ambos ao mesmo tempo.

Grok

Grok CLI (local): kya connect grok anexa uma tabela [mcp_servers.shield-kya] a ~/.grok/config.toml (serve-mcp --stdio, avaliação de amostra offline sem chave). Em uma sessão em execução, pressione r em /mcps para atualizar.

grok.com (hospedado): conector personalizado em https://shield-agent.com/mcp (veja grok/README.md). Grok rejeita localhost. Prefira uma chave de máquina Bearer quando a interface oferecer um cabeçalho de solicitação.

Mais hosts

Cada um inclui um exemplo copiável em seu próprio diretório; kya connect <host> escreve o mesmo para os marcados com estrela. Receitas completas (verificar, desinstalar, solução de problemas): docs/hosts/.

Host	Configuração	Exemplo
Claude Code	`kya connect claude` (ou `kya start`)	- (mescla `~/.claude.json` / `.mcp.json`)
Grok CLI	`kya connect grok`	- (anexa `[mcp_servers.shield-kya]` a `~/.grok/config.toml`)
OpenCode	`kya connect opencode`	`opencode/opencode.example.json`
Kilo Code	`kya connect kilo`	`kilo/kilo.example.json`
Kiro	`kya connect kiro`	`kiro/mcp.example.json`
Qwen Code	`kya connect qwen`	`qwen/settings.example.json` (+ `settings.hosted.example.json`)
Kimi Code	`kya connect kimi`	`kimi/mcp.example.json`
MastraCode	`kya connect mastracode`	`mastracode/mcp.example.json`
Amp	`kya connect amp`	`amp/settings.example.json`
GitHub Copilot CLI	`kya connect copilot`	`copilot/mcp-config.example.json`
Cline	copie para o globalStorage do VS Code	`cline/cline_mcp_settings.example.json`
Droid	`droid mcp add` (esquema não verificado)	`droid/mcp.example.json`
Pi · OMP · Devin · Hermes · Qoder · Maki · Muse · Antigravity	`kya wrap --offline -- <cmd>`	docs/hosts/

Plugin Cursor

O pacote inclui .cursor-plugin/plugin.json, mcp.json, e uma habilidade de wrap. Repositório de listagem pública: https://github.com/The-Pixel-Boys/shield-kya

ORR (somente relatório)

npx @shield-agent/kya orr run --path . --out ./orr-report --skip-optional-producers
npx @shield-agent/kya orr run --path . --out ./orr-report --scorecard ./scorecard.json --producer openssf.scorecard
npx @shield-agent/kya orr run --path . --out ./orr-report --producer harness.agentshield --agentshield-json ./agentshield-report.json

ORR é um painel de relatórios. Scanners, --scorecard, e harness.agentshield são evidências. Eles nunca PERMITEM um efeito colateral de alto risco, então não são um segundo portão de política. AgentShield é opcional e somente leitura: sem --fix, sem MiniClaw, sem hook de runtime. Este pacote não depende de ecc-agentshield. Se você passar --producer harness.agentshield e não tiver nem --agentshield-json nem um binário agentshield, ORR registra uma lacuna de cobertura e ainda sai com 0. --producer explícito sempre tenta; --skip-optional-producers apenas pula produtores que você não solicitou.

Certify (garantia contínua do agente)

kya certify avalia o catálogo aberto Agent Trust Baseline (catalog/agent-trust-baseline-v0.json - 30 requisitos em Dados e Privacidade, Segurança, Segurança Física, Confiabilidade, Responsabilidade, Sociedade) contra evidências locais: o rastro global, saída ORR, hosts conectados, inventário de sandbox, recibos, showback, e suas atestações registradas. Ele escreve um relatório de lacunas em .kya/certify/ (JSON + Markdown + HTML). A lista de lacunas é seu plano de trabalho. O relatório de recibo mostra o mesmo estado ao vivo: um painel Certify recalculado a cada renderização (então o relatório ao vivo de kya start atualiza conforme os eventos chegam), além de uma aba dedicada Certify com a tabela completa de requisitos ao vivo - execute kya certify para o relatório completo de lacunas + pacote de evidências assinado.

npx @shield-agent/kya certify                  # gap report; exit 1 when gaps exist (CI-friendly)
npx @shield-agent/kya certify --open           # open the HTML report
npx @shield-agent/kya certify --fail-on never  # report only, always exit 0
npx @shield-agent/kya certify --attest SOC-01 --text "Acceptable-use policy: https://example.com/aup"
npx @shield-agent/kya certify --sign           # also emit a signed evidence-bundle.json

Certify é somente evidências. Nunca PERMITE, NEGA, ou bloqueia nada - o único PEP permanece Shield KYA. Verificações de máquina baseadas em rastro nunca passam em um rastro vazio (elas relatam insufficient_evidence). O que uma máquina não pode verificar é coberto por atestações locais explícitas (--attest), registradas em .kya/attestations.json - declarações de operador não verificadas, rotuladas como tal.

--sign emite evidence-bundle.json: JSON canônico, assinado com ed25519 por uma chave gerada localmente (~/.kya/keys/evidence-ed25519.json, modo 0600, criada automaticamente no primeiro uso). Cada execução de --sign imprime a impressão digital da chave de assinatura; quando a chave acabou de ser criada, o CLI observa que a continuidade da chave é redefinida ali (pacotes anteriores permanecem verificáveis apenas sob a chave pública antiga). Uma chave de desenvolvedor autoassinada prova integridade do pacote e continuidade de uma chave - não identidade. Vinculação de identidade e o selo verificado são o produto de verificação hospedado (separado). O formato do pacote é aberto e documentado em docs/certify.md; qualquer pessoa pode verificar um pacote offline com a chave pública embutida.

kya certify é local, gratuito e offline: sem conta, sem chamadas de rede, sem verificação de licença (nunca envia estatísticas de uso). O catálogo é licenciado sob MIT e PRs são bem-vindos. Um mapeamento EU AI Act (requisitos de linha de base mapeados para Artigos 9-15, 26, 72) é enviado em docs/certify-eu-ai-act.md e src/certify/eu-ai-act-map.json.

Importar rastros (LangSmith, Langfuse, Phoenix, OTel, AGT, ADR Sensor)

Traga exportações de observabilidade existentes para o rastro para que o recibo e o certify as vejam:

kya import --from langsmith ./runs.json
kya import --from langfuse ./observations.jsonl
kya import --from otel ./otraces.json
kya import --from agt   # Microsoft Agent Governance Toolkit audit log
kya import --from adr-sensor ./adr-sensor-events.jsonl

O importador AGT verifica a cadeia de hash do AGT, sinaliza logs adulterados com chainVerified=false, e nunca duplica linhas em re-importação; veja docs/import-agt.md. Eventos ADR Sensor mapeiam um AgentEvent para um ou mais eventos de rastro, com deduplicação estável de uuid em re-importação; veja docs/import-adr-sensor.md. A cadeia de hash do AGT não tem chave, então "verificado" significa internamente consistente, não autêntico. O console hospedado aceita os mesmos formatos (docs/import-agt-hosted.md).

Importações chegam como eventos de modo observe (host: import, reasonCode: IMPORTED, execuções com erro se tornam DENY/IMPORTED_ERROR), com latência e contagens de tokens mapeadas quando a fonte as carrega. Arquivos acima de 50MB são recusados; registros malformados são pulados, nunca fatais. O relatório (kya start / kya receipt) mostra um cartão Import com contagens por formato, contagem de erros, e o evento importado mais recente uma vez que qualquer importação tenha chegado.

Investigação (detecções + resumos de correção)

kya investigate executa detectores locais determinísticos sobre o rastro — sem chamadas de LLM: vazamentos de PII em resumos, picos de DENY, loops de repetição de aprovação, tentativas repetidas de eventos proibidos, ferramentas desconhecidas em espera, ferramentas lentas. As descobertas são agrupadas em incidentes, e cada incidente gera um resumo de correção em markdown formatado para colar no Claude Code / Cursor / Codex. Cada execução também persiste um resumo compacto em ~/.kya/investigate-last.json, que o relatório renderiza como um cartão Investigações (descobertas por gravidade com IDs de detectores, além do principal resumo de correção).

kya investigate           # summary: counts by severity + top incidents
kya investigate --json    # findings + incidents + briefs, machine-readable

Descoberta de endpoints

kya discover inventaria agentes de IA, extensões de IDE, aplicativos de desktop, runtimes de modelo e servidores MCP na estação de trabalho atual. O scanner apenas inspeciona caminhos e arquivos de configuração; ele nunca executa binários descobertos e nunca se conecta a portas de runtime. Os snapshots são gravados em ~/.kya/discovery/<iso-ts>.json com uma cópia latest.json, e o relatório ao vivo mostra um cartão Descoberta com totais, contagens sancionadas/revisadas e principais categorias.

kya discover                              # scan, save snapshot, print summary
kya discover --json                       # print snapshot JSON to stdout
kya discover --diff ~/.kya/discovery/latest.json  # compare current scan to saved snapshot
kya discover --push                       # scan and push to hosted console

O push requer KYA_BASE_URL e KYA_API_KEY:

export KYA_BASE_URL=https://shield-agent.com
export KYA_API_KEY=your-token
kya discover --push

Prefixos de diretório inicial são redigidos dos caminhos de evidência (substituídos por ~). O snapshot inclui um endpointUid estável derivado do SO, hash do hostname e hash do usuário — nenhum hostname ou nome de usuário bruto sai da máquina. Consulte docs/discovery.md para a lista completa de varreduras e notas de privacidade.

Webhooks de alerta (roteamento de veredito)

Roteie eventos DENY / REQUIRE_APPROVE para Slack, Linear, Jira ou qualquer webhook. A configuração fica em .kya/config.json (projeto) ou ~/.kya/config.json (global):

{
  "notify": {
    "webhooks": [
      { "url": "https://hooks.slack.com/services/...", "template": "slack", "events": ["DENY", "REQUIRE_APPROVE"] },
      { "url": "https://example.invalid/jira", "template": "jira", "events": ["DENY"] }
    ]
  }
}

KYA_NOTIFY_WEBHOOK=<url> é a variante de configuração zero (payload genérico). A entrega tenta novamente com backoff exponencial (250ms/1s/4s + jitter), timeouts por tentativa, um disjuntor por URL e um limitador de taxa de envio; os payloads são construídos apenas a partir de campos de rastro redigidos, com um fallback minimizado automático se a varredura de segredos disparar. De spawns de hook/wrap de curta duração, a entrega usa um helper destacado (kya notify-flush), então o caminho do gate nunca espera pela rede. Cada tentativa de entrega é anexada a ~/.kya/notify-log.jsonl (apenas host de destino, nunca a URL completa; limitado às últimas 500 entradas), e a aba Sistema do relatório mostra um painel Alertas com contagens entregues/falhas por destino e a última tentativa.

Wrap de sandbox opcional (Firecracker)

Ao lado do gate, não dentro do MCP. Somente opt-in:

KYA_SANDBOX=mock kya sandbox spawn
KYA_SANDBOX=mock kya sandbox exec --sandbox-id <id> --cmd "true"
KYA_SANDBOX=mock kya sandbox kill --sandbox-id <id>

org.sample.sandbox.exec sem --sandbox-id é DENY MISSING_SANDBOX_ID. Firecracker real precisa de firecracker + jailer no PATH e env de kernel/rootfs (KYA_SANDBOX_KERNEL, KYA_SANDBOX_ROOTFS). Não enviamos esses binários. serve-mcp ainda expõe apenas evaluate / ingest / request_approval.

Showback de custo (somente observação)

kya orr run --usage ./usage.json (ou .kya/usage.json) adiciona uma seção de showback: tokens e USD estimados por agente e execução. Subagentes aninham sob parentRunId. Essa seção não é um medidor de cobrança nem um gate de política. Métricas hospedadas mostram o mesmo rollup quando o uso é ingerido com uma sessão. Eventos de rastro que carregam contagens de tokens relatadas pelo host (payloads de hook com um objeto usage, rastros importados) são preferidos em vez da estimativa estática por evento, e o relatório informa quantos eventos da janela tiveram uso real.

Enterprise (tier separado)

Pin, registro privado, densidade multi-tenant, operações de quadro ORR e suporte não são necessários para o caminho npx do dia 1 acima.

Desenvolver

pnpm install
pnpm test
pnpm build

Documentação

Estatísticas de uso anônimas (opt-in, desativado por padrão)

Na primeira vez que você executa kya start, kya init ou kya connect em um terminal, o KYA pergunta uma vez se deseja compartilhar estatísticas de uso anônimas ([y/N], o padrão é Não). Apenas um y ou yes explícito ativa isso. Nada é enviado em CI, em execuções não interativas, com --json, ou quando DO_NOT_TRACK=1 / KYA_TELEMETRY=0 está definido. kya hook em si nunca toca a rede; quando você opta por participar, ele inicia um helper destacado no máximo uma vez por dia que envia um ping, então instalações somente hook ainda contam como ativas.

kya telemetry show        # the exact payload, field by field
kya telemetry status      # on / off / not asked, and what overrides it
kya telemetry off --purge # turn off and erase what the server holds for this install

Detalhes completos, o payload, retenção e como auto-hospedar o endpoint: docs/telemetry.md.

OTLP (opcional)

Opt-in. Desativado por padrão.

CLI OSS: defina KYA_OTLP_ENDPOINT (ou OTEL_EXPORTER_OTLP_ENDPOINT) para exportar latência fina de evaluate (kya.client.evaluate.latency) com tags verdict e host apenas. Sem argumentos de ferramenta ou chaves de API.

Exportação de span de veredito: defina KYA_OTLP_EXPORT_ENDPOINT (ou "otlpExport": { "endpoint": ... } em .kya/config.json) para emitir cada veredito como um span GenAI OTLP/JSON (gen_ai.tool.name, kya.verdict, kya.reason_code, atributos de token quando conhecidos) para qualquer backend OTLP/HTTP. Processos de longa duração (gate MCP, gateway) exportam cada veredito; spawns de hook/wrap exportam DENY / REQUIRE_APPROVE via helper destacado notify-flush. HTTP em texto puro é aceito apenas para loopback, a menos que "insecure": true. Os resultados de flush acumulam em ~/.kya/otel-stats.json (rótulo do host do endpoint, spans enviados/falhos, último horário de exportação), renderizados como o painel Exportação OTel na aba Sistema do relatório.

Plano hospedado: medidores e timers Micrometer mais ricos quando KYA_OTLP_ENABLED=true.

Env completo, notas de Grafana/Datadog, lista de proibições e uma amostra de Collector: docs/otlp.md.