Configurar o Dicionário ESA usando Python e API REST AsyncOS

Introdução

Este documento descreve como usar o script Python para adicionar um novo dicionário a um Cisco Email Security Appliance (ESA) usando a API AsyncOS (REST API).

Pré-requisitos

Revise estes pré-requisitos:

• Linguagem de programação Python
• Módulo de requisições Python
• JSON
• Dispositivo de segurança de e-mail (ESA) da Cisco

Requisitos

Use o seguinte software e acesso para executar o script:

• Cisco Email Security Appliance (ESA) com AsyncOS 14.x ou posterior
• Python 3
• Módulo de requisições Python
• Credenciais de administrador do ESA com permissão para usar a API AsyncOS (REST API)
• Acesso à interface de gerenciamento do ESA através de HTTPS na porta 6443 (recomendado)

Componentes Utilizados

Estes componentes foram usados para concluir este laboratório:

1) Cisco ESA - 15.0.0-104

2) Editor de Texto Sublime

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Transporte e autenticação

• Transporte: Use HTTPS na porta 6443 para a API do AsyncOS quando disponível. Use HTTP/6080 somente em ambientes de laboratório ou que não sejam de produção.
• Autenticação: Este exemplo usa a autenticação básica HTTP. Forneça a autorização do cabeçalho: Básico <base64(username:password)>. Não cole credenciais reais no script.

Informações de Apoio

Para este documento:

Meta: Adicione um dicionário ao ESA usando um script Python e a API AsyncOS (REST API).

Resultado esperado: A API retorna uma resposta com êxito e o novo dicionário aparece na configuração do ESA.

Configurar

Ative o serviço AsyncOS API (REST API) na interface de gerenciamento ESA antes de executar o script.

1. Na Interface gráfica do usuário (GUI), navegue até a página network ou interface que contém as configurações de AsyncOS API HTTP e AsyncOS API HTTPS.
2. Habilite AsyncOS API HTTPS e verifique a porta 6443.
3. (Opcional) Habilite AsyncOS API HTTP e verifique a porta 6080 para uso em laboratório.
4. Click Save.

Imagem 1: Verifique se AsyncOS API HTTPS (porta 6443) está Habilitado na interface de Gerenciamento.

Configure o log de API para solucionar problemas de solicitações de API do AsyncOS.

1. Na Interface gráfica do usuário (GUI), navegue para Administração do sistema > Inscrições de registro.
2. Clique em Add Log Subscription.
3. Na lista suspensa Tipo de log, selecione Logs de API.
4. Insira os campos obrigatórios restantes, como o nome do log e o nome do arquivo, e clique em Enviar.

Selecione API Logsna lista suspensa Log Type e insira os demais detalhes obrigatórios.

Script

Use o método HTTP POST do módulo Python requests para criar um dicionário.

Use estes parâmetros para a solicitação POST:

Parâmetro	Local	Necessário	Notas
device_type	Cadeia de caracteres de consulta URL	Yes	Defina como ESA.
ignorecase	payload JSON	Yes	0 = diferencia maiúsculas de minúsculas, 1 = não diferencia maiúsculas de minúsculas.
palavras inteiras	payload JSON	Yes	0 = correspondência de substring, 1 = correspondência de palavra inteira.
codificação	payload JSON	Yes	Use utf-8 a menos que uma codificação diferente seja necessária.
palavras	payload JSON	Yes	Matriz de entradas. Use ["term"] para um termo literal. Para identificadores inteligentes, use um formato de tupla como ["*credit", 2, "prefix"], conforme suportado pelo ESA.
modo	Cadeia de caracteres de consulta URL	No	Necessário apenas para implantações em cluster/grupo (por exemplo, mode=cluster).

import base64
import requests

# ESA management IP address or FQDN
host = "<ESA_IP>"

# Dictionary name to create
dictionary_name = "<DICT_NAME>"

# AsyncOS API endpoint (HTTPS recommended)
url = f"https://{host}:6443/esa/api/v2.0/config/dictionaries/{dictionary_name}?device_type=esa"

payload = {
    "data": {
        "ignorecase": 0,
        "wholewords": 1,
        "words": [
            ["*credit", 2, "prefix"],
            ["*aba"],
            ["Example Term"]
        ],
        "encoding": "utf-8"
    }
}

# Basic authentication header
username = "<USERNAME>"
password = "<PASSWORD>"
creds = base64.b64encode(f"{username}:{password}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Basic {creds}"
}

response = requests.post(url, headers=headers, json=payload, timeout=30, verify=False)
print(f"Status code: {response.status_code}")
try:
    print(response.json())
except ValueError:
    print(response.text)

if response.status_code != 201:
    raise SystemExit("Dictionary creation failed.")

No script, o nome do dicionário () é incluído no caminho da URL de solicitação.

Inclua os parâmetros necessários (ignorecase, wholewords, words, e encoding) na carga JSON. Adicionar device_type à string de consulta da URL.

O parâmetro mode é necessário apenas quando os ESAs estão em um cluster ou grupo. Nesse caso, anexe mode=cluster à string de consulta da URL da mesma forma que device_type.

*credit e*abasão adicionados ao payload para ativar os identificadores inteligentes para números de cartão de crédito e números de roteamento ABA, como mostrado na captura de tela:

O termo Example Term é adicionado à carga como um item de dicionário para correspondência.

Verificar

Quando a solicitação POST é bem-sucedida, o log de API contém uma entrada semelhante a esta:

API log example
Thu October 5 12:58:19 2023 Info: 198.51.100.10 - - 05/Oct/2023 12:58:19 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 201 -

Resposta esperada:

{"data": {"message": "Added Successfully"}}

Se o dicionário já existir e a solicitação POST for executada novamente, o log de API conterá uma entrada semelhante a esta:

API log example
Thu October 5 13:00:31 2023 Info: 198.51.100.10 - - 05/Oct/2023 13:00:31 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 409 -

Resposta esperada:

{"error": {"message": "Dictionary already exists.", "code": "409", "explanation": "409 = Request conflict."}}

Informações Relacionadas

Use os seguintes recursos externos para obter informações adicionais de segundo plano (o procedimento neste documento é independente):

Adicionando dicionários usando REST API + Python 

Este documento inclui o método de autenticação necessário e o procedimento mínimo. Usar a autenticação Básica HTTP com a Autorização do cabeçalho: Básico <base64(username:password)> e prefira HTTPS na porta 6443.

API REST e Cisco ESA 

Além disso, o código Python usado neste procedimento pode ser extraído do Postman. Revise este tutorial em vídeo se necessário:

Postman - Como gerar um script Python 

Histórico de revisões

Revisão	Data de publicação	Comentários
1.0	26-Aug-2026	Versão inicial