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 CLI 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.

Il 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, Cygwin, Termux (Android) e 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 e il riutilizzo del contesto di sessione (_B4L_RT_CTX).
• 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 e cronologia
  Gestione del contesto conversazionale multi-turno con salvataggio dello storico in formato NDJSON. 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
  Caricamento dinamico dei moduli provider esterni (Gemini, Hugging Face, Mistral) con verifica di integrità crittografica dell'hash SHA-256 rispetto al manifest.

Requisiti di sistema

Pacchetti richiesti nel PATH:

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

Guida all'installazione

Installazione rapida ⏩

# 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

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

Installazione degli Extras opzionali:

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

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"

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