Connect LLMs to your shell with a secure Bash CLI wrapper

🛡️ Nota sulla Verifica del Core: La riga inferiore dei badge dedicati a sicurezza, isolamento dello sourcing, integrità delle sezioni e chaos test API viene eseguita rigorosamente ed esclusivamente sul file eseguibile core ./bash4llm per garantire Zero-Leakage, conformità all'Architettura Piatta e una resilienza superiore.

Bash4LLM⁺ 🇮🇹 🇬🇧

Wrapper in ambiente Bash per l'interfacciamento con API LLM compatibili con lo standard OpenAI. Integra un provider predefinito (Groq) ed è estendibile ad altri provider tramite moduli aggiuntivi (es. gemini, mistral, huggingface). Offre tre modalità di interazione: linea di comando diretta (CLI) e terminale interattivo a schermo intero (TUI REPL) - entrambi 100% nativi in Bash -, oltre a un'interfaccia grafica su browser (WebApp GUI) fornita come estensione opzionale (richiede Python 3.10+).

Il Core del progetto è strutturato come uno script Bash autonomo senza dipendenze esterne oltre ai comandi POSIX standard e alle utilità di base della shell.

Compatibilità nativa: Linux, macOS, WSL e Cygwin (Windows), Termux (Android), BSD.

Caratteristiche tecniche

• Gestione dinamica dei modelli
  Interrogazione degli endpoint degli utenti (GET /v1/models) per l'aggiornamento dell'elenco dei modelli supportati, senza identificatori hardcoded nello script principale.
• Isolamento a livello di filesystem
  I file temporanei sono gestiti all'interno di directory di processo dedicate (RUN_TMPDIR) con permessi restrittivi 0700 (umask 077). Non vengono usate directory condivise come /tmp.
• Cifratura delle chiavi API (--vault)
  Integrazione opzionale tramite OpenSSL per la cifratura locale delle chiavi API. Utilizza l'algoritmo AES-256-CBC con derivazione della chiave tramite PBKDF2 (100.000 iterazioni) e Master Password. Supporta una chiave di ripristino offline, il riutilizzo del contesto di sessione (_B4L_RT_CTX) e la policy di obbligatorietà BASH4LLM_REQUIRE_VAULT.
• Supporto Termux / Android
  Rilevamento dell'ambiente Android Termux con adattamento dei meccanismi di locking: dove flock presenta limitazioni di sistema, la gestione della concorrenza è reindirizzata su atomic directory lock (mkdir).
• Integrazione dati di stato (ui_state)
  Scrittura atomica di file JSON contenenti i metadati operativi del runtime nella cartella ui_state, per l'integrazione con pannelli di controllo esterni o script di monitoraggio.
• Gestione sessioni, cronologia e protezione PII
  Gestione del contesto conversazionale multi-turno con salvataggio dello storico in formato NDJSON e anonimizzazione crittografica degli ID di thread (anonymize_thread_id) per prevenire fughe di dati personali. Con il modulo opzionale session-engine.sh vengono abilitati il tracciamento dei token, la rotazione/compressione dei segmenti di storico e il caching locale con TTL.
• Moduli estendibili e firma crittografica
  Caricamento dinamico dei moduli provider esterni (builtin, vendor, local) in copia di staging anti-TOCTOU, con verifica di integrità dell'hash SHA-256 e convalida della firma crittografica Ed25519 del manifesto (manifest.sha256.sig).
• Validazione deterministica
  Supporto nativo per la validazione sintattica delle risposte (--validate-sml per SML v2.0, --validate-regex), sanitizzazione ANSI zero-eval (--sanitize), diagnostica JSON strutturata (--json-diagnostics), guardie di immutabilità delle funzioni (readonly -f) e rate limiting locale a finestra scorrevole (30s).
• Interfaccia WebApp GUI locale (--gui, --webapp):
  WebApp responsive basata su stack Python/FastAPI e frontend Vanilla JS/CSS (Zero CDN). Architettura Thin Adapter / Domain-Stateless con streaming dei token via SSE, binding esclusivo su loopback (127.0.0.1), autenticazione tramite One-Time URL, cookie HttpOnly / SameSite=Strict e protezione Anti-CSRF in tempo costante.

📘 Documentazione Architetturale: Per l'analisi dettagliata delle macro-sezioni, dei meccanismi di isolamento e del layout di memoria, consulta la Specifica Tecnica del Sistema Bash4LLM⁺.

Requisiti di sistema

Pacchetti richiesti nel PATH:

• bash (versione 4.0 o superiore)
• coreutils (stat, chmod, mkdir, mv, rm, cp, mktemp, base64, ecc.)
• findutils
• util-linux
• awk
• curl
• jq

Requisiti opzionali per la WebApp GUI (--gui, --webapp):

• Python (versione 3.10 o superiore)
• Pacchetti Python: fastapi, uvicorn, pydantic

  pip install --user fastapi "uvicorn[standard]" pydantic

(L'uso in modalità CLI e TUI rimane al 100% nativo Bash/POSIX senza dipendenze Python).

Guida all'installazione

Installazione rapida ⏩

Con Installazione degli Extras opzionali:

# 1. Clona il repository
git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm  

# 2. Copia l'eseguibile nella cartella di lavoro
mkdir -p bash4llm
cp repo-bash4llm/bin/bash4llm bash4llm/
chmod +x bash4llm/bash4llm

# 3. Inizializzazione e aggiornamento modelli
cd bash4llm 
./bash4llm --refresh-models

# 4. Installazione opzionale degli Extras (provider aggiuntivi, TUI, moduli)
./bash4llm --install-extras ../repo-bash4llm/extras/

Al primo avvio senza variabile d'ambiente impostata, lo script chiederà l'inserimento interattivo della chiave API (input nascosto a schermo).

Istruzioni dettagliate sono disponibili in INSTALL.

Esempi d'uso

Prompt da linea di comando:

./bash4llm "Fornisci una spiegazione del protocollo SSH."

Input da standard input (pipe):

cat codice.sh | ./bash4llm "Analizza questo script"

Selezione di un modello specifico:

./bash4llm -m llama-3.3-70b-versatile "Spiega il paradosso di Fermi."

Esecuzione di prova senza chiamate di rete (Dry-Run):

./bash4llm --dry-run "Test di generazione payload"

Uso di un provider secondario:

./bash4llm --provider gemini "Traduci il testo in inglese"

Moduli Aggiuntivi (Extras)

Mentre il Core ./bash4llm è un eseguibile completamente autonomo e privo di dipendenze esterne (compatibile POSIX/Bash 4.0+), la cartella extras/ estende il runtime attraverso moduli opzionali con dipendenze software mirate (soft dependencies). Tutti i moduli aderiscono al principio di Zero-Eval, all'isolamento su filesystem (RUN_TMPDIR, no /tmp) e al principio del minimo privilegio (0700 per le directory, 0600 per i file e bit di esecuzione limitato ai 4 entrypoint autorizzati).

• Interfacce Utente Avanzate:
  • TUI REPL (extras/chat/tui-repl.sh): Interfaccia interattiva a schermo intero nativa al 100% in Bash con supporto multilingua (--chat, --tui).
  • WebApp GUI (extras/gui-py/): Interfaccia grafica su browser in Python 3.10+ (FastAPI + Uvicorn) con streaming SSE e protezione CSRF (--gui, --webapp).
• Provider LLM Estesi (extras/providers/): Driver plug-and-play caricati in subshell isolata per backend OpenAI-compatibili come gemini, mistral e huggingface (--provider <nome>).
• Sicurezza, Cifratura e Sanitizzazione (extras/security/):
  • OpenSSL Key Vault (openssl-helper.sh): Cifratura locale delle chiavi API con AES-256-CBC, PBKDF2 (100k iterazioni), Master Password e Recovery Key offline a 32 char (--vault).
  • Output Sanitizer (output-sanitizer.sh): Motore Zero-Eval per il filtraggio deterministico di sequenze ANSI e caratteri non stampabili (--sanitize).
• Session Engine Avanzato (extras/session/session-engine.sh): Gestione di contesti estesi con segmentazione NDJSON su soglia (1MB), rotazione automatica (.gz), deduplicazione, byte-budgeting e caching in memoria con TTL.
• Hooks e Validazione Semantica (extras/hooks/sml-gate.sh): Gate di conformità per forzare la struttura Structured Metadata Layout (SML v2.0) sulle risposte (--validate-sml).
• Autocompletamento Shell (extras/docs/bash4llm-completion.sh): Modulo di completamento contestuale nativo per Bash 4.0+ per opzioni CLI, modelli e codici d'errore.
• Master Test Suite (extras/test/run-all-tests.sh): Framework di collaudo a 6 livelli (Sanity, Compatibility, Regression, Hardening, Concurrency, Stress) integrato con la suite scintilla-t3.sh per la verifica del refactoring di sicurezza (--test, --run-all-tests).

Integrità della Supply Chain & Manifest

Il caricamento dei moduli segue il modello Manifest-Authorized: ogni componente deve corrispondere al checksum SHA-256 registrato in extras/manifest.sha256 (verificato contro manomissioni con codice d'uscita 17 / BASH4LLM_ERR_SEC). Per registrare modifiche o moduli aggiunti in locale:

# Aggiornamento locale rapido del manifest SHA-256
./extras/security/generate-manifest.sh --no-sign-if-missing-key

📖 Per la documentazione tecnica completa di ogni componente, consulta la Guida agli Extras.

Sicurezza e permessi del filesystem 🚨

Per proteggere lo script bash4llm da modifiche non autorizzate in ambienti condivisi, è possibile impostare i permessi di sola lettura/esecuzione appropriati per il sistema operativo in uso:

• Linux (GNU/Linux):

  sudo chown root:root /path/to/bash4llm && sudo chmod 755 /path/to/bash4llm
  sudo chattr +i /path/to/bash4llm
  

• macOS / BSD:

  sudo chown root:wheel /path/to/bash4llm && sudo chmod 755 /path/to/bash4llm
  sudo chflags schg /path/to/bash4llm
  

• Termux (Android):

  chmod 500 ~/bash4llm
  

• WSL / Cygwin:

  setfacl -b /path/to/bash4llm 2>/dev/null
  chmod 755 /path/to/bash4llm
  

Per informazioni dettagliate sulle politiche di sicurezza, consultare SECURITY.md.

Verifiche di sicurezza e test automatizzati 🛡️

L'eseguibile ./bash4llm integra verifiche continue sul codice e sull'ambiente di esecuzione:

1. Verifica marcatura sezioni: Controllo della struttura ad ancoraggi e delimitatori di sezione del file principale.
2. Isolamento ambiente di sourcing: Test della funzione _cleanup_sourced_env per verificare che l'inclusione via source non lasci funzioni residue nella shell chiamante.
3. Verifica secret leak in argv: Verifica della mancata presenza di chiavi API e token Bearer nella tabella dei processi del sistema operativo durante l'esecuzione di curl. Controllo permessi POSIX 0700 e 0600.
4. Test di resilienza API: Simulazione di risposte di errore HTTP, rate limit e casi limite tramite server mock.
5. Integrità del manifest extras: Controllo degli hash SHA-256 e della firma crittografica Ed25519 (manifest.sha256.sig) dei moduli opzionali rispetto al file extras/manifest.sha256.

Riferimento comandi e opzioni

Modelli e provider

Input

Gestione thread e contesto

Parametri di generazione

Output e salvataggio

Modalità operative

Configurazione e diagnostica

Struttura dello stato UI (ui_state)

Il runtime aggiorna in modo atomico i metadati di stato nella directory:

bash4llm.d/config/ui_state/

File generati:

• threads/<thread_id>.json: Stato e metadati del thread attivo.
• threads/index.json: Indice dei thread salvati.
• last_api.json: Metadati dell'ultima chiamata API (stato HTTP, ID richiesta, tempo).
• last_history.json: Informazioni sull'ultimo file scritto in cronologia.
• provider_capabilities.json: Funzionalità supportate dal provider attivo.

Codici di uscita (Exit Codes)

Licenza e Contatti

• Licenza: GNU General Public License v3.0 (LICENSE)
• Autore: Cristian Evangelisti
• Email: opensource@cevangel.anonaddy.me
• Repository: GitHub kamaludu/bash4llm

Uso di strumenti di Intelligenza Artificiale nello sviluppo

Bash4LLM è un'opera sviluppata dall'autore con un uso esteso di strumenti di Intelligenza Artificiale generativa (LLM) per progettazione, implementazione, analisi, debugging, revisione e documentazione.

Gli LLM sono stati utilizzati come strumenti di sviluppo, non come generatori autonomi del progetto. L'autore ha definito l'architettura, i requisiti e le scelte progettuali, orchestrando il lavoro attraverso modelli e sessioni differenti e utilizzando gli stessi LLM anche per esaminare, mettere in discussione e criticare il lavoro prodotto da altri modelli.

Il codice e la documentazione sono quindi il risultato di un processo iterativo e supervisionato, nel quale le proposte generate dagli LLM sono state valutate, confrontate, modificate o scartate dall'autore. Le decisioni finali e il risultato complessivo del progetto sono dell'autore.

L'uso degli LLM offre significativi vantaggi in termini di produttività, analisi e revisione, ma introduce anche rischi: nessun processo di verifica può garantire che ogni errore o omissione venga individuato. Questa informativa intende rendere trasparente sia l'ampiezza dell'utilizzo degli LLM sia il loro ruolo effettivo nel processo di sviluppo.