Statistikdaten aus SEPPmail auslesen
Die SEPPmail-Appliance stellt bei unseren Kunden die Funktion der E-Mail-Verschlüsselung zur Verfügung. Dies passiert in der Regel unbemerkt und vollautomatisch. Zur Auswertung bekommen Administratoren täglich statistische Daten aus der Appliance per E-Mail zugesendet, die im Administrationsinterface ebenfalls ersichtlich sind. Manche Organisationen haben jedoch zentrale Reporting-Plattformen im Einsatz, die Daten von vielen unterschiedlichen Systemen sammeln und darstellen. Um diese Reporting-Anforderungen zu erfüllen, bietet SEPPmail die Legacy API an.
Darunter versteht man eine REST API-Schnittstelle, mit der sich Statistikdaten aus SEPPmail in ein generisches Datenformat (CSV, JSON etc.) auslesen lassen. Diese Daten können dann einfach von anderen Systemen weiterverarbeitet werden.
Da Rest nicht die benutzerfreundlichste Schnittstelle ist und viele Administratoren auf der Windows-Plattform die dort mitgelieferte PowerShell einsetzen, sind weiter unten ein paar Beispiele aufgeführt, die darstellen, wie man mittels PowerShell REST-Aufrufe macht, um Daten aus der SEPPmail-Appliance zu erhalten.
Zur Einrichtung eines Benutzerkontos mit entsprechenden Rechten in der SEPPmail-Appliance sollte vor dem Start der User-Guide gelesen werden. Das Konto ist notwendig für die Nutzung des Features.
Reporting mit Legacy API
Die Legacy API liefert jeweils Daten der letzten 24 Stunden, weshalb lediglich Daten innerhalb dieses Zeitraumes angezeigt werden. Zu Beginn sind die Anmeldedaten und das Ziel (die SEPPmail-Appliance) für die Abfragen festzulegen und die URL für die Aufrufe zusammenzustellen.
# Abfrage Username und Passwort, zusammenstellen eines „Credential“ Objektes. $user = Read-Host -Prompt ‚Username i.e. reportadmin@contoso.de‘ $pwd = Read-Host -Prompt ‚Password‘ -AsSecureString $cred = New-object pscredential -ArgumentList ($user,$pwd) # Abfrage wie die SEPPmail erreichbar ist und zusammenstellen der Abfrage-URL. $seppmailDNS = Read-Host -Prompt ‚SEPPmail DNS name (i.e. securemail.contoso.de)‘ $adminPort = ‚8443‘ $urlroot = ‚https://‘ + $seppmailDNS + ‚:‘ + $adminport + ‚/v1/legacy.app/‘ | |
Mit diesen Werten lassen sich die Abfragen zusammenbauen.
Allgemeine Encryption-Info
$uri = $urlroot + ‚encinfo‘ $encinfodata = Invoke-RestMethod -Uri $uri -Method GET -Credential $cred -OutVariable ‚encinfo‘ | |
Die Daten sind nun in der Variable $encinfo gespeichert, die diese Daten zwar erfasst, aber in Substrukturen ablegt.
Die entsprechenden Daten werden schließlich verwendet, um Berichte daraus zu erzeugen.
Auswertungsbeispiele
S/MIME-Mailadressen mit *hans*
$encinfodata.smime.personal|where-object mailAddress -like ‚*hans*‘ | |
S/MIME-Domains mit *.de am Ende
$encinfodata.smime.domain|where-object domain -like ‚*.de‘ | |
TLS-Domains mit spezifischen Settings (’none‘, ‚verify‘, ‚may‘, ’secure‘)
$encinfodata.tls.domain |where-object {$_.tls -eq ’secure‘} | |
TLS-Domains mit *test* im Namen
$encinfodata.tls.domain |where-object {$_.tls -eq ’secure‘} | |
GINA-Mailadressen, die temporär gesperrt sind
$encinfodata.gina.personal|where-Object status -eq ‚locked temporarily’|select mailAddress | |
GINA-Mailadressen, die ‚enabled‘ sind
$encinfodata.gina.personal|where-Object status -eq ‚locked temporarily’|select mailAddress | |
Für einen einfachen Überblick über die Anzahl der Empfängeradressen werden die Zahlen von PowerShell zusammengerechnet.
Die Daten lassen sich auch vorfiltern (Auswertung siehe oben).
$uri = $urlroot + ‚encinfo/smime‘ $smimeMailAddr = Invoke-RestMethod -Uri $uri -Method GET -Credential $cred | |
Liefert alle möglichen Verschlüsselungsmethoden für S/MIME-Domain.
$uri = $urlroot + ‚encinfo/smime‘ $smimeMailAddr = Invoke-RestMethod -Uri $uri -Method GET -Credential $cred | |
Beispiel
$smimeMailDomains.smime.domain ($smimeMailDomains.smime.domain).count | |
Soll die Abfrage zum Beispiel eine Empfängeradresse limitieren, so lässt sich das Argument mailAddress nutzen.
$mailaddr = ‚max@mustermann.de‘ $uri = $urlroot + ‚encinfo/smime/domain‘ + ‚?mailAddress=‘ + $mailaddr Invoke-RestMethod -Uri $uri -Method GET -Credential $cred |Select-Object -ExpandProperty smime|select-object -ExpandProperty domain | |
Dies zeigt an, mit welcher Verschlüsselungsform die E-Mails verschlüsselt werden.
Statistiken
Alle Tagesstatistiken (Default User) als CSV
$uri = $urlroot + ’statistics‘ $userstats = Invoke-RestMethod -Uri $uri -Method GET -Credential $cred $userstats|set-content c:\temp\smstats.CSV | |
Wenn man die Daten in PowerShell auswerten möchte, ist JSON komfortabler.
Alle Tagesstatistiken (Default User) als JSON
$uri = $urlroot + ’statistics?returnType=JSON‘ $userstats = Invoke-RestMethod -Uri $uri -Method GET -Credential $cred | |
Dieser Aufruf liefert Daten mit folgenden Eigenschaften:
‚Mail address‘ ‚User ID‘ ‚Certificate expires on‘ ‚Group membership‘ ‚Account last used‘ ‚S/MIME Domain encrypted mails received‘ ‚Registered user‘ ‚GINA encrypted mails sent‘ ‚S/MIME signed mails received‘ ‚S/MIME Domain encrypted mails sent‘ ‚S/MIME signed mails sent‘ ‚S/MIME encrypted mails sent‘ | |
Die Daten lassen sich im Anschluss in ‚Object‘-Befehlen verwenden.
$userstats.user|sort-object ‚GINA encrypted mails sent’|format-Table ‚E-Mail address‘,’GINA encrypted mails sent‘,’Account last used‘,’Registered user‘ -AutoSize | |
$userstats.user|Sort-Object ‚Account last used‘ -Descending -Culture en-US|Out-GridView | |
Domain-Tagesstatistiken
Ähnlich wie das Beispiel oben können auch Domainstatistiken verwendet werden.
$uri = $urlroot + ’statistics/domain?returnType=JSON‘ Invoke-RestMethod -Uri $uri -Method GET -Credential $cred -OutVariable ‚domainstat‘ $domainstat|ConvertFrom-Csv -Delimiter ‚;‘ | |