Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Segurança na Chamada de Funções

Aula 11 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Nunca Execute Cegamente
  2. Valide Antes de Executar
  3. Quando o Argumento Se Torna uma Carga Útil
  4. Restrinja o Campo de Possibilidades
  5. Nem Todas as Funções Têm o Mesmo Peso
  6. Conter Abusos e Execuções Descontroladas
  7. O Que Retorna ao Modelo
  8. Pontos-chave

Nunca Execute Cegamente

A chamada de funções confere ao modelo a capacidade de solicitar a execução de funções no seu sistema. Isto é poderoso, mas cria também um vetor de ataque potencial. Um utilizador mal-intencionado não pode executar o seu código diretamente; no entanto, pode escrever qualquer coisa no campo de chat, influenciando assim os argumentos que o modelo produz. Precisa de derrubar uma suposição confortável: os argumentos de tool_call não são dados internos da sua aplicação. São dados do utilizador que passaram por um modelo de linguagem. O seu código deve ser a última linha de defesa.

Valide Antes de Executar

O modelo gera argumentos JSON onde garante a forma gramatical, nunca a legitimidade comercial. Um transaction_id pode ser sintaticamente uma cadeia de caracteres, mas conter qualquer coisa. A disciplina, portanto, consiste em validar cada argumento antes de fazer qualquer coisa com ele e estruturar a função em três etapas distintas: verificar o formato, verificar a existência e, só depois, executar.

import re

def validate_transaction_id(transaction_id: str) -> bool:
    """Valida o formato de um identificador de transação."""
    # Formato esperado: T seguido de 4 dígitos
    return bool(re.match(r"^T\d{4}$", transaction_id))


def retrieve_payment_status_safe(df, transaction_id: str) -> str:
    """Versão segura com validação."""
    # Passo 1: Validar formato
    if not validate_transaction_id(transaction_id):
        return json.dumps({
            "error": "invalid_format",
            "message": "O ID deve estar no formato Txxxx (ex.: T1001)"
        })

    # Passo 2: Verificar existência
    if transaction_id not in df["transaction_id"].values:
        return json.dumps({
            "error": "not_found",
            "message": f"Transação {transaction_id} não encontrada"
        })

    # Passo 3: Executar
    status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
    return json.dumps({"status": status})

A expressão regular ^T\d{4}$ faz todo o trabalho defensivo aqui: ancorada em ambos os lados, rejeita qualquer cadeia que contenha sequer um caráter extra. Isto leva diretamente à razão desta ancoragem.

Quando o Argumento Se Torna uma Carga Útil

Considere este pedido, que parece perfeitamente inocente:

User: "Find the payment with ID: T1001; DROP TABLE payments"

O modelo, a fazer conscientemente o seu trabalho de extração, pode gerar {"transaction_id": "T1001; DROP TABLE payments"}. Não fez nada de errado: recebeu um identificador e transmitiu-o. Se a sua função inserir este argumento numa consulta SQL via concatenação, acabou de perder a sua tabela. O problema não é novo — é a clássica injeção SQL —, mas a chamada de funções adiciona um elo que cria uma falsa impressão de filtragem.

As três versões seguintes mostram a progressão: o que nunca deve escrever, o mínimo aceitável e a prática a adotar.

# NUNCA faça isto — injeção SQL direta
def bad_query(transaction_id):
    cursor.execute(f"SELECT * FROM payments WHERE id = ' {transaction_id}'")

# SEMPRE faça isto — consultas parametrizadas
def safe_query(transaction_id):
    cursor.execute("SELECT * FROM payments WHERE id = %s", (transaction_id,))

# AINDA MELHOR — validação + consulta parametrizada
def best_query(transaction_id):
    if not validate_transaction_id(transaction_id):
        raise ValueError("Formato de ID inválido")
    cursor.execute("SELECT * FROM payments WHERE id = %s", (transaction_id,))

A consulta parametrizada é suficiente para neutralizar a injeção, uma vez que o controlador trata o argumento como um valor e não como SQL. A validação a montante adiciona uma segunda barreira e, incidentalmente, fornece uma mensagem de erro muito mais clara do que a base de dados forneceria.

Restrinja o Campo de Possibilidades

A segunda linha de defesa consiste em reduzir o que o modelo pode solicitar. Uma lista de permissões explícita, separada do seu dicionário de despacho, estabelece preto no branco quais as funções autorizadas neste contexto. A separação é importante: ALLOWED_FUNCTIONS expressa uma decisão de segurança, enquanto available_functions reflete um estado de implementação. Confundir os dois equivale a autorizar uma função simplesmente porque a codificou.

# Definir explicitamente as funções permitidas
ALLOWED_FUNCTIONS = {
    "retrieve_payment_status",
    "retrieve_payment_date",
    "search_transactions"
}

