Audiocodes REST-API

Lange hat es gedauert, bis Audiocodes eine einfache erreichbare API für ihre Gateways und Session Border Controller bereit gestellt hat. Bislang habe ich Gateways per SYSLOG überwacht und mehr oder weniger gut per SNMP. Über HTTPS und REST ist es nun sehr viel einfacher, Betriebsdaten zu ermitteln. Das eröffnet natürlich ganz neue Wege, Daten aus dem Gateway in eine vorhandene Lösung zu überführen. Das kann ein Inventar sein, z.B.: um Versionen zu prüfen oder Dokumentationen anzufertigen. Aber auch KPIs (Key Performance Indikatoren) sind für ein Monitoring interessant

API Einrichten

Der Zugriff auf die API ist natürlich nicht anonym einmal mal so möglich. Daher sind durch den Administrator erst einmal Voraussetzungen zu schaffen:

  • Authentifizierung
    Der Zugriff erfordert eine Anmeldung, d.h. das Skript muss einen gültigen Benutzernamen mit Kennwort für das jeweilige Gateway haben. Je nach Einstufung des Kontos kann er bestimmte Aktionen ausführen. Der einfachste Weg ist die Anlage eines Benutzers mit "Monitor"-Recht, der nur einen Teilbereich der REST-API lesen aber nicht schreiben kann.

    Dies ist nur eine vereinfachte Tabelle, denn Audiocodes unterscheidet später noch weitere Unterverzeichnisse und HTTP-Methoden
  • TLS-Zertifikat
    Die Anmeldung erfolgt per HTTP-Basic-Authentication. Das macht die Nutzung per Automatisierung einfach und auch eine Fehlersuche, solange die Verbindungen nicht verschlüsselt sind. Aber das ist natürlich keine Lösung, denn ohne Verschlüsselung dürfen Sie hier nicht arbeiten, denn die REST-API erlaubt auch Konfigurationsänderungen. Sie sollten entweder ein öffentliches Zertifikat oder eines ihrer internen vertrauenswürdigen PKI nutzen. Ein "Self Signed" Zertifikat verbietet sich daher schon fast.

Für den Anfang sollten wir einen eigenen REST-Benutzer mit dem Recht "Monitoring" anlegen und HTTPS erzwingen. Die Einstellung ist auf der Webseite recht einfach möglich:

Ich nutze bei den folgenden Beispielen den User "RESTMON" mit dem Kennwort "DasIstEinKennwort!" gegen die URL https://sbc.msxfaq.de. Alle Werte sind nicht real.

Security Guidelines SIP Media Gateways and SBCs
https://www.audiocodes.com/media/13430/recommended-security-guidelines-ver-72.pdf

Ich habe noch zu klären, ob hier auch eine LDAP-Anmeldung möglich ist.

Anmelden und erster Aufruf

Nachdem diese Einrichtung würde ich erst einmal einen einfachen HTTPS-Aufruf per PowerShell starten, welcher mir den Status meldet. Damit lässt sich ganz schnell prüfen, dass DNS, TLS, REST-API, Anmeldedaten u.a. korrekt eingerichtet sind.

Erst ab PowerShell Core (6+) gibt es den Parameter "-SkipCertificateCheck", um in nicht produktiven Umgebungen die Zertifikatsprüfung abzuschalten. Für die Produktion rate ich davon ab!

param (
   $restuser = "RESTMON",
   $restpass = (read-host -prompt "Kennwort") ,    # in der Produktion sollten Sie NIE ein Kennwort im Code ablegen
   $sbcurl   = "https://sbc.msxfaq.de"
)

# Zusammenbauen des AuthHeader
$Anmeldestring= "$($restuser):$($restpass)"
$Anmeldestringb64 = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Anmeldestring))
$headers = @{ Authorization = "Basic $($Anmeldestringb64)"}

$sbcresponse = Invoke-RestMethod `
                   -Uri "$($sbcurl)/api/v1/status" `
                   -Method Get `
                   -Headers $headers
$sbcresponse


localTimeStamp : 06.09.2021 21:35:44
ipAddress : 192.168.1.16
subnetMask : N/A
defaultGateway : N/A
productType : Mediant 1000
versionID : 7.20A.254.565
protocolType : SIP
operationalState : UNLOCKED
highAvailability : Not Operational
serialNumber : xxxxxx
macAddress : 00908fxxxxxx
systemUpTime : 12052516
saveNeeded : False
resetNeeded : False

Wenn Sie den SSL-Stream aufbrechen (WireShark mit PrivateKey des Zertifikats oder Fiddler) dann sehen sie hier auch die JSON-Antwort:

Schon durch diesen einfachen Aufruf können wir schon mal die Version der Firmware und einige andere Daten ermitteln und überwachen. Der Zeitstempel hilft bei der Kontrolle der Zeitabweichung und ist z.B.: wichtig, wenn Sie Logdateien mehrerer Systeme zusammenführen müssen. Auch die Versionsnummer der Firmware, Seriennummer und MAC-Adresse hilft bei einer Inventarisierung und auch die Notwendigkeit eines "Reboot" wird übermittelt.

In der Anleitung von Audiocodes werden weitere Pfade aufgeführt. Interessant sind hier z.B. die KPIs und Lizenzpfade wie:

/api/v1/kpi/current
/api/v1/kpi/current/sbc
/api/v1/kpi/current/sbc/callstats
/api/v1/kpi/current/sbc/callStats/ipGroup?after=0
/api/v1/kpi/current/sbc/callStats/ipGroup/0
/api/v1/kpi/current/sbc/callStats/ipGroup/0?limit=1
/api/v1/kpi/current/sbc/callStats/ipGroup/0?kpi=attemptedCallsRate Out
/api/v1/kpi/current/sbc/callStats/ipGroup/0/noAnswerCallsInTotal ?interval=all
/api/v1/license

Leider habe ich keine URL gefunden die einfach mal alle Daten liefert. Aber vielleicht würde das dann auch den Audiocodes überlasten. Sie müssen also schon "durchlaufen" und die Unterobjekte bestimmen.

REST mit CDR

Eine zweite Funktion per REST geht in die Gegenrichtung: Sie können im Audiocodes Mediant auch einen HTTP-Server hinterlegen und bestimmen, welche CDRs dorthin gesendet werden. Man muss damit also nicht mehr die Daten per SYSLOG ungesichert verteilen.

Hier ist dann aber der Mediant der Client und die Gegenstelle ist ein Webserver, der die Anfragen zur weiteren Verarbeitung annimmt.

REST mit Webseite

Die REST-API wird übrigens nicht nur für API-Aufrufe genutzt. Auch die Webseite von Audiocodes selbst spricht per HTTPS mit dem Backend. Allerdings wird hier die Anmeldung am Anfang per Formular durchgeführt und ein Sessioncookie sorgt für die weitere Sicherheit. Aber auch hier: Bitte HTTPS verwenden, insbesondere wenn Sie sich mit privilegierten Rechten anmelden. Angreifer können ansonsten sehr einfach Sessioncookies abgreifen.

Quasi alle 15 Sekunden wird ein Request zum Update des Status ausgelöst

Der Versuch diese URL aber anonym abzurufen wurde mit einem "401 (unauthorized)" abgelehnt.

Monitoring mit PRTG und Co

Ich habe aktuell noch kein Skript entwickelt, welches diese Daten nun in ein 3rd Party Monitoring übernimmt. PRTG selbst hat sogar schon einen REST-Sensor, den ich vermutlich ohne umfangreiche Entwicklung einsetzen kann. Wer allerdings viele SBCs nutzt, sollte sich vielleicht das One Voice Operations Center (OVOC) anschauen.

Bei Net at Work und Kunden haben wir mit Hilfe der API unser Monitoring und Management optimiert. Den Code kann ich aber nicht auf der MSXFAQ bereitstellen.

Weitere Links