ts_llmlib - Libreria LLM di TrustedSec

TrustedSec LLM Library è una libreria Python per interagire con LLM locali che supportano l'uso di strumenti. Consente di eseguire grandi flussi di lavoro tradizionalmente possibili solo con modelli all'avanguardia sfruttando endpoint LLM locali e l'integrazione MCP (Model Context Protocol).

Caratteristiche

• Supporto LLM locale: Connettersi a qualsiasi endpoint API compatibile con OpenAI o usare server LLM locali
• Integrazione MCP: Supporto completo del Model Context Protocol per i protocolli RPC e SSE
• Registro degli strumenti: Strumenti integrati per operazioni sui file con estensibilità per strumenti personalizzati
• Cronologia della conversazione: Mantiene il contesto della chat su più turni
• Limiti di tempo: Timeout di esecuzione configurabili per prevenire operazioni incontrollate
• Python puro: Nessuna dipendenza esterna oltre alla libreria standard

Installazione

Come pacchetto Python

# Clone or copy the repository
git clone https://github.com/trustedsec/ts_llmlib.git
cd ts_llmlib

# Install with pip
pip install -e .

Installazione manuale

Copia la directory ts_llmlib/ nel tuo progetto:

cp -rf ts_llmlib /path/to/your/project/

Avvio rapido

Utilizzo di base

from ts_llmlib import ChatSession

# Initialize with defaults (connects to http://localhost:1234/v1/chat/completions)
chat = ChatSession()

# Run a prompt
response = chat.run_prompt("What files are in the current directory?")
print(response['content'])

Con configurazione personalizzata

from ts_llmlib import ChatSession

# Configure with custom settings
chat = ChatSession(
    system_prompt="You are a helpful assistant that uses file tools.",
    tool_list=[],  # Empty = use default file tools
    mcp_servers={
        "default": "http://localhost:3000/mcp"
    },
    llm_endpoint_url="http://localhost:1234/v1/chat/completions",
    model_name="qwen3-coder-next",
    timeout=60,
    max_runtime=300
)

response = chat.run_prompt("Write 'hello' to /tmp/greeting.txt")
print(response['content'])

Con cronologia della conversazione

from ts_llmlib import ChatSession

chat = ChatSession()

history = [
    {"role": "user", "content": "What is 2+2?"},
    {"role": "assistant", "content": "The answer is 4."}
]

response = chat.run_prompt("Can you write that to a file?", history=history)

Strumenti integrati

Integrazione MCP

MCP (Model Context Protocol) consente l'integrazione con strumenti e servizi esterni. Quando i server MCP sono configurati, ts_llmlib:

1. Inizializza le connessioni a ciascun server
2. Recupera gli strumenti disponibili dal server
3. Li unisce agli strumenti integrati (gli strumenti MCP hanno precedenza per i nomi corrispondenti)
4. Esegue le chiamate agli strumenti utilizzando il server appropriato

Esempio con server MCP Ghidra

from ts_llmlib import ChatSession

chat = ChatSession(
    mcp_servers={
        "ghidraSvr": "http://localhost:8081/sse"
    },
    llm_endpoint_url="http://localhost:1234/v1/chat/completions",
    model_name="qwen3-coder-next"
)

# The chat session will automatically fetch and integrate Ghidra tools
# such as list_methods, decompile_function, get_xrefs_to, etc.

Endpoint dei server MCP

ts_llmlib supporta sia endpoint in stile RPC che SSE (Server-Sent Events):

• RPC: http://localhost:3000/mcp
• SSE: http://localhost:3000/sse (converte automaticamente in /mcp per le chiamate RPC)

Riferimento API

Classe ChatSession

ChatSession(
    system_prompt: str | None = None,
    tool_list: list | None = None,
    mcp_servers: dict[str, str] | None = None,
    llm_endpoint_url: str = "http://localhost:1234/v1/chat/completions",
    model_name: str = "default",
    timeout: int = 60,
    max_runtime: int = 300
)

Parametri:

• system_prompt (str | None): Prompt di sistema personalizzato. Di default utilizza un prompt minimo per l'assistente.
• tool_list (list | None): Elenco di definizioni di strumenti personalizzati. Un elenco vuoto usa gli strumenti integrati.
• mcp_servers (dict[str, str] | None): Dizionario che mappa i nomi dei server agli URL.
• llm_endpoint_url (str): URL dell'endpoint API LLM.
• model_name (str): Identificativo del modello per l'endpoint LLM.
• timeout (int): Timeout della richiesta HTTP in secondi.
• max_runtime (int): Tempo massimo di esecuzione per un prompt in secondi.

Metodo run_prompt

response = chat.run_prompt(
    user_prompt: str,
    conversation_history: list[dict] | None = None,
    disable_tools: list[str] | None = None,
    max_runtime: int | None = None
) -> dict

Parametri:

• user_prompt (str): Il messaggio o la domanda dell'utente.
• conversation_history (list[dict] | None): Cronologia della conversazione opzionale come elenco di coppie ruolo/contenuto.
• disable_tools (list[str] | None): Elenco di nomi di strumenti da disabilitare per questa chiamata.
• max_runtime (int | None): Sostituisce il tempo massimo di esecuzione predefinito per questa specifica chiamata.

Restituisce:

{
    "content": str,           # LLM response text
    "tool_calls": list,       # List of tool calls made (if any)
    "usage": dict | None,     # Token usage if available from the LLM
    "error": str | None       # Error message if failed
}

Registro degli strumenti

ToolRegistry gestisce tutti gli strumenti disponibili per la sessione di chat:

• Strumenti integrati: Operazioni sui file (lettura/scrittura/elenco)
• Strumenti MCP: Strumenti recuperati dai server MCP
• Strumenti personalizzati: Strumenti definiti dall'utente tramite il parametro tool_list

Esempi

Per sovrascrivere i percorsi predefiniti puoi impostare le seguenti variabili, che vengono controllate in ChatSession.

TS_LLM_MODEL=qwen3-coder-next TS_LLM_ENDPOINT=http://HOSTNAME:1234/v1/chat/completions
# Example usage
export TS_LLM_MODEL=qwen3-coder-next
export TS_LLM_ENDPOINT=http://HOSTNAME:1234/v1/chat/completions
ts_llmlib-redclippy
# OR
TS_LLM_MODEL=qwen3-coder-next TS_LLM_ENDPOINT=http://HOSTNAME:1234/v1/chat/completions ts_llmlib-redclippy

Analisi del codice sorgente C/C++

Analizza i file sorgente C/C++ alla ricerca di vulnerabilità di sicurezza:

ts_llmlib-cpp-analyze <source_folder> <output_folder>

Analisi binaria con Ghidra

Analisi binaria di reverse engineering con integrazione Ghidra:

# Basic analysis
ts_llmlib-ghidra-analyze <output_folder>

# Rename-only mode (first pass)
ts_llmlib-ghidra-analyze --rename_only <output_folder>

# Process only previously unnamed functions
ts_llmlib-ghidra-analyze --process_unnamed_only <output_folder>

# Grouped analysis for call relationship grouping
ts_llmlib-ghidra-analyze --grouped <output_folder>

Una volta terminata l'esecuzione, se non stai usando --rename_only, puoi pulire la struttura eseguendo:

ts_llmlib-ghidra-cleanup <input_folder> <output_folder>

Generazione di report di vulnerabilità

Genera report di vulnerabilità formattati da file di revisione JSON:

ts_llmlib-ghidra-report <review_folder>

Applicazione chat GUI

Esegui l'interfaccia chat RedClippy basata su Qt (nota: questo esempio richiede pyside6):

ts_llmlib-redclippy

Opzioni di configurazione

Configurazione dell'endpoint LLM

ts_llmlib si connette a qualsiasi endpoint API compatibile con OpenAI. Server LLM locali comuni:

Limiti di tempo

Due impostazioni di timeout controllano l'esecuzione:

• Timeout HTTP (timeout): Tempo massimo per una singola richiesta API
• Tempo massimo di esecuzione (max_runtime): Tempo totale consentito per l'elaborazione del prompt (incluse le chiamate agli strumenti)

Se uno dei due limiti viene superato, la risposta conterrà un messaggio di errore.

Gestione degli errori

Tutti gli errori vengono restituiti nel dizionario di risposta:

response = chat.run_prompt("Some prompt")

if response.get('error'):
    print(f"Error: {response['error']}")
else:
    print(response['content'])

Errori comuni

• Errori HTTP: Connessione rifiutata, timeout, chiave API non valida
• Errori di parsing JSON: Argomenti degli strumenti non validi o risposte malformate
• Errori di esecuzione degli strumenti: File mancanti, problemi di permessi, parametri non validi
• Errori di timeout: Operazione che supera il limite max_runtime

Struttura del progetto

ts_llmlib/
├── __init__.py          # Package initialization, exports ChatSession
├── client.py            # LLMClient for HTTP requests to LLM endpoints
├── chat.py              # ChatSession class (main API)
├── mcp.py               # MCPClient for Model Context Protocol integration
├── tools.py             # ToolRegistry for tool management
├── HOW_TO_TS_LLMLIB.md  # Original documentation
└── examples/            # Example scripts
    ├── c_cpp_analyze.py     # C/C++ vulnerability analysis script
    ├── redclippy.py         # Qt-based GUI chat application
    ├── ghidra_analyze.py    # Ghidra binary analysis with MCP integration
    ├── ghidra_vuln_report.py  # Vulnerability report generator
    ├── ghidra_cleanup.py    # Output file reorganization utility
    └── example_ts_llmlib.py # Example script demonstrating library usage

pyproject.toml         # Modern Python package configuration (scripts defined here)
LICENSE.txt            # BSD-3-Clause License
README.md              # This file

Licenza

Licenza BSD-3-Clause - Consulta il file LICENSE.txt per i dettagli.

Contributi

I contributi sono benvenuti! Non esitare a inviare una Pull Request.

1. Fai un fork del repository
2. Crea il tuo branch per la funzionalità (git checkout -b feature/AmazingFeature)
3. Esegui il commit delle tue modifiche (git commit -m 'Add some AmazingFeature')
4. Esegui il push del branch (git push origin feature/AmazingFeature)
5. Apri una Pull Request