Naar de inhoud
Avanet

Sophos Firewall exporteren en importeren via Central API

Sophos Firewall

Met SFOS 22.0 MR2 of hoger kunnen firewallconfiguraties via de Sophos Central REST API in Sophos Fusion (voorheen Sophos Central) worden geëxporteerd en geïmporteerd. De procedure bestaat uit enkele stappen: authenticeren bij de API, de firewall-ID bepalen, de export of upload starten en de geretourneerde transactie tot aan de voltooiing controleren.

Voor één handmatige wijziging rechtstreeks in de lokale WebAdmin gebruikt men in plaats daarvan Configuratie selectief exporteren en importeren. Het artikel legt ook Entities.xml, SSMK, objectafhankelijkheden en de mergewerking van de import uit.

Een import wijzigt de doelfirewall en is geen herstel van een back-up. Maak vooraf een actuele firewallback-up, voer de procedure eerst uit met een testfirewall en valideer het resultaat daarna lokaal.

Vereisten en API-variabelen voorbereiden

Benodigd zijn:

  • een met Sophos Fusion verbonden en beheerde firewall met SFOS 22.0 MR2 of hoger;
  • een actief betaald firewallabonnement naast de Base License of een actief supportcontract;
  • eigen API-referenties met de vereiste rechten;
  • curl, jq en voor een import md5 of md5sum;
  • tenant-ID, regionale API-host en firewall-ID;
  • een onderhoudsvenster en een geteste terugvalprocedure voor imports.

Credentialaanmaak, rollen, Token- en whoami-contracten, regio, secretbeveiliging, validatie en algemene diagnose staan centraal in Sophos Central API Credentials veilig beheren. Rond eerst dat proces af; dit artikel gebruikt daarna SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID en SOPHOS_API_HOST.

API-referenties worden in Sophos Fusion aangemaakt onder Global Settings > Access Control > API Credentials. Voor een tenant adviseert Sophos de rol Service Principal Firewall. In het Partner Dashboard staat deze functie onder Global Settings > APIs & Integrations > API Credentials Management; daar zijn andere rollen beschikbaar en geldt de kleinste rol die toegang tot de doeltenant biedt. Client Secret, JWT, Secure Storage Master Key en later uitgegeven download- of upload-URL’s horen niet thuis in tickets, chats of screenshots.

De voorbeelden worden uitgevoerd in Bash en gaan uit van API-referenties voor een tenant. Met API-referenties voor een partner of enterprise-organisatie moeten eerst de doeltenant en de bijbehorende regionale API-host worden bepaald. Gebruik vervolgens voor elke tenantspecifieke aanvraag de regionale apiHost die whoami voor die tenant retourneert.

Koppel de drie door het Owner-proces gevalideerde waarden aan de variabelen die hier worden gebruikt:

JWT="$SOPHOS_ACCESS_TOKEN"
TENANT_ID="$SOPHOS_TENANT_ID"
API_HOST="$SOPHOS_API_HOST"

Vraag het JWT niet opnieuw aan: JWT is het hierboven overgenomen tijdelijke Access Token.

De eenvoudige curl-voorbeelden geven het kortlevende JWT door als headerargument. Voer ze daarom uit op een vertrouwd beheerwerkstation waarop andere gebruikers lokale procesargumenten niet kunnen uitlezen.

Tenant-ID en regionale API-host komen eveneens uit het Owner-proces:

TENANT_ID en API_HOST zijn al gevalideerd. Bij Partner- of Enterprise-credentials moeten ze uit de volledig gepagineerde tenantlijst van het Owner-proces komen.

Firewall-ID bepalen

De firewalllijst toont naam, hostnaam, serienummer, firmware en UUID:

FIREWALLS_FILE=$(mktemp); printf '[]\n' >"$FIREWALLS_FILE"; page=1; max_pages=1000; expected_pages=
while (( page <= max_pages )); do
  PAGE_RESPONSE=$(curl --fail-with-body --silent --show-error --get --header "Authorization: Bearer $JWT" --header "X-Tenant-ID: $TENANT_ID" --data-urlencode "page=${page}" --data-urlencode 'pageSize=100' --data-urlencode 'pageTotal=true' "$API_HOST/firewall/v1/firewalls")
  page_total=$(jq -er 'select((.items|type)=="array")|.pages.total|select(type=="number" and floor==. and .>=1 and .<=1000)' <<<"$PAGE_RESPONSE")
  if [[ -z "$expected_pages" ]]; then expected_pages=$page_total; fi; [[ "$page_total" == "$expected_pages" ]] || exit 1
  jq -e --argjson page "$PAGE_RESPONSE" '.+$page.items' "$FIREWALLS_FILE" >"${FIREWALLS_FILE}.new"; mv "${FIREWALLS_FILE}.new" "$FIREWALLS_FILE"
  (( page >= expected_pages )) && break; ((page++))
done
(( page == expected_pages )) || exit 1
jq -r '.[]|[.name,.hostname,.serialNumber,.firmwareVersion,.id]|@tsv' "$FIREWALLS_FILE"

Gebruik de UUID van de juiste firewall en selecteer niet alleen op basis van een vergelijkbare weergavenaam:

read -r -p 'Firewall-UUID uit de goedgekeurde inventaris: ' REQUESTED_FIREWALL_ID
UUID_RE='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
FIREWALL_ID=$(jq -er --arg id "$REQUESTED_FIREWALL_ID" --arg re "$UUID_RE" '[.[]|select((.id|type)=="string" and (.id|test($re)) and (.id|ascii_downcase)==($id|ascii_downcase))]|select(length==1)|.[0].id' "$FIREWALLS_FILE")
rm -f "$FIREWALLS_FILE"; unset PAGE_RESPONSE REQUESTED_FIREWALL_ID page page_total expected_pages max_pages

Ontbreekt de firewall, controleer dan eerst tenant, regio, Sophos Fusion-verbinding en beheergoedkeuring. De registratie wordt uitgelegd in Sophos Firewall verbinden met Sophos Fusion.

Configuratie exporteren

Volledige export starten

De export wordt asynchroon uitgevoerd. De eerste aanroep retourneert daarom alleen een transactie-ID:

EXPORT_RESPONSE=$(
  curl --fail-with-body --silent --show-error \
    --request POST \
    --header "Authorization: Bearer $JWT" \
    --header "X-Tenant-ID: $TENANT_ID" \
    --header 'Content-Type: application/json' \
    --data '{"fullExport":true}' \
    "$API_HOST/firewall/v1/firewall-config/firewalls/$FIREWALL_ID/export"
)

EXPORT_TX=$(jq -er '.transactionId' <<<"$EXPORT_RESPONSE")
printf 'Export transaction: %s\n' "$EXPORT_TX"

Vraag de status na enkele seconden opnieuw op:

EXPORT_STATUS=$(
  curl --fail-with-body --silent --show-error \
    --header "Authorization: Bearer $JWT" \
    --header "X-Tenant-ID: $TENANT_ID" \
    "$API_HOST/firewall/v1/firewall-config/firewalls/transactions/$EXPORT_TX"
)

jq '{status, result, createdAt, finishedAt, expiryAt, response}' \
  <<<"$EXPORT_STATUS"

Herhaal de aanvraag ongeveer elke tien seconden totdat status de eindstatus finished bereikt. pending en started zijn nog geen fouten.

Pas bij status: "finished" en result: "success" bevat response.url de tijdelijke download-URL:

DOWNLOAD_URL=$(
  jq -er '
    select(.status == "finished" and .result == "success") |
    .response.url
  ' <<<"$EXPORT_STATUS"
)

OUTPUT="sophos-firewall-config-$(date +%F).tar"
curl --fail-with-body --location --output "$OUTPUT" "$DOWNLOAD_URL"
tar -tf "$OUTPUT"
unset DOWNLOAD_URL

Het TAR-bestand kan gevoelige netwerk-, gebruikers-, VPN- en policygegevens bevatten. Sla het beveiligd op of verwijder het na de analyse. Voor een leesbaar rapport of een vergelijking van vóór en na kan het opgenomen bestand Entities.xml worden gebruikt in Sophos Firewall Config Studio.

Alleen geselecteerde configuraties exporteren

Voor een selectieve export moeten de entitynamen exact en met de juiste hoofdletters worden opgegeven. Dit voorbeeld exporteert firewall- en NAT-regels met afhankelijke objecten:

curl --fail-with-body --silent --show-error \
  --request POST \
  --header "Authorization: Bearer $JWT" \
  --header "X-Tenant-ID: $TENANT_ID" \
  --header 'Content-Type: application/json' \
  --data '{
    "fullExport": false,
    "includeDependency": true,
    "exportEntities": ["FirewallRule", "NATRule"]
  }' \
  "$API_HOST/firewall/v1/firewall-config/firewalls/$FIREWALL_ID/export"

Entitynamen zijn exact en hoofdlettergevoelig; het voorbeeld gebruikt FirewallRule en NATRule. Bij een selectieve export is includeDependency standaard false; stel de optie bewust in en controleer het resulterende pakket desondanks.

Omvang en beperkingen van het pakket

Houd vóór een API-import ook rekening met deze SFOS-regels voor het TAR-bestand:

  • Een import werkt bestaande instellingen bij. Een instelling die niet in het pakket staat, blijft op het doel ongewijzigd; staat deze in beide configuraties, dan heeft de geïmporteerde waarde voorrang.
  • Bij externe authenticatie bevat de export alleen gebruikers die handmatig op de firewall zijn aangemaakt. OTPTokens bevat uitsluitend uitgegeven tokens voor die gebruikers.
  • REDDevice neemt de benodigde DHCP-server niet automatisch mee, ook niet met includeDependency. Exporteer ook DHCPServer of maak de DHCP-server na de import opnieuw aan.
  • Een geïmporteerde URL-lijst mag maximaal 128 domeinen bevatten.
  • Voor XGS 88w, 108w, 118w en 128w gelden aanvullende voorwaarden voor draadloze configuraties, onder meer voor frequentiebanden, Security mode, Encryption, bridges en het aantal unieke SSID’s.

Een TAR-inhoudsopgave die zonder fouten opent, bewijst dus alleen dat het archief leesbaar is. Ze bevestigt niet dat alle benodigde objecten aanwezig zijn of op de doelhardware worden toegepast.

Configuratie importeren

De import bestaat uit het aanvragen van een upload-URL, het uploaden van het TAR-bestand, het bevestigen van de bestandsgegevens en het controleren van de transactie. Het voorbeeld gebruikt slechts één testfirewall en stelt performPartialImport bewust in op false. De standaardwaarde van de API is true en staat per firewall een gedeeltelijke import toe.

Controleer vooraf de compatibiliteit: de doelfirewall moet minstens dezelfde firmware- en patroonversie hebben. Sophos ondersteunt selectieve imports tussen verschillende modellen alleen van een lager naar een hoger model; de doelhardware moet minstens evenveel Ethernet-poorten hebben. Bij afwijkende poortnamen moet Entities.xml vóór de upload worden aangepast.

Importbestand en controlesom voorbereiden

Bereid het doelbestand, de controlesom en de bestandsgrootte voor:

FILE="sophos-firewall-config-2026-08-03.tar"
FILE_SIZE=$(wc -c <"$FILE" | tr -d ' ')

Op macOS:

CHECKSUM_MD5=$(md5 -q "$FILE")

Op Linux:

CHECKSUM_MD5=$(md5sum "$FILE" | awk '{print $1}')

Uploadsessie aanvragen en bestand uploaden

Vraag een uploadsessie aan en toon alleen de niet-geheime velden:

IMPORT_SESSION=$(
  curl --fail-with-body --silent --show-error \
    --request POST \
    --header "Authorization: Bearer $JWT" \
    --header "X-Tenant-ID: $TENANT_ID" \
    "$API_HOST/firewall/v1/firewall-config/firewalls/import"
)

IMPORT_TX=$(jq -er '.transactionId' <<<"$IMPORT_SESSION")
UPLOAD_URL=$(jq -er '.url' <<<"$IMPORT_SESSION")
jq '{transactionId, method, expiresAt}' <<<"$IMPORT_SESSION"

Upload het bestand vóór het verlopen van de pre-signed URL met de geretourneerde methode PUT. Stuur geen JWT- of tenantheader naar deze URL:

curl --fail-with-body --silent --show-error \
  --request PUT \
  --upload-file "$FILE" \
  "$UPLOAD_URL"
unset UPLOAD_URL

Import voltooien en status controleren

Als het pakket gevoelige informatie bevat en naar een andere of opnieuw geïnstalleerde firewall wordt geïmporteerd, is de bijbehorende Secure Storage Master Key nodig. Zonder deze sleutel importeert SFOS geen gevoelige informatie en daarvan afhankelijke configuraties. De volgende prompt toont het secret niet; met Enter wordt het weggelaten:

read -r -s -p "Secure Storage Master Key, anders Enter: " SSMK
printf '\n'

Voltooi de upload en wijs het pakket toe aan de doelfirewall:

TARGET_FIREWALL_ID="$FIREWALL_ID"

COMPLETE_RESPONSE=$(
  printf '%s' "$SSMK" |
    jq -Rsc \
      --arg firewall "$TARGET_FIREWALL_ID" \
      --arg checksum "$CHECKSUM_MD5" \
      --argjson size "$FILE_SIZE" '
        . as $ssmk |
        {
          firewallIds: [$firewall],
          checksumMd5: $checksum,
          fileSizeBytes: $size,
          performPartialImport: false
        }
        + if ($ssmk | length) > 0
          then {secureMasterKey: $ssmk}
          else {}
          end
      ' |
    curl --fail-with-body --silent --show-error \
      --request POST \
      --header "Authorization: Bearer $JWT" \
      --header "X-Tenant-ID: $TENANT_ID" \
      --header 'Content-Type: application/json' \
      --data-binary @- \
      "$API_HOST/firewall/v1/firewall-config/firewalls/import/$IMPORT_TX/upload-complete"
)
unset SSMK
jq '{id, status, result}' <<<"$COMPLETE_RESPONSE"

Een aanvraag accepteert 1 tot 25 unieke firewall-ID’s. Voor extra firewalls moet het pakket opnieuw worden geüpload; gebruik dezelfde pre-signed URL of transactie-ID niet opnieuw.

Controleer de importstatus via hetzelfde transactie-endpoint:

IMPORT_STATUS=$(
  curl --fail-with-body --silent --show-error \
    --header "Authorization: Bearer $JWT" \
    --header "X-Tenant-ID: $TENANT_ID" \
    "$API_HOST/firewall/v1/firewall-config/firewalls/transactions/$IMPORT_TX"
)

jq '{status, result, createdAt, finishedAt, response}' <<<"$IMPORT_STATUS"

Herhaal ook deze aanvraag ongeveer elke tien seconden totdat status: "finished" verschijnt. Beoordeel pas daarna result en bij meerdere doelen elk element in response.items.

success bevestigt de verwerking door de API, niet de functionele uitwerking.

Import lokaal valideren

Controleer na finished op elke doelfirewall:

  1. Zijn precies de verwachte regels, objecten en instellingen aanwezig?
  2. Ontbreken gebruikers, wachtwoorden, certificaten of afhankelijke objecten door een ontbrekende of onjuiste SSMK?
  3. Komen interfaces, zones, gateways, firmware, patroonversie en hardwaremodel overeen met het pakket?
  4. Werken routing, NAT, VPN, authenticatie en beheertoegang met gedefinieerde testgevallen?
  5. Tonen Audit Trail en configuratielogs onverwachte wijzigingen?
  6. Toont een nieuwe export of Config Studio-vergelijking alleen de geplande verschillen?

Import/export werkt de bestaande configuratie bij en verwijdert niet automatisch alles wat in het pakket ontbreekt. Het TAR-bestand vormt daarom geen volledige gewenste status en vervangt geen back-up, rollback of functionele test.

Een foutieve import terugdraaien

Als de lokale validatie mislukt, stop dan de uitrol, bewaar de transactierespons en maskeer het resultaat niet met meer imports. Ga voor herstel in de lokale WebAdmin naar Backup and firmware > Backup and restore. Kies onder Restore configuration via Choose file de vooraf gemaakte back-up, voer het bijbehorende Encryption password in en start Upload and restore.

Een herstel vervangt de huidige configuratie, verwijdert de op de firewall opgeslagen back-up en start de firewall opnieuw. Daarna wordt het WebAdmin-IP-adres uit de herstelde configuratie actief. Zorg dus vóór de import dat dit adres en het encryptiewachtwoord beschikbaar zijn. Herhaal na de herstart dezelfde functionele tests en controleer met een nieuwe export; wijzigingen van na de back-up gaan bij het herstel verloren.

Problemen oplossen

Export blijft zonder download-URL

De URL verschijnt pas na status: "finished" en result: "success". Controleer bij error of partialSuccess de velden in response en ga niet verder met een lege of verlopen URL.

HTTP 401 of 403

Bij 401 is het JWT meestal verlopen of ongeldig. Authenticeer opnieuw. Controleer bij 403 de Sophos Fusion-rol, tenantcontext, X-Tenant-ID en regionale API-host. De lokale XML API-goedkeuring onder /webconsole/APIController is hiervoor niet verantwoordelijk; deze wordt afzonderlijk behandeld in Toegang tot de Sophos Firewall XML API beveiligen.

Upload-complete retourneert 400 of 409

Controleer transactie-ID, vervaltijd van de upload-URL, werkelijke bestandsgrootte, hexadecimale MD5-controlesom en unieke firewall-ID’s. Wijzig het geüploade bestand daarna niet. Gebruik voor een nieuwe poging een nieuwe uploadsessie.

Import eindigt met error of partialSuccess

Bewaar response en bij meerdere doelfirewalls response.items. Als een API-aanroep een afzonderlijke 4xx- of 5xx-foutreactie retourneert, documenteer dan ook error, message, code, correlationId en requestId. Controleer daarna lokaal doelversie, patroonstatus, model, poorten, afhankelijkheden en SSMK. Als de Sophos Fusion-reactie niet voldoende is, controleer dan fwcm-api-executor.log op de firewall volgens Sophos Firewall-services en logbestanden.

Het transactie-endpoint is bepalend voor de API-status; neem niet aan dat de opdracht in de Central Firewall Task Queue verschijnt.

Verwijder aan het einde van de sessie de gevoelige variabelen:

unset JWT CLIENT_ID TENANT_ID API_HOST FIREWALL_ID TARGET_FIREWALL_ID
unset EXPORT_TX IMPORT_TX CHECKSUM_MD5 FILE_SIZE