Hoppa till innehållet
Avanet

Exportera och importera Sophos Firewall via Central API

Sophos Firewall

Sedan Sophos Central Firewall Management 2026.29 kan konfigurationer från brandväggar med SFOS 22.0 MR2 eller senare exporteras och importeras via REST API. Förloppet består av några få steg: autentisera API-åtkomsten, fastställ brandväggens ID, starta exporten eller uppladdningen och kontrollera den returnerade transaktionen tills den är klar.

En import ändrar målbrandväggen och är inte en återställning av en backup. Skapa först en aktuell backup av brandväggen, testa förloppet med en testbrandvägg och validera därefter resultatet lokalt.

Förbered krav och API-variabler

Följande krävs:

  • en brandvägg med minst SFOS 22.0 MR2 som är ansluten till och hanteras av Sophos Central;
  • en aktiv betald brandväggsprenumeration utöver Base License eller ett aktivt supportavtal;
  • separata API-autentiseringsuppgifter med nödvändiga rättigheter;
  • curl, jq och för en import även md5 eller md5sum;
  • tenant-ID, regional API-värd och brandväggens ID;
  • ett underhållsfönster och en testad reservväg för import.

API-autentiseringsuppgifter skapas i Sophos Central under Global Settings > Access Control > API Credentials. För en tenant rekommenderar Sophos rollen Service Principal Firewall. I Partner Dashboard finns funktionen under Global Settings > APIs & Integrations > API Credentials Management. Där finns andra roller, och rollen med minsta möjliga behörighet som ger åtkomst till mål-tenant ska användas. Client Secret, JWT, Secure Storage Master Key och senare utfärdade URL:er för nedladdning eller uppladdning hör inte hemma i ärenden, chattar eller skärmbilder.

Exemplen körs i Bash och förutsätter autentiseringsuppgifter för en tenant. Autentiseringsuppgifter för partner och Enterprise-organisationer måste först identifiera mål-tenant och dess regionala API-värd. Sophos förklarar skillnaden i Så fungerar våra API:er.

Ange Client ID och Client Secret utan att skriva hemligheten till skalhistoriken:

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

Begär därefter ett tidsbegränsat JWT:

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 enkla curl-exemplen skickar det kortlivade JWT:t som ett headerargument. De ska därför köras på en betrodd administratörsdator där inga andra lokala användare kan läsa processargument.

whoami returnerar tenant-ID och regional API-värd för autentiseringsuppgifter som hör till en tenant:

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"

Om jq avbryts här tillhör autentiseringsuppgifterna sannolikt en partner eller Enterprise-organisation. Fortsätt då inte med deras ID som X-Tenant-ID, utan identifiera den hanterade tenantens ID och dess apiHost.

Fastställ brandväggens ID

Brandväggslistan visar namn, hostname, serienummer, firmware och 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'

Använd UUID:t för rätt brandvägg och välj inte endast utifrån ett liknande visningsnamn:

FIREWALL_ID="<firewall-uuid>"

Om brandväggen saknas ska tenant, region, Central-anslutning och hanteringsgodkännande kontrolleras först. Registreringen beskrivs i Anslut Sophos Firewall till Sophos Central.

Exportera konfigurationen

Starta en fullständig export

Exporten körs asynkront. Det första anropet returnerar därför endast ett transaktions-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"

Hämta statusen igen efter några sekunder:

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"

Upprepa anropet ungefär var tionde sekund tills status når sluttillståndet finished. pending och started är ännu inga fel.

Först när status: "finished" och result: "success" visas innehåller response.url den tidsbegränsade nedladdningsadressen:

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

TAR-filen kan innehålla känsliga nätverks-, användar-, VPN- och policyuppgifter. Förvara den skyddat eller radera den efter analysen. För en läsbar rapport eller en jämförelse före och efter ändringen kan filen Entities.xml i paketet användas i Sophos Firewall Config Studio.

Exportera endast valda konfigurationer

För en selektiv export måste entitetsnamnen anges exakt och med rätt skiftläge. Det här exemplet exporterar brandväggs- och NAT-regler med beroende objekt:

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"

Giltiga entitetsnamn finns i den aktuella export-endpointen för Sophos Firewall API. Vid selektiv export är standardvärdet för includeDependency false. Ange alternativet medvetet och kontrollera ändå det resulterande paketet.

Importera konfigurationen

Importen består av att begära en uppladdnings-URL, ladda upp TAR-filen, bekräfta filuppgifterna och kontrollera transaktionen. Exemplet använder endast en testbrandvägg och sätter avsiktligt performPartialImport till false. API-standardvärdet är true och tillåter en partiell import per brandvägg.

Kontrollera kompatibiliteten först: målbrandväggen behöver minst samma firmware- och Pattern-version. Sophos stöder selektiva importer mellan olika modeller endast från en lägre till en högre modell. Målhårdvaran måste ha minst lika många Ethernet-portar. Om portnamnen avviker måste Entities.xml anpassas före uppladdningen.

Förbered importfil och kontrollsumma

Förbered målfil, kontrollsumma och filstorlek:

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

På macOS:

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

På Linux:

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

Begär en uppladdningssession och ladda upp filen

Begär en uppladdningssession och visa endast fälten som inte är hemliga:

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"

Ladda upp filen före utgångstiden för den försignerade URL:en med den returnerade metoden PUT. Skicka inga JWT- eller tenant-headrar till denna URL:

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

Slutför importen och kontrollera status

Om paketet innehåller känslig information och importeras till en annan eller ominstallerad brandvägg behövs rätt Secure Storage Master Key. Utan den importerar SFOS inte känslig information eller konfigurationer som är beroende av den. Följande prompt visar inte hemligheten. Enter lämnar den tom:

read -r -s -p "Secure Storage Master Key, eller tryck Enter för att hoppa över: " SSMK
printf '\n'

Slutför uppladdningen och tilldela paketet till målbrandväggen:

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"

Ett anrop accepterar 1 till 25 unika brandväggs-ID:n. För ytterligare brandväggar måste paketet laddas upp på nytt. Återanvänd inte samma försignerade URL eller transaktions-ID.

Kontrollera importstatus via samma transaktions-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"

Upprepa även detta anrop ungefär var tionde sekund tills status: "finished" visas. Först då ska result och, vid flera mål, varje element i response.items utvärderas.

success bekräftar API-bearbetningen, inte den funktionella effekten.

Validera importen lokalt

Efter finished ska följande kontrolleras på varje målbrandvägg:

  1. Finns exakt de förväntade reglerna, objekten och inställningarna?
  2. Saknas användare, lösenord, certifikat eller beroende objekt på grund av en saknad eller felaktig SSMK?
  3. Stämmer gränssnitt, zoner, gateways, firmware, Pattern-version och hårdvarumodell med paketet?
  4. Fungerar routing, NAT, VPN, autentisering och hanteringsåtkomst enligt definierade testfall?
  5. Visar Audit Trail och konfigurationsloggar oväntade ändringar?
  6. Visar en ny export eller jämförelse i Config Studio endast de planerade skillnaderna?

Import/Export uppdaterar befintlig konfiguration och tar inte automatiskt bort allt som saknas i paketet. TAR-filen är därför varken ett fullständigt önskat tillstånd eller en ersättning för backup, återställning och funktionstest.

Felsökning

Exporten saknar nedladdnings-URL

URL:en visas först vid status: "finished" och result: "success". Vid error eller partialSuccess ska fälten i response kontrolleras. Fortsätt inte med en tom eller utgången URL.

HTTP 401 eller 403

Vid 401 har JWT:t oftast gått ut eller är ogiltigt. Autentisera på nytt. Vid 403 ska Central-rollen, tenant-kontexten, X-Tenant-ID och den regionala API-värden kontrolleras. Den lokala XML API-åtkomsten under /webconsole/APIController berör inte detta. Den behandlas separat i Säkra XML API-åtkomst i Sophos Firewall.

Upload-complete returnerar 400 eller 409

Kontrollera transaktions-ID, uppladdnings-URL:ens utgångstid, faktisk filstorlek, hexadecimal MD5-kontrollsumma och unika brandväggs-ID:n. Ändra inte den uppladdade filen efteråt. Skapa en ny uppladdningssession för ett nytt försök.

Importen slutar med error eller partialSuccess

Spara response och, vid flera målbrandväggar, även response.items. Om ett API-anrop returnerar ett separat 4xx- eller 5xx-felsvar ska dessutom error, message, code, correlationId och requestId dokumenteras. Kontrollera sedan målversion, Pattern-version, modell, portar, beroenden och SSMK lokalt. Om svaret från Central inte räcker ska fwcm-api-executor.log på brandväggen kontrolleras enligt Sophos Firewall-tjänster och loggfiler.

Transaktions-endpointen är avgörande för API-statusen. Utgå inte från att uppdraget visas i Sophos Central Firewall Task Queue.

En mycket stor import avbryts

Sophos listar Known Issue NR-19066: en import med mycket många objekt kan överskrida bearbetningsgränsen på två timmar. I stället för att upprepa den fullständiga importen oförändrad ska mindre selektiva paket skapas, importeras separat och varje steg valideras.

Ta bort känsliga variabler i slutet av sessionen:

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