Exportera och importera Sophos Firewall via Central API

Med SFOS 22.0 MR2 eller senare kan brandväggskonfigurationer exporteras och importeras via Sophos Central REST API i Sophos Fusion (tidigare Sophos Central). 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.

För direkt brandväggsåtkomst beskriver lokalt REST API och API-nycklar i SFOS 23.0 en annan väg. Dessa lokala administratörsnycklar ersätter inte molnets service principal, token, tenant eller regionala API-värd i denna artikel.

För en enskild manuell ändring direkt i lokal WebAdmin används i stället Exportera och importera konfiguration selektivt. Artikeln förklarar också Entities.xml, SSMK, objektberoenden och importens mergeeffekt.

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 Fusion;
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.

Credential-skapande, roller, Token- och whoami-kontrakt, region, secret-skydd, validering och gemensam felsökning finns centralt i Hantera Sophos Central API Credentials säkert. Slutför först den processen; artikeln återanvänder sedan SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID och SOPHOS_API_HOST.

API-autentiseringsuppgifter skapas i Sophos Fusion 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. Använd därefter den regionala apiHost som whoami returnerar för denna tenant för varje tenantspecifik begäran.

Mappa de tre värden som validerats av Owner-processen till variablerna som används här:

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

Begär inte JWT igen: JWT är det kortlivade Access Token som återanvänds ovan.

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.

Tenant-ID och regional API-värd kommer också från Owner-processen:

TENANT_ID och API_HOST är redan validerade. För Partner- eller Enterprise-Credentials måste de komma från den fullständigt sidindelade tenantlistan i Owner-processen.

Fastställ brandväggens ID

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

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

read -r -p 'Brandväggens UUID från godkänt inventarium: ' 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

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

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"

Entitetsnamn är exakta och skiftlägeskänsliga; exemplet använder FirewallRule och NATRule. Vid selektiv export är standardvärdet för includeDependency false; ställ in alternativet medvetet och kontrollera ändå det resulterande paketet.

Paketets omfattning och begränsningar

Före en API-import måste även följande SFOS-regler för TAR-filen beaktas:

En import uppdaterar befintliga inställningar. En inställning som saknas i paketet förblir oförändrad på målet. Om den finns i båda konfigurationerna gäller det importerade värdet.
Vid extern autentisering innehåller exporten endast användare som skapats manuellt på brandväggen. OTPTokens innehåller bara utfärdade tokens för dessa användare.
REDDevice inkluderar inte automatiskt den DHCP-server som krävs, inte ens med includeDependency. Exportera även DHCPServer eller återskapa DHCP-servern efter importen.
En importerad URL-lista får innehålla högst 128 domäner.
XGS 88w, 108w, 118w och 128w har ytterligare villkor för trådlösa konfigurationer, bland annat frekvensband, Security mode, Encryption, bryggor och antal unika SSID:n.

En TAR-listning som kan läsas utan fel visar därför bara att arkivet går att öppna. Den bekräftar inte att alla nödvändiga objekt finns med eller att de får effekt på målhårdvaran.

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:

Finns exakt de förväntade reglerna, objekten och inställningarna?
Saknas användare, lösenord, certifikat eller beroende objekt på grund av en saknad eller felaktig SSMK?
Stämmer gränssnitt, zoner, gateways, firmware, Pattern-version och hårdvarumodell med paketet?
Fungerar routing, NAT, VPN, autentisering och hanteringsåtkomst enligt definierade testfall?
Visar Audit Trail och konfigurationsloggar oväntade ändringar?
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.

Återställ efter en felaktig import

Om den lokala valideringen misslyckas ska utrullningen stoppas, transaktionssvaret sparas och resultatet inte döljas med fler importer. För återställning i lokal WebAdmin, gå till Backup and firmware > Backup and restore. Under Restore configuration väljer du den tidigare skapade backupen med Choose file, anger dess Encryption password och startar Upload and restore.

En återställning ersätter den aktuella konfigurationen, tar bort backupen som lagras på brandväggen och startar om brandväggen. Därefter blir WebAdmin-IP-adressen från den återställda konfigurationen aktiv. Se därför till att adressen och krypteringslösenordet finns tillgängliga före importen. Upprepa samma funktionstester efter omstarten och kontrollera med en ny export. Ändringar som gjorts efter backupen går förlorade.

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 Sophos Fusion-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 Sophos Fusion 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.

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