Naar de inhoud
Avanet

Sophos Firewall exporteren en importeren via Central API

Sophos Firewall

Sinds Sophos Central Firewall Management 2026.29 kunnen configuraties van firewalls met SFOS 22.0 MR2 of hoger via de REST API 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.

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 Central 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.

API-referenties worden in Sophos Central 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. Sophos legt dit verschil uit in How Our APIs Work.

Voer Client ID en Client Secret in zonder het secret naar de shellgeschiedenis te schrijven:

read -r -p "Client ID: " CLIENT_ID
read -r -s -p "Client Secret: " CLIENT_SECRET
printf '\n'

Vraag vervolgens een tijdelijk JWT aan:

JWT=$(
  printf '%s' "$CLIENT_SECRET" |
    curl --fail-with-body --silent --show-error \
      --request POST \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'grant_type=client_credentials' \
      --data-urlencode "client_id=$CLIENT_ID" \
      --data-urlencode 'client_secret@-' \
      --data-urlencode 'scope=token' \
      https://id.sophos.com/api/v2/oauth2/token |
    jq -er '.access_token'
)
unset CLIENT_SECRET

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.

Met API-referenties voor een tenant retourneert whoami de tenant-ID en de regionale API-host:

WHOAMI=$(
  curl --fail-with-body --silent --show-error \
    --header "Authorization: Bearer $JWT" \
    https://api.central.sophos.com/whoami/v1
)

TENANT_ID=$(jq -er 'select(.idType == "tenant") | .id' <<<"$WHOAMI")
API_HOST=$(jq -er '.apiHosts.dataRegion' <<<"$WHOAMI")
printf 'Tenant: %s\nAPI host: %s\n' "$TENANT_ID" "$API_HOST"

Als jq hier stopt, horen de API-referenties waarschijnlijk bij een partner of enterprise-organisatie. Ga dan niet verder met het bijbehorende ID als X-Tenant-ID, maar bepaal de beheerde tenant en de bijbehorende apiHost.

Firewall-ID bepalen

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

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $JWT" \
  --header "X-Tenant-ID: $TENANT_ID" \
  "$API_HOST/firewall/v1/firewalls?pageSize=1000" |
  jq -r '.items[] |
    [.name, .hostname, .serialNumber, .firmwareVersion, .id] |
    @tsv'

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

FIREWALL_ID="<firewall-uuid>"

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

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"

De geldige entitynamen staan in het actuele exportendpoint van de Sophos Firewall API. Bij een selectieve export is includeDependency standaard false; stel de optie bewust in en controleer het resulterende pakket desondanks.

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.

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 Central-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 Central-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.

Zeer grote import wordt afgebroken

Sophos vermeldt Known Issue NR-19066: een import met zeer veel objecten kan de verwerkingslimiet van twee uur overschrijden. Maak kleinere selectieve pakketten, importeer deze afzonderlijk en valideer elke stap in plaats van de volledige import ongewijzigd te herhalen.

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