Sophos UTM – Konfiguration mit RESTful API

Sophos hat für die UTM bereits mit der Firmwareversion 9.5 die RESTful API integriert. Über die REST API lassen sich Konfiguration an der UTM mittels Webaufrufe durchführen und auslesen wodurch sich die Pflege vereinfachen und automatisieren lässt.

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.

Sophos WebAdmin Settings RESTful API

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.

Sophos Token RESTful API

Sophos RESTful API Konfigurationspunkte

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.

Sophos RESTful API dns group

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.

Sophos RESTful API host

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:

Sophos RESTful API Windows Powershell

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:

Sophos RESTful API Webadmin 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

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

CAPTCHA *