ESA Dictionary configureren met Python en AsyncOS REST API

Inleiding

In dit document wordt beschreven hoe u het Python-script kunt gebruiken om een nieuw woordenboek toe te voegen aan een Cisco Email Security Appliance (ESA) met behulp van de AsyncOS API (REST API).

Voorwaarden

Bekijk deze voorwaarden:

• Python programmeertaal
• Python aanvragen module
• JSON
• Cisco Email Security Appliance (ESA)

Vereisten

Gebruik de volgende software en toegang om het script uit te voeren:

• Cisco Email Security Appliance (ESA) met AsyncOS 14.x of hoger
• Python 3
• Python aanvragen module
• ESA-beheerdersreferenties met toestemming om de AsyncOS API (REST API) te gebruiken
• Toegang tot de ESA-beheerinterface via HTTPS op poort 6443 (aanbevolen)

Gebruikte componenten

Deze componenten werden gebruikt om dit lab te voltooien:

1) Cisco ESA - 15.0.0-104

2) Sublieme teksteditor

De informatie in dit document is gebaseerd op de apparaten in een specifieke laboratoriumomgeving. Alle apparaten die in dit document worden beschreven, hadden een opgeschoonde (standaard)configuratie. Als uw netwerk live is, moet u zorgen dat u de potentiële impact van elke opdracht begrijpt.

Vervoer en authenticatie

• Transport: gebruik HTTPS op poort 6443 voor de AsyncOS API wanneer deze beschikbaar is. Gebruik HTTP/6080 alleen in niet-productie- of laboratoriumomgevingen.
• Verificatie: in dit voorbeeld wordt HTTP Basic-verificatie gebruikt. Geef de header Authorisation: Basic <base64(gebruikersnaam: wachtwoord)>. Plak geen echte referenties in het script.

Achtergrondinformatie

Voor dit document:

Doel: Voeg een woordenboek toe aan de ESA met behulp van een Python-script en de AsyncOS API (REST API).

Verwachte uitkomst: De API geeft een succesvolle respons en het nieuwe woordenboek verschijnt in de ESA-configuratie.

Configureren

Schakel de AsyncOS API (REST API)-service in op de ESA-beheerinterface voordat u het script uitvoert.

1. Navigeer in de grafische gebruikersinterface (GUI) naar de pagina van het netwerk of de interface die de AsyncOS API HTTP en AsyncOS API HTTPSą-instellingen bevat.
2. Schakel AsyncOS API HTTPS in en controleer poort 6443.
3. (Optioneel) Schakel AsyncOS API HTTP in en controleer poort 6080 voor laboratoriumgebruik.
4. Klik op Save (Opslaan).

Afbeelding 1: Controleer of AsyncOS API HTTPS (poort 6443) is ingeschakeld op de beheerinterface.

API-logboekregistratie configureren om problemen met AsyncOS API-verzoeken op te lossen.

1. Ga in de grafische gebruikersinterface (GUI) naar Systeembeheer > Abonnementen loggen.
2. Klik op Logabonnement toevoegen.
3. Selecteer in de vervolgkeuzelijst Logtype de optie API-logboeken.
4. Voer de resterende vereiste velden in, zoals de lognaam en bestandsnaam, en klik vervolgens op Indienen.

Selecteer API Logsin de Log Type en voer de resterende vereiste gegevens in.

script

Gebruik de HTTP POST methode van de Python requests module om een woordenboek te maken.

Gebruik deze parameters voor het POST-verzoek:

Parameter	Location (Locatie)	verplicht	Opmerkingen
device_type	URL-querytekenreeks	Ja	Instellen op esa.
onwetendheid	JSON-payload	Ja	0 = hoofdlettergevoelig, 1 = hoofdletterongevoelig.
hele woorden	JSON-payload	Ja	0 = subtekenreeksovereenkomst, 1 = volwoordovereenkomst.
codering	JSON-payload	Ja	Gebruik utf-8 tenzij een andere codering vereist is.
woorden	JSON-payload	Ja	Een scala aan inzendingen. Gebruik ["term"] voor een letterlijke term. Gebruik voor slimme id's een tuple-indeling zoals ["*credit", 2, "prefix"] zoals ondersteund door de ESA.
modus	URL-querytekenreeks	Nee	Alleen vereist voor geclusterde/groepsimplementaties (bijvoorbeeld modus=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.")

In het script is de naam van het woordenboek () opgenomen in het URL-aanvraagpad.

Neem de vereiste parameters (ignorecase, wholewords, wordsen encoding) op in de JSON-payload. Voeg device_type toe aan de URL-querytekenreeks.

De mode parameter is alleen vereist wanneer de ETA's zich in een cluster of groep bevinden. Voeg in dat geval mode=cluster toe aan de URL-querytekenreeks op dezelfde manier als device_type.

*credit en*abaworden aan de payload toegevoegd om de slimme identificatiecodes voor creditcardnummers en ABA-routeringsnummers mogelijk te maken, zoals weergegeven in de schermafbeelding:

De term Example Term wordt toegevoegd aan de payload als een woordenboekitem dat overeenkomt.

Verifiëren

Wanneer het POST-verzoek slaagt, bevat het API-log een item dat vergelijkbaar is met dit:

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 -

Verwachte reactie:

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

Als het woordenboek al bestaat en het POST-verzoek opnieuw wordt uitgevoerd, bevat het API-log een item dat vergelijkbaar is met dit:

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 -

Verwachte reactie:

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

Gerelateerde informatie

Gebruik de volgende externe bronnen voor extra achtergrond (de procedure in dit document is zelfstandig):

Woordenboeken toevoegen met REST API + Python 

Dit document bevat de vereiste verificatiemethode en de minimale procedure. Gebruik HTTP Basic-verificatie met de header Authorisation: Basic <base64(gebruikersnaam:wachtwoord)> en geef de voorkeur aan HTTPS op poort 6443.

REST API en de Cisco ESA 

Bovendien kan de Python-code die in deze procedure wordt gebruikt, worden geëxtraheerd uit Postman. Bekijk deze video tutorial indien nodig:

Postman - Hoe maak je een Python Script Genereren 

Revisiegeschiedenis

Revisie	Publicatiedatum	Opmerkingen
1.0	26-Aug-2026	Eerste vrijgave