Sophos UTM – Konfiguration mit RESTful API
Vorbereitungen
Zur Nutzung der REST API müssen wir diese im ersten Schritt im Sophos WebAdmin aktivieren. Im gleichen Menü haben wir einen Token generiert und dem Admin zugewiesen.
Wichtig an dieser Stelle ist zu erwähnen, dass der Aufruf der REST API denselben Restriktionen wie der Aufruf des WebAdmin unterliegt. Also müssen die IP Adressen von denen aus die REST API nutzbar sein soll unter „WebAdmin Settings“ -> „Access Control“ entsprechend freigeschaltet sein. Ebenfalls gelten die Rechtebeschränkungen welche ggf. für den Nutzer des Tokens konfiguriert sind.
Erste Versuche mit der REST API
Nun haben wir die Vorbereitungen getroffen um die REST API nutzen zu können, doch wie verwenden wir sie nun?
Schauen wir uns dafür die beiden Links aus dem obigen Screenshot, „API Endpoint“ und „Documentation“, an.
Über den API Endpoint rufen wir nun das WebGUI zur REST API auf und melden uns dort mittels des vorher erstellen Tokens an.
Wie uns nun aufgefallen ist, gibt es sehr viele Konfigurationspunkte an denen man die UTM über die REST API konfigurieren kann.
Um nicht im trüben zu fischen und jede Einstellungsmöglichkeit zu suchen, haben wir uns die Dokumentation näher angeschaut und sind dabei auf folgendes sehr nützliches Shell Script gestoßen welches wir sogleich ausprobiert haben indem wir es in einer SSH Sitzung gestartet haben und anschließend über den WebAdmin eine Testhost erstellt wurde:
192:/root # confd-watch.plx -v watching the Confd storage on ASG 9.605001 o+ REF_NetHosTesthost network host created resolved = 1 name = Testhost hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 1.2.3.4 duids = Empty ARRAY macs = Empty ARRAY
Was wir nun in der Zeile:
o+ REF_NetHosTesthost network host created
erkennen können ist, dass der Testhost unter „network“ -> „host“ erstellt wurde. Also navigieren wir im GUI dorthin und schauen uns die Möglichkeiten an welche uns zur Verfügung stehen.
Wie wir beim Studieren der WebGUI feststellen können wir hierrüber auch Objekte anlegen. Also probieren wir die POST Methode für den Testhost2 aus.
Nachdem wir “Try it out!” gedrückt haben, bekommen wir im Webbrowser auch direkt den Ausgeführten Befehl und die Ergebnisse präsentiert.
Den abgesetzten CURL Befehl:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic XYZ12345' -d '{"address":"2.3.4.1","address6":"","comment":"","duids":[],"hostnames":[],"interface":"","macs":[],"name":"Testhost2","resolved":false,"resolved6":false,"reverse_dns":false}' 'https://192.168.2.4:4444/api/objects/network/host/'
Und den Response Body:
{ "_locked": "", "_ref": "REF_NetHosTesthost2", "_type": "network/host", "address": "2.3.4.1", "address6": "", "comment": "", "duids": [], "hostnames": [], "interface": "", "macs": [], "name": "Testhost2", "resolved": true, "resolved6": false, "reverse_dns": false }
In unserer SSH Sitzung können wir auch erkennen, das der Testhost2 erstellt wurde:
192:/root # confd-watch.plx -v watching the Confd storage on ASG 9.605001 o+ REF_NetHosTesthost2 network host created name = Testhost2 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 2.3.4.1 macs = Empty ARRAY duids = Empty ARRAY
Das erste Script: Hinzufügen mehrerer Hosts
Da wir nun jede Menge Informationen gesammelt haben, wie wir die REST API nutzen können, machen wir uns daran ein erstes einfaches Script für das Hinzufügen mehrerer Hosts zu schreiben.
Als Mittel der Wahl haben wir hier die Powershell gewählt, da die meisten administrativen Aufgaben für eine Sophos UTM über Windows Systeme stattfinden.
Powershell Script:
#setzen der Parameter für das Script param( $UTMAddress = "192.168.2.4", [Parameter(Mandatory=$true)] $UTMApiToken = "XXXxxxXxxxXXXXxxxx", $newHosts = ".\hosts.txt" ) #Anpassen des SSL Verhaltens der Powershell für self signed Certificates Add-Type @" using System.Net; using System.Security.Cryptography.X509Certificates; public class TrustAllCertsPolicy : ICertificatePolicy { public bool CheckValidationResult( ServicePoint srvPoint, X509Certificate certificate, WebRequest request, int certificateProblem) { return true; } } "@ [System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy #API Token wird für die Anmeldung an der UTM vorbereitet $token = [Convert]::ToBase64String([System.Text.Encoding]::Default.GetBytes("token:" + $UTMApiToken)) #Header für den HTTP Request wird zusammengesetzt $headers = @{} $headers.add("Authorization",'Basic ' + $token) $headers.add("Content-Type", "application/json") $headers.add("Accept", "application/json") #import der einzutragenden Hosts $NewHostsList = Import-Csv -Path $newHosts #generieren der API URL $urlHost = "https://"+ $UTMAddress + ":4444/api/objects/network/host/" foreach ($newHost in $NewHostsList){ #generieren des Body mit den Host Eigenschaften $newHostName = $newHost.name $body = '{"address":"' + $newHost.ip + '","name":"' + $newHostName + '"}' try{ #es wird versucht den Host anzulegen Invoke-RestMethod -Uri $urlHost -Method Post -Headers $headers -Body $body | Out-Null Write-Host -ForegroundColor Green "Der Host $newHostName wurde angelegt" } catch{ #wenn der Host nicht angelegt werden konnte wird eine entsprechende Fehlermeldung ausgegeben Write-Host -ForegroundColor Red "Der Host $newHostName konnte nicht angelegt werden" } }
In der hosts.txt haben wir folgenden Inhalt hinterlegt:
NAME,IP Testhost,1.2.3.4 Testhost2,2.3.4.1 Testhost3,3.4.1.2 Testhost4,4.1.2.3 Testhost5,4.3.2.1 Testhost6,3.2.1.4 Testhost7,2.1.4.3 Testhost8,1.4.3.2
Nun führen wir das Script zweimal aus um die Fehlerbehandlung zu prüfen.
Die Ausgabe die wir auf der Powershell sehen ist wie erwartet:
Wie uns auch die Ausgabe in der SSH Sitzung bestätigt, wurden die Hosts erfolgreich angelegt:
192:/root # confd-watch.plx -v watching the Confd storage on ASG 9.605001 s 1 caught USR1 signal(s) vc 88 89 data version change detected at Mon Sep 16 13:29:02 2019 o+ REF_NetHosTesthost network host created name = Testhost resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 1.2.3.4 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 89 90 data version change detected at Mon Sep 16 13:29:02 2019 o+ REF_NetHosTesthost2 network host created name = Testhost2 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 2.3.4.1 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 90 91 data version change detected at Mon Sep 16 13:29:02 2019 o+ REF_NetHosTesthost3 network host created name = Testhost3 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 3.4.1.2 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 91 92 data version change detected at Mon Sep 16 13:29:02 2019 o+ REF_NetHosTesthost4 network host created name = Testhost4 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 4.1.2.3 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 92 94 data version change detected at Mon Sep 16 13:29:03 2019 o+ REF_NetHosTesthost5 network host created resolved = 1 name = Testhost5 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 4.3.2.1 macs = Empty ARRAY duids = Empty ARRAY o+ REF_NetHosTesthost6 network host created name = Testhost6 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 3.2.1.4 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 94 95 data version change detected at Mon Sep 16 13:29:03 2019 o+ REF_NetHosTesthost7 network host created name = Testhost7 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 2.1.4.3 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) vc 95 96 data version change detected at Mon Sep 16 13:29:04 2019 o+ REF_NetHosTesthost8 network host created name = Testhost8 resolved = 1 hostnames = Empty ARRAY reverse_dns = 0 resolved6 = 0 address6 = Empty SCALAR comment = Empty SCALAR interface = Empty SCALAR address = 1.4.3.2 duids = Empty ARRAY macs = Empty ARRAY s 1 caught USR1 signal(s) v= 96 96 data version unchanged at Mon Sep 16 13:29:04 2019
Auch im WebAdmin sehen wir das erwartete Ergebnis:
Somit haben wir erfolgreich ein erstes Script erstellt welches für uns Hosts auf der Sophos UTM erstellt.
Neben dem Vorteil der Aufwandsreduzierung und Zeitersparnis werden gegenüber manueller Konfiguration auch Fehler vermieden.
Das Hinzufügen mehrerer Hosts ist dabei nur eine von vielen Möglichkeiten mit der RESTful API.
1 Kommentar