Get-CoveDeviceReport.ps1

<#PSScriptInfo
.VERSION 1.0.0
.GUID 0b90f453-da5f-508c-aa13-004eee0d8445
.AUTHOR Torsten Weise
.COMPANYNAME powerscripting.de
.COPYRIGHT (c) 2026 Torsten Weise. MIT-Lizenz.
.TAGS Powerscripting German Monitoring Report Windows Backup Cove N-able PSEdition_Desktop PSEdition_Core
.LICENSEURI https://powerscripting.de/skripte/files/LICENSE.txt
.PROJECTURI https://powerscripting.de/skripte/get-covedevicereport.html
.ICONURI https://powerscripting.de/assets/icon-192.png
.EXTERNALMODULEDEPENDENCIES
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES
Erste Veröffentlichung in der PowerShell Gallery.
.PRIVATEDATA
#>


<#
.SYNOPSIS
    Bewertet die Backups aller Geräte in N-able Cove Data Protection über die JSON-RPC-API.
 
.DESCRIPTION
    Die Cove-Konsole zeigt den Status jedes Geräts, aber nicht auf einen Blick, welche Geräte seit Tagen
    kein erfolgreiches Backup mehr haben. Ein Gerät, das gar nicht mehr sichert, steht dort oft unauffällig
    mit dem Status des letzten Laufs von vor zwei Wochen.
 
    Das Skript meldet sich an der API an, liest für alle Geräte unterhalb deines Partners die Werte für
    "Total" (alle Datenquellen zusammen) und bewertet jedes Gerät:
    - Fehler: letzter Lauf fehlgeschlagen, abgebrochen, unterbrochen oder Speicherquote überschritten.
    - Veraltet: letzter erfolgreicher Lauf älter als -MaxAgeHours.
    - Warnung: letzter Lauf mit Fehlern abgeschlossen, ohne Auswahl oder nie gestartet.
    - OK: letzter Lauf erfolgreich und aktuell.
    - Läuft: Sicherung gerade aktiv.
 
    Der Bericht wird als HTML- und CSV-Datei gespeichert. Der Exitcode ist 0 (alles OK), 1 (Warnung) oder
    2 (Fehler oder veraltet), passend für die Aufgabenplanung oder ein RMM-Tool.
 
.PARAMETER Partner
    Name des Partners (deiner Firma oder des Kunden) genau so, wie er in der Cove-Konsole steht.
 
.PARAMETER Credential
    Benutzer und Kennwort eines API-Benutzers. Ohne Angabe fragt das Skript nach.
 
.PARAMETER Customer
    Optional. Nur Geräte dieser Kunden auswerten (Spalte "Customer", Platzhalter erlaubt).
 
.PARAMETER MaxAgeHours
    Ab wie vielen Stunden ohne erfolgreiches Backup ein Gerät als veraltet gilt. Standard: 26.
 
.PARAMETER ReportPath
    Ordner für HTML- und CSV-Bericht. Standard: aktueller Ordner.
 
.EXAMPLE
    .\Get-CoveDeviceReport.ps1 -Partner 'Contoso IT GmbH'
 
    Fragt nach Benutzer und Kennwort und bewertet alle Geräte.
 
.EXAMPLE
    .\Get-CoveDeviceReport.ps1 -Partner 'Contoso IT GmbH' -Credential (Import-Clixml C:\Skripte\cove-api.xml) -MaxAgeHours 48 -Customer 'Muster*'
 
    Läuft ohne Rückfrage, etwa in der Aufgabenplanung, und wertet nur die Kunden ab "Muster" aus.
 
.NOTES
    Autor: Torsten Weise, powerscripting.de
    API: https://api.backup.management/jsonapi (JSON-RPC 2.0, Methoden Login und EnumerateAccountStatistics).
    Spaltencodes laut N-able-Dokumentation "Column Codes": I1 Gerätename, I8 Kunde, I18 Computername,
    I14 belegter Speicher, I78 aktive Datenquellen, D09F00 Status letzter Lauf, D09F09 letzter erfolgreicher
    Lauf, D09F15 letzter Lauf, D09F06 Fehleranzahl.
    Lege für das Skript einen eigenen API-Benutzer mit Leserechten an. Die Zugangsdaten für die
    Aufgabenplanung speicherst du mit Get-Credential | Export-Clixml (nur für denselben Windows-Benutzer lesbar).
    Das Skript liest nur und ändert nichts.
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory)] [string] $Partner,
    [pscredential] $Credential,
    [string[]] $Customer,
    [ValidateRange(1, 2160)] [int] $MaxAgeHours = 26,
    [string] $ReportPath = (Get-Location).Path
)

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
$Api = 'https://api.backup.management/jsonapi'
if (-not $Credential) { $Credential = Get-Credential -Message 'Cove-API-Benutzer' }

$script:visa = $null
function Invoke-Cove([string] $Method, [hashtable] $Params) {
    $body = @{ jsonrpc = '2.0'; id = 'jsonrpc'; method = $Method; params = $Params }
    if ($script:visa) { $body.visa = $script:visa }
    $json = $body | ConvertTo-Json -Depth 8 -Compress
    $resp = Invoke-RestMethod -Uri $Api -Method Post -ContentType 'application/json; charset=utf-8' `
        -Body ([Text.Encoding]::UTF8.GetBytes($json)) -TimeoutSec 120 -ErrorAction Stop
    if ($resp.error) { throw "Cove-API $Method`: $($resp.error.message)" }
    if ($resp.visa) { $script:visa = $resp.visa }   # jede Antwort liefert ein frisches Visum
    return $resp.result.result
}

# Anmelden
$login = Invoke-Cove 'Login' @{
    partner  = $Partner
    username = $Credential.UserName
    password = $Credential.GetNetworkCredential().Password
}
$partnerId = $login.PartnerId
Write-Host "Angemeldet bei Partner '$Partner' (ID $partnerId)"

# Gerätestatistiken seitenweise lesen
$columns = 'I1', 'I8', 'I18', 'I14', 'I78', 'D09F00', 'D09F09', 'D09F15', 'D09F06'
$devices = [System.Collections.Generic.List[object]]::new()
$start = 0
$page  = 500
do {
    $chunk = @(Invoke-Cove 'EnumerateAccountStatistics' @{
        query = @{
            PartnerId = $partnerId; Filter = ''; Columns = $columns; OrderBy = 'I8 ASC'
            StartRecordNumber = $start; RecordsCount = $page; Totals = @()
        }
    })
    foreach ($d in $chunk) { $devices.Add($d) }
    $start += $page
} while ($chunk.Count -eq $page)
Write-Host "$($devices.Count) Geräte gelesen"

$status = @{
    1 = 'Läuft'; 2 = 'Fehlgeschlagen'; 3 = 'Abgebrochen'; 5 = 'Erfolgreich'; 6 = 'Unterbrochen'; 7 = 'Nicht gestartet'
    8 = 'Mit Fehlern'; 9 = 'Läuft mit Fehlern'; 10 = 'Quote überschritten'; 11 = 'Keine Auswahl'; 12 = 'Neu gestartet'
}
$epoch = [datetime]::new(1970, 1, 1, 0, 0, 0, [DateTimeKind]::Utc)
function ConvertFrom-Epoch($v) { if ($v -and [long]$v -gt 0) { $epoch.AddSeconds([long]$v).ToLocalTime() } else { $null } }

$now  = Get-Date
$rows = foreach ($d in $devices) {
    # Settings ist eine Liste aus Objekten mit je einer Eigenschaft, z. B. @{ I1 = 'Server01' }
    $s = @{}
    foreach ($kv in @($d.Settings)) { foreach ($p in $kv.PSObject.Properties) { $s[$p.Name] = $p.Value } }

    if ($Customer -and -not ($Customer | Where-Object { $s['I8'] -like $_ })) { continue }

    $code    = if ($s['D09F00']) { [int]$s['D09F00'] } else { 0 }
    $last    = ConvertFrom-Epoch $s['D09F15']
    $lastOk  = ConvertFrom-Epoch $s['D09F09']
    $ageH    = if ($lastOk) { [math]::Round(($now - $lastOk).TotalHours, 1) } else { $null }

    $rating = if ($code -in 1, 9, 12) { 'Läuft' }
              elseif ($code -in 2, 3, 6, 10) { 'Fehler' }
              elseif (-not $lastOk -or $ageH -gt $MaxAgeHours) { 'Veraltet' }
              elseif ($code -in 7, 8, 11) { 'Warnung' }
              else { 'OK' }
    # Ein laufendes Backup auf einem Gerät, das seit Tagen nicht durchkommt, ist trotzdem veraltet
    if ($rating -eq 'Läuft' -and $ageH -gt $MaxAgeHours) { $rating = 'Veraltet' }

    [pscustomobject]@{
        Kunde              = $s['I8']
        Gerät              = $s['I1']
        Computer           = $s['I18']
        Bewertung          = $rating
        'Letzter Lauf'     = if ($last) { $last.ToString('dd.MM.yyyy HH:mm') } else { '' }
        Status             = if ($status.ContainsKey($code)) { $status[$code] } else { "Code $code" }
        'Letzter Erfolg'   = if ($lastOk) { $lastOk.ToString('dd.MM.yyyy HH:mm') } else { 'nie' }
        'Stunden seit Erfolg' = $ageH
        Fehler             = $s['D09F06']
        'Belegt GB'        = if ($s['I14']) { [math]::Round([double]$s['I14'] / 1GB, 1) } else { 0 }
        Datenquellen       = $s['I78']
    }
}

$order  = @{ 'Fehler' = 0; 'Veraltet' = 1; 'Warnung' = 2; 'Läuft' = 3; 'OK' = 4 }
$sorted = @($rows | Sort-Object @{ e = { $order[$_.Bewertung] } }, Kunde, Gerät)
$sorted | Format-Table Kunde, Gerät, Bewertung, Status, 'Letzter Erfolg', 'Stunden seit Erfolg' -AutoSize

$bad   = @($sorted | Where-Object { $_.Bewertung -in 'Fehler', 'Veraltet' }).Count
$warn  = @($sorted | Where-Object Bewertung -eq 'Warnung').Count
$stats = $sorted | Group-Object Bewertung | ForEach-Object { "$($_.Name): $($_.Count)" }
Write-Host ($stats -join ' | ')

$title = "Cove-Backupstatus - $($now.ToString('dd.MM.yyyy HH:mm'))"
$css   = '<style>body{font-family:Segoe UI,Arial,sans-serif;font-size:13px}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:4px 8px}th{background:#eee}</style>'
$pre   = "<h2>$title</h2><p>Partner $Partner, $($sorted.Count) Geräte. $($stats -join ', '). Veraltet ab $MaxAgeHours Stunden ohne Erfolg.</p>"
$html  = $sorted | ConvertTo-Html -Title $title -Head $css -PreContent $pre | Out-String
$html  = $html -replace '<td>(Fehler|Veraltet)</td>', '<td style="background:#f8d7da">$1</td>' `
               -replace '<td>Warnung</td>', '<td style="background:#fff3cd">Warnung</td>' `
               -replace '<td>OK</td>', '<td style="background:#d4edda">OK</td>'
$base  = Join-Path $ReportPath ("Cove-Backupstatus_{0:yyyy-MM-dd}" -f $now)
$html | Set-Content -Path "$base.html" -Encoding UTF8
$sorted | Export-Csv -Path "$base.csv" -NoTypeInformation -Delimiter ';' -Encoding UTF8
Write-Host "Bericht: $base.html und $base.csv"

if ($bad) { exit 2 } elseif ($warn) { exit 1 } else { exit 0 }