Biblioteca Python para análise de segurança com LLM local, integrando análise binária com Ghidra, varredura de vulnerabilidades em C/C++ e integração com ferramentas MCP para engenharia reversa automatizada e geração de relatórios.
Biblioteca LLM da TrustedSec é uma biblioteca Python para interagir com LLMs locais que suportam uso de ferramentas. Ela permite executar grandes fluxos de trabalho tradicionalmente possíveis apenas com modelos de ponta, aproveitando endpoints de LLM locais e integração com MCP (Model Context Protocol).
# Clone or copy the repository
git clone https://github.com/trustedsec/ts_llmlib.git
cd ts_llmlib
# Install with pip
pip install -e .
Copie o diretório ts_llmlib/ para o seu projeto:
cp -rf ts_llmlib /path/to/your/project/
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'])
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'])
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)
| Ferramenta | Parâmetros | Descrição |
|---|---|---|
read_local_file | path: str | Lê o conteúdo de um arquivo local |
write_local_file | path: str, content: str | Escreve conteúdo em um arquivo local |
list_directory | path: str | Lista arquivos e diretórios em um caminho |
O MCP (Model Context Protocol) possibilita a integração com ferramentas e serviços externos. Quando servidores MCP estão configurados, o ts_llmlib irá:
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.
O ts_llmlib suporta endpoints no estilo RPC e SSE (Server-Sent Events):
http://localhost:3000/mcphttp://localhost:3000/sse (converte automaticamente para /mcp para chamadas RPC)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
)
Parâmetros:
system_prompt (str | None): Prompt de sistema personalizado. O padrão é um prompt de assistente mínimo.tool_list (list | None): Lista de definições de ferramentas personalizadas. Lista vazia usa as ferramentas integradas.mcp_servers (dict[str, str] | None): Dicionário mapeando nomes de servidores para URLs.llm_endpoint_url (str): URL do endpoint da API do LLM.model_name (str): Identificador do modelo para o endpoint do LLM.timeout (int): Timeout da requisição HTTP em segundos.max_runtime (int): Tempo máximo de execução para um prompt em segundos.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
Parâmetros:
user_prompt (str): A mensagem ou pergunta do usuário.conversation_history (list[dict] | None): Histórico de conversa opcional como uma lista de pares papel/conteúdo.disable_tools (list[str] | None): Lista de nomes de ferramentas para desabilitar nesta chamada.max_runtime (int | None): Substitui o tempo máximo de execução padrão para esta chamada específica.Retorna:
{
"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
}
O ToolRegistry gerencia todas as ferramentas disponíveis para a sessão de chat:
tool_listPara substituir os caminhos padrão, você pode definir as seguintes variáveis; elas são verificadas no 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
Analisa arquivos de código-fonte C/C++ em busca de vulnerabilidades de segurança:
ts_llmlib-cpp-analyze <source_folder> <output_folder>
Análise binária de engenharia reversa com integração 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>
Após concluir a execução, se não estiver usando --rename_only, você pode limpar a estrutura executando:
ts_llmlib-ghidra-cleanup <input_folder> <output_folder>
Gera relatórios de vulnerabilidades formatados a partir de arquivos de revisão JSON:
ts_llmlib-ghidra-report <review_folder>
Execute a interface de chat RedClippy baseada em Qt (observe que este exemplo requer pyside6):
ts_llmlib-redclippy
O ts_llmlib conecta-se a qualquer endpoint de API compatível com OpenAI. Servidores LLM locais comuns:
| Servidor | URL Padrão |
|---|---|
| Ollama | http://localhost:11434/v1/chat/completions |
| LM Studio | http://localhost:1234/v1/chat/completions |
| vLLM | http://localhost:8000/v1/chat/completions |
Duas configurações de timeout controlam a execução:
timeout): Tempo máximo para uma única requisição de APImax_runtime): Tempo total (wall-clock) permitido para o processamento do prompt (incluindo chamadas de ferramentas)Se qualquer um dos limites for excedido, a resposta conterá uma mensagem de erro.
Todos os erros são retornados no dicionário de resposta:
response = chat.run_prompt("Some prompt")
if response.get('error'):
print(f"Error: {response['error']}")
else:
print(response['content'])
max_runtimets_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
Licença BSD-3-Clause - Consulte o arquivo LICENSE.txt para obter detalhes.
Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)