def execute_tool_call_safe(tool_call, available_functions):
    """Execução com verificação da lista de permissões."""
    function_name = tool_call.function.name

    # Verificar lista de permissões
    if function_name not in ALLOWED_FUNCTIONS:
        return json.dumps({
            "error": "forbidden",
            "message": f"A função {function_name} não está autorizada."
        })

    if function_name not in available_functions:
        return json.dumps({
            "error": "not_implemented",
            "message": f"A função {function_name} não está implementada."
        })

    # Executar
    function_params = json.loads(tool_call.function.arguments)
    return available_functions[function_name](**function_params)

Nem Todas as Funções Têm o Mesmo Peso

Ler o estado de um pagamento e purgar registos antigos obviamente não comportam o mesmo risco. Classificar as suas funções por nível — apenas leitura, escrita, destrutivo — permite conceder a cada sessão ou utilizador o escopo apropriado. Um assistente público de rastreio de encomendas funcionará em modo read; uma ferramenta de back-office autorizará escritas. Quanto às ações destrutivas, a resposta certa não é proibi-las, mas escaloná-las: a função devolve confirmation_required, o modelo explica ao utilizador o que está prestes a acontecer e um humano toma a decisão final.

# Níveis de risco
READ_ONLY = {"retrieve_payment_status", "retrieve_payment_date", "search_transactions"}
WRITE = {"update_payment_status", "create_refund"}
DESTRUCTIVE = {"delete_transaction", "purge_old_records"}

def execute_with_permissions(tool_call, available_functions, permission_level="read"):
    """Executa com verificação do nível de permissão."""
    function_name = tool_call.function.name

    if permission_level == "read" and function_name not in READ_ONLY:
        return json.dumps({
            "error": "permission_denied",
            "message": f"Apenas funções de leitura estão autorizadas. "
                       f"{function_name} requer o nível 'write'."
        })

    if function_name in DESTRUCTIVE:
        return json.dumps({
            "error": "confirmation_required",
            "message": f"A ação {function_name} é destrutiva e "
                       f"requer confirmação manual."
        })

    function_params = json.loads(tool_call.function.arguments)
    return available_functions[function_name](**function_params)

Conter Abusos e Execuções Descontroladas

Um ciclo de conversa mal gerido pode chamar a mesma função dezenas de vezes em poucos segundos, seja por malícia ou por um simples erro de encadeamento. Um contador deslizante de sessenta segundos por função custa algumas linhas de código e impede a saturação de uma API de terceiros faturada por chamada.

from collections import defaultdict
import time

class FunctionRateLimiter:
    def __init__(self, max_calls_per_minute=10):
        self.max_calls = max_calls_per_minute
        self.call_history = defaultdict(list)

    def can_call(self, function_name: str) -> bool:
        now = time.time()
        # Limpar chamadas com mais de um minuto
        self.call_history[function_name] = [
            t for t in self.call_history[function_name]
            if now - t < 60
        ]
        return len(self.call_history[function_name]) < self.max_calls

    def record_call(self, function_name: str):
        self.call_history[function_name].append(time.time())

rate_limiter = FunctionRateLimiter(max_calls_per_minute=10)

O Que Retorna ao Modelo

O último ponto cego é frequentemente o mais dispendioso. Uma função que devolve uma linha completa da base de dados pode incluir um hash de palavra-passe, uma chave de API ou um número de cartão. No entanto, tudo o que colocar numa mensagem tool entra no contexto do modelo, o que significa que poderia potencialmente aparecer na sua resposta no ecrã, nos seus registos e no lado do seu fornecedor. Mascarar campos sensíveis antes do envio — recursivamente, para cobrir objetos aninhados — é a precaução que o salvará de um incidente de fuga de dados.

def sanitize_result(result: dict) -> dict:
    """Remove campos sensíveis antes de retornar ao modelo."""
    sensitive_keys = {"password", "api_key", "secret", "token", "ssn", "credit_card"}

    sanitized = {}
    for key, value in result.items():
        if key.lower() in sensitive_keys:
            sanitized[key] = "[MASKED]"
        elif isinstance(value, dict):
            sanitized[key] = sanitize_result(value)
        else:
            sanitized[key] = value

    return sanitized

Pontos-chave

  • Valide sempre os argumentos antes de executar uma função — formato, tipo, valores permitidos
  • Utilize consultas parametrizadas para prevenir injeção SQL
  • Implemente uma lista de permissões de funções autorizadas
  • Classifique as funções por nível de risco (leitura, escrita, destrutivo)
  • Adicione limitação de taxa para prevenir abusos
  • Limpe os resultados para evitar expor dados sensíveis ao modelo