Säkra åtkomst till Sophos Firewall XML API

Sophos Firewalls XML API är praktisk för automatisering, övervakning, säkerhetskopiering, analyser och integrationer. Det går även att tillämpa samma konfiguration reproducerbart på flera brandväggar när processen är tydligt avgränsad och testad. Just därför utgör den också en del av hanteringsytan för attacker. Att tillåta API-åtkomst ger ett system möjlighet att läsa konfigurationsdata eller, beroende på behörighet, göra ändringar.

API-åtkomst bör därför inte tillåtas brett från interna nätverk eller från godtyckliga källor. Det är bättre med en liten, dokumenterad uppsättning av hanteringsnätverk, automationsvärdar eller fasta partneråtkomster.

Sedan SFOS 22 har Sophos utökat API-åtkomstkontrollen. API access settings finns under Administration > API access, och tillåtna källor kan definieras som IP-värdar. Detta gör det möjligt att modellera inte bara enskilda IP-adresser, utan även IP-områden och nätverk på ett korrekt sätt.

I äldre SFOS-versioner fanns API-konfigurationen under Backup and firmware > API. Ta hänsyn till den ändrade menysökvägen när äldre instruktioner jämförs.

När XML API-åtkomst är meningsfull

XML API är ingen standardåtkomst för vanligt administrativt arbete. Det är meningsfullt att använda den när det finns en konkret teknisk process bakom.

Typiska användningsfall:

• Övervakning eller inventering.
• Automatiserade konfigurationskontroller.
• Säkerhetskopierings- eller dokumentationsprocesser.
• MSP- eller integrationsplattformar.
• Skript för återkommande administrativa uppgifter.
• Förberedda ändringar från verktyg som Sophos Firewall Config Studio.

Om en process kan fungera utan API bör API-åtkomst inte förbli aktiverad i förebyggande syfte. Varje ytterligare gränssnitt behöver en ägare, en källa, ett åtkomstkoncept och en kontroll.

Vad som har ändrats med SFOS 22

Med SFOS 22 har XML API-åtkomstkontrollen blivit betydligt mer hanterbar:

• API access settings har flyttats till menyn Administration > API access.
• API access är inaktiverad som standard och måste aktiveras medvetet.
• API-åtkomst kan begränsas till IP-värdar.
• Som källor kan IP-adresser, IP-områden och nätverk användas.
• Upp till 64 IP-värdar kan tillåtas.
• Vid uppgradering omvandlas tidigare tillåtna IP-adresser automatiskt till IP-värdobjekt.
• Migrerade objekt får prefixet apiconfig.

Detta är användbart för driften eftersom API-källor inte längre behöver hanteras som lösa enskilda adresser. Man kan namnge ett hanteringsnätverk, en automationsvärd eller en dedikerad värdgrupp korrekt och senare känna igen dem i granskningar.

Grundregel: tillåt API endast från definierade källor

API access bör behandlas som WebAdmin eller SSH: så snävt som möjligt, så brett som nödvändigt.

Lämpliga källor är till exempel:

• en dedikerad automationsserver,
• ett monitoreringssystem,
• en host för konfigurationshantering,
• ett internt managementnät,
• ett VPN- eller adminnät,
• en tydligt definierad partner- eller MSP-källadress.

Olämpliga källor är:

• hela klientnät,
• gäst- eller IoT-nät,
• Any,
• otydliga undantag som “hela servernätet”,
• temporära test-IP-adresser som senare glöms bort.

Om externa tjänsteleverantörer behöver API-åtkomst bör källan definieras så specifikt som möjligt. Det bör också dokumenteras vad åtkomsten används till och när den tas bort.

Rekommenderad procedur

Den exakta UI-sökvägen kan variera något beroende på SFOS-version. I SFOS 22 finns API-konfigurationen under Administration > API access.

Praktisk procedur:

1. Kontrollera vilket system som behöver API-åtkomst.
2. Under Hosts and services > IP host, skapa ett tydligt IP Host-objekt för systemet.
3. Om flera källor behövs, namnge IP Hosts, IP ranges eller nätverk tydligt.
4. Under Administration > API access, aktivera API access.
5. Under Allowed IP hosts, tillåt endast dessa objekt.
6. Klicka på Apply.
7. Lägg inte till breda klient- eller servernät.
8. Testa åtkomsten från den verkliga automations- eller monitoreringshosten, inte från administratörens laptop.
9. Ta bort källor som inte längre behövs.
10. Dokumentera ändringen i change-processen.

I befintliga installationer efter en uppgradering till SFOS 22 bör man dessutom söka efter objekt med prefixet apiconfig. Dessa objekt skapades från äldre API-allow-poster och bör kontrolleras, namnges om eller rensas.

Testa åtkomsten målinriktat

API-endpointen ligger vanligtvis på:

https://<Firewall-IP-eller-hostnamn>:<Port>/webconsole/APIController

Porten är HTTPS-porten för WebAdmin Console. Om adminporten har ändrats under Administration > Admin settings måste API-verktyget använda samma port. API:t arbetar med XML-payloads via HTTP POST, inte som ett klassiskt REST-API med separata GET-, POST-, PUT- och DELETE-endpoints.

HTTPS skyddar endast credentials tillförlitligt mot avlyssning och manipulation om klienten validerar brandväggens certifikat. Automationssystemet bör därför använda namnet i certifikatet, lita på utfärdande CA och avbryta vid certifikat- eller hostnamnsfel. Alternativ som curl -k kringgår denna kontroll och hör inte hemma i produktionsjobb.

Ett meningsfullt test svarar inte bara på om inloggning är möjlig. Det bör visa om rätt källa är tillåten, om kontot får utföra den nödvändiga operationen och om resultatet kan spåras i audit- eller change-processen.

För acceptans bör dessa punkter kontrolleras separat:

• Källa: Testet körs från den verkliga automations-, monitorerings- eller integrationshosten, inte från administratörens laptop.
• Åtkomst: Brandväggen accepterar käll-IP endast om matchande IP Host-objekt är tillåtet i API access.
• Negativt test: Skicka samma ofarliga läsbegäran från en kontrollerad testvärd som avsiktligt saknas under Allowed IP hosts och verifiera att API:t avvisar den utan att returnera konfigurationsdata. Lätta inte på och ta inte bort ett produktionsundantag enbart för att skapa detta testfall.
• Konto: API- eller servicekontot har endast nödvändiga rättigheter.
• Secret: Användarnamn, lösenord eller token hamnar inte i shell-historik, tickets, chattar eller skärmbilder.
• Audit: Åtkomsten eller ändringen är spårbar i audit- eller change-processen.
• Rollback: Före skrivoperationer finns backup, rollbackpunkt och ett ofarligt lästest.

curl-exempel med användarnamn och lösenord i URL:en kopieras snabbt och är senare svåra att få bort ur loggar. Bättre är ett kort test med dedikerat servicekonto, temporärt test-secret, säker lagring och efterföljande rotation om ett secret har använts i en osäker kontext.

För strukturerade tester är en Postman-collection ofta renare än ett snabbt kopierat shell-kommando. Även där bör brandväggsadress, port, användarnamn, lösenord och objektvärden hanteras som variabler eller secrets, inte hårdkodas i requests, skärmbilder eller tickets. Collectionen är inget säkerhetskoncept, men hjälper till att testa läs- och skrivoperationer mer reproducerbart.

Ett nåbart API är ännu inget bevis för att den planerade ändringen är tekniskt säker. Före produktiva skrivoperationer bör därför först en ofarlig läsfråga fungera och därefter en liten, kontrollerad ändring testas.

Bygg och utvärdera XML-requests medvetet

Versionsgräns: SFOS 22-instruktionerna nämner webbläsare som XML-klienter. Från SFOS 23.0 utesluter den specifika sändningsinstruktionen för XML-förfrågningar uttryckligen webbläsare; använd Postman eller en kontrollerad Linux-kommandorad för dessa POST. Den allmänna XML-översikten nämner fortfarande webbläsare, men tillåter därmed inte webbläsar-POST i SFOS 23.0. Lokalt REST API med administratörsnycklar är ett separat gränssnitt, inte en ny autentisering för dessa XML-payloads.

Konfigurationsfrågor och ändringar här använder HTTP POST till samma APIController. Läsning, skapande, uppdatering eller borttagning definieras i XML-payloaden, inte i HTTP-metoden. XML <Get> betyder läsning, inte automatiskt HTTP GET; även Object Usage-frågan kallad ”API GET request” skickas via HTTP POST. Certifikatexport nedan är ett separat dokumenterat HTTP GET-undantag. Den yttre strukturen består av <Request>, <Login> och exakt den operation som behövs:

• <Set operation="add"> skapar objekt, regler eller policies som stöds.
• <Set operation="update"> ändrar inställningar som inte kan skapas som nya objekt.
• <Get> läser konfigurationer eller statusdata.
• <Remove> tar bort objekt som stöds. Fasta inställningar som SSL/TLS Inspection-konfigurationen kan inte tas bort, utan endast uppdateras.
• <Filter> begränsar en läsfråga. Den allmänna XML-referensen dokumenterar endast objektnamnet Name, med kriterierna =, != och like och skrivsättet <key name="Name" ...>. Den separat dokumenterade Object Usage-statistiken stöder ytterligare nycklar och kriterier; använd inte dessa för vanliga objektfrågor.

Förlita dig inte på att operation kan utelämnas på <Set> vid skrivoperationer. Dokumentationen ger motstridiga beskrivningar av det utelämnade värdet: XML-översikten anger add, medan den fullständiga XML-referensen för SFOS 22 och 23 anger Add följt av Update. Detta visar varken ett testat standardbeteende med enbart Add eller ett generellt upsert- eller överskrivningsbeteende. Använd endast en explicit operation som API help bekräftar för det aktuella objektet och den installerade builden; om detta förblir oklart ska skrivbegäran inte utföras, utan frågan klargöras med Support. APIXMLTags dokumenterar det valfria alfanumeriska attributet transactionid på <Set>; det gör det enklare att koppla samman begäran och svar. För specialiserade operationer är objektexemplet i API help för den installerade SFOS-builden vägledande. Certifikatexemplet placerar transactionid på <Certificate>; detta specialfall är ingen allmän regel för placering på objekttaggar inuti <Set>.

APIVersion i <Request> är versionsspecifikt: XML-referensen för SFOS 22 visar 2200.1, och den för SFOS 23 visar 2300.1. Dessa är dokumentationsexempel, inte en rekommendation att använda värdet på varje build. Enligt referensen innehåller APIVersion i <Response> det värde som angavs i begäran; om värdet utelämnas i begäran beaktas API-versionen för den aktiva firmwaren. Samtidigt beskriver avsnittet om begäran versionsangivelsen som nödvändig, medan senare exempel utelämnar den. Denna interna motsägelse bevisar varken att angivelsen alltid är obligatorisk eller att den alltid är valfri vid körning. Exakta objekttaggar, attribut, statuskoder och exempelkonfigurationer måste därför hämtas från API help för den installerade SFOS-builden; bekräfta version och objektkompatibilitet före användning och överför inte payloads mellan versioner utan kontroll.

En liten läsfråga har följande struktur:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader och SECRET är platshållare. Det verkliga secretet hör hemma i verktygets skyddade secret store, inte i en XML-fil i repositoryt. Testet är godkänt först när responsen innehåller förväntat innehåll under <Response> och en lämplig status under <Status>. Ett lyckat HTTP-anrop eller Send successful i Postman bevisar inte i sig att SFOS utförde avsedd operation. Vid skrivoperationer ska även målobjektet i WebAdmin och ändringen i Audit Trail kontrolleras.

Följande värden är dokumenterade XML-statuskoder i attributet code på <Status>, inte HTTP-statuskoder. Meddelandet och Status Message Information för det aktuella objektet i den installerade builden avgör den exakta tolkningen:

• 200: konfigurationen har tillämpats; 201: endast delvis lyckad operation. Vid 203 lyckades operationen, men vissa konfigurationer tillämpades inte; referensen hänvisar till Support. 204–210 innebär att operationen delvis misslyckades, inte att den lyckades fullt ut.
• 211–215: varningar; 216: lyckad operation med objektspecifik förklaring. Läs respektive Status Message Information för båda fallen i stället för att behandla alla XML-2xx-värden som en fullständigt lyckad konfigurationsändring.
• 500: operationen kan inte utföras på objektet; 501: parametervalideringen misslyckades; 502: namnet finns redan; 503: samma parametrar finns redan. Vid 504–510 hindrar en referens från ett annat objekt borttagningen; kontrollera först beroendena. För 511–520 kräver referensen ett klargörande med Support.
• 521: begäran är inkompatibel med aktuell API-version; 522–525: objektgränsen har nåtts; 526: posten saknas; 528: standardobjekt som inte kan redigeras; 529: ogiltig XML för objektet; 530: API-versionen stöds inte för detta objekt. 541–590 är objektspecifika fel med ytterligare information under Status Message Information; 599 innebär att behörighet att skapa eller ändra saknas.

Vid delvis lyckad operation eller varningar ska svaret jämföras med objektets faktiska tillstånd före ett nytt skrivförsök; anta inte att allt har tillämpats eller att ett nytt försök är riskfritt. Dela endast rensade svar och loggar med Support.

Använd den officiella Postman-collectionen säkert

Ladda ner och importera den aktuella Postman-samlingen. Samlingen täcker bara en del av de requesttyper som stöds; brandväggens lokala API help visar hela uppsättningen operationer samt buildspecifika exempelkonfigurationer och entitetsdefinitioner. Före den första requesten ska alla fyra medföljande exempelvärden apiadmin, Admin@12345, 172.16.16.16 och 4444 under Collection Variables ersättas med miljöns username, password, firewall-ip och firewall-port. De inkluderade objektvärdena är också exempel och får inte skickas utan kontroll.

För en egen request används metoden POST, endpointen ovan och nyckeln reqxml under Body > form-data. Testa först Authenticate > Sign in och därefter en ofarlig <Get>-fråga. Först när källa, konto, response och audit stämmer ska en liten skrivoperation med förberedd rollback följa.

Känsliga XML-importer: Kontrollera före import av lösenord eller andra känsliga värden i API help för den installerade builden om den aktuella operationen kräver SecureStorageMasterKey och attributet Token på <Request>, och vilka indata som är giltiga. I POST-exemplet för SFOS 23 är SecureStorageMasterKey ett separat fält i begärans body; Token finns på <Request> i XML-innehållet i bodyfältet reqxml. Skicka endast de indata som bekräftats för operationen på de godkända platserna i POST-body/XML. Håll i detta arbetsflöde nycklar, lösenord och token borta från URL:er, shellhistorik och loggar; detta innebär inte att varje XML-fråga kräver en token.

Vad gäller ursprunget beskriver XML-referensen SecureStorageMasterKey som huvudnyckeln för källbrandväggen, från vilken konfigurationen exporterades. Utan denna nyckel importeras enligt referensen inte känslig information som lösenord eller de inställningar som är beroende av den; om nyckeln saknas hänvisar referensen till standardadministratören med användarnamnet admin. Token och krypterade lösenordsvärden kommer från det dokumenterade Get-/exportresultatet. Markeringen hashform="mode1", exempelvis på <Password>, beskriver där ett krypterat lösenordsvärde; referensen anger ett okrypterat lösenord som alternativ. Detta är information om ursprung och tolkning, inte ett tillstånd att kopiera chiffertext, token eller markörer mellan godtyckliga objekt och builds. XML-<Get> tillåter inte automatiskt HTTP-metoden GET. Här införs inget nytt import- eller exportkommando; objektspecifik och buildspecifik bekräftelse samt det följande kravet att stoppa vid oklara indata gäller fortfarande.

Dokumentationen innehåller också fortfarande ett motstridigt URL-exempel för huvudnyckeln. Utför inte den känsliga importen så länge en källkonflikt, nödvändiga indata eller deras tolkning för den installerade builden är olösta; be Support om ett klargörande. Den separat skyddade certifikatexporten via HTTP GET nedan förblir ett eget undantag.

En exporterad collection kan innehålla credentials eller miljövärden. Rensa collectioner innan de delas, lagra inte secrets i klartext som Initial Values och rotera testlösenord efter en läcka.

Fråga efter Object Usage före ändringar

API:t kan returnera namn och Usage Count för objekt som stöds. Då används statistiktaggar som <IPHostStatistics> i stället för den vanliga objekttaggen. Ett filter på namn för IP Hosts ser till exempel ut så här:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

SFOS 22 stöder denna användningsfråga för IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts och grupper, Country Groups, Services och Service Groups samt Interfaces, Zones, Gateways och SD-WAN Profiles. Namnfilter stöder bland annat like, not like, startswith, in, = och !=; Usage Count stöder dessutom >, >= och listor med tal via in.

Responsen innehåller för närvarande bara objektnamn och antal användningar, inte beroende konfigurationer. Ett Usage Count på 3 visar alltså inte vilka tre regler eller profiler som berörs. Kontrollera före en update- eller remove-operation även Object usage i WebAdmin eller Config Studio. Ett värde på 0 är inte heller tillstånd för okontrollerad borttagning: backup, beroendekontroll och ett begränsat test är fortsatt obligatoriska.

I WebAdmin visas Usage för gränssnitt, zoner, gateways, SD-WAN-profiler samt värdar och tjänster. Räknaren uppdateras en gång per dag; uppdatera den med kontrollen bredvid Usage före en ändring. Klicka på objektets användningsantal, expandera rätt kategori och öppna den angivna regeln eller policyn för att ersätta eller ta bort objektet där. Då tas referensen bort, inte automatiskt själva objektet. Vissa WAN-gateway- och CLI-konfigurationer kan inte redigeras från Object Usage-fönstret; använd respektive konfigurationssida eller CLI.

Logga in och ut Live Users via API:t

SFOS kan logga in eller ut en användare som Live User via API:t. Det passar för en integration med ett externt autentiseringssystem där ansvaret är tydligt definierat, men är ingen allmän genväg runt normal användarinloggning. En felaktig inloggning kopplar trafik till en identitet och kan därför påverka användarbaserade firewall- eller webregler.

För administratören som utför operationen måste Manage live users under Profiles > Device access > Identity vara inställt på Read-write. Den avsedda endpointen är:

https://<Firewall-IP-eller-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Den här endpointen behandlar in- och utloggningar parallellt. Den allmänna APIController kan behandla samma operationer seriellt. En befintlig integration bör därför inte migreras utan test enbart på grund av denna skillnad i beteende.

En payload för inloggning kan se ut så här:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

För utloggning skickas samma logiska användare med LiveUserLogout:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 och MAC-adressen är exempelvärden. Användarnamn, IP-adress och MAC-adress måste stämma med den faktiska sessionen. Lagra admin-secret i verktygets skyddade secret store och skicka det i HTTP POST-body, inte i en URL, shellhistorik, loggfil eller delad collection.

Efter inloggning måste användaren visas under Current activities > Live users med Client type API client. Ett kontrollerat test verifierar därefter det förväntade beslutet i den användarbaserade regeln. Efter utloggning får sessionen inte längre listas som aktiv API-klient. Om användaren fortfarande visas kontrolleras först payload, användarnamn, IP-adress, MAC-adress och API-response; logga inte på chans ut en annan Live User-session.

Överför eller exportera certifikat via API:t

Skapa i Postman en begäran via New > HTTP Request, namnge den med Save och spara den i en samling. Använd POST och ovanstående APIController-endpoint med den faktiska WebAdmin-porten. Desktopappen skickar som standard från denna dator; tillåt dess käll-IP så som brandväggen ser den. Skapa under Body > form-data en namngiven File-post för certifikatet och en för den privata nyckeln, och välj de lokala filerna; den tredje posten, reqxml, är Text. Förvara filerna lokalt med begränsad åtkomst, inte i en molnsynkroniserad mapp.

Postman-exemplet använder C:/Users/[yourname]/Postman/files som lagringsplats i Windows. Ersätt [yourname] och kontrollera åtkomstbegränsningar och appens lokala filåtkomst; sökvägen är ingen generell SFOS-parameter.

⚠️ Tillverkarexempel för dokumentation, får inte köras: Följande PEM-certifikatpayload för reqxml utelämnar operation på <Set>. Skicka den inte på grund av de motstridiga beskrivningarna av standardbeteendet, inte ens för att skapa ett nytt certifikat. Klargör först den explicita operationen och den fullständiga certifikatpayloaden för objektet och den installerade builden i API help eller med Support. Alla kontonamn, hemligheter, objektnamn och filnamn är exempelvärden:

<Request><Login><Username>api-certificates</Username><Password>SECRET</Password></Login><Set><Certificate transactionid="10"><Name>TestCertificate</Name><Action>UploadCertificate</Action><CertificateFormat>pem</CertificateFormat><CertificateFile>TestCertificate.pem</CertificateFile><PrivateKeyFile>TestCertificate.key</PrivateKeyFile></Certificate></Set></Request>

CertificateFile och PrivateKeyFile anger de valda uppladdningsfilerna. Det valfria transactionid används här för att koppla samman begäran och svar. Att operation saknas bevisar varken att ett objekt skapas eller att det uppdateras; tillverkarexemplet, som bevaras oförändrat, får inte användas förrän objektets och buildens krav har klargjorts. Kontrollera särskilt för ett befintligt certifikat den exakta uppdateringspayloaden i API help och skicka inte blint på nytt. Skicka en bekräftad payload först efter detta klargörande; granska därefter svaret under Body och kontrollera sedan målcertifikatet i WebAdmin.

Certifikat är ett specialfall eftersom filer överförs utöver XML. För en bekräftad payload som skapar eller uppdaterar används i Postmans desktopapp en form-data-begäran med tre delar: certifikatfil, fil med privat nyckel och reqxml med den bekräftade explicita operationen på <Set> och tillhörande <Certificate>-fält. Den förkortade strukturen i exemplet som inte får användas är ingen körbar mall. Filnamn, format, åtgärd och certifikatnamn i XML måste stämma med de uppladdade filerna.

Private Keys hör endast hemma på den skyddade admin-endpointen och får aldrig hamna i en cloud collection, ett ärende eller ett repository. Efter Send utvärderas först <Response> och <Status>; kontrollera därefter under Certificates > Certificates att exakt det förväntade certifikatet, matchande nyckel och rätt kedja finns. Tilldelning och tjänstetest följer proceduren Importera och tilldela certifikat på Sophos Firewall. Hela automationsvägen från offentlig CA via buildspecifik uppladdning till tjänstetilldelning och extern kontroll beskrivs i Förnya ett Sophos Firewall-certifikat via XML API och kontrollera tjänster.

En <Get><Certificate/></Get>-request ger ett .tar-arkiv med certifikat, Private Keys och Entities.xml, inte ett normalt XML-resultat. Den fungerar därför inte som vanligt Postman-svar. Den särskilda instruktionen dokumenterar HTTP GET från Linux eller webbläsare; båda varianterna placerar credentials i URL:ens reqxml.

SFOS 23.0: Denna GET-instruktion nämner ännu webbläsare medan POST-instruktionen utesluter dem. Det bevisar varken ett förbud mot alla HTTP GET eller en webbläsarexport testad på denna firmware. För inte över äldre webbläsarinstruktioner och anta inte att POST ger samma nedladdning. Verifiera före export med Support eller i ett godkänt testsystem CLI GET-sökvägen och säker credentialhantering för installerad build; utför inte exporten utan verifiering.

Använd för verifierad export endast ett tillfälligt, begränsat konto på en skyddad värd, logga inte URL eller kommando och rotera sedan hemligheten. Validera TLS-certifikat och värdnamn; för inte över -k från tillverkarexempel till produktion. Arkivet är mycket känsligt: lagra krypterat med begränsad åtkomst, extrahera kontrollerat och ta säkert bort onödiga kopior.

Välj vid en godkänd CLI-export en uttrycklig lokal utdatasökväg för filename.tar. Granska före extrahering innehållet med tar -tf filename.tar; acceptera inte oväntade sökvägar eller länkar. Extrahera med tar -xvf filename.tar endast i en tom målkatalog med begränsad åtkomst. filename.tar är ett exempelvärde. Utdata från dessa kommandon kan avslöja känsliga filnamn och hör inte hemma i offentliga loggar.

API-åtkomst och användarrättigheter

En käll-IP ensam är inget fullständigt säkerhetskoncept. Begränsningen begränsar bara varifrån API:n är tillgänglig. Dessutom måste det vara klart med vilket konto API-åtkomst sker och vilka rättigheter detta konto har.

För produktiva miljöer bör man kontrollera:

• Används ett eget API- eller servicekonto?
• Har kontot endast de nödvändiga behörigheterna?
• Är det tydligt dokumenterat vilken person eller vilket team som är ansvarigt för kontot?
• Lagrar man lösenordet eller hemligheten säkert?
• Tas åtkomsten bort när integrationen inte längre används?
• Är ändringar spårbara via granskningsloggar?

Delade administratörskonton är problematiska för API-processer. Om flera system eller personer använder samma konto blir spårbarheten svagare. För förändringsanalyser är Sophos Firewall Audit Trail Logs granska relevant.

För ett dedikerat API-konto är ett snävt arbetssätt bättre än en snabbt kopierad full admin. Den allmänna planeringen av personliga konton och begränsade profiler beskrivs i Konfigurera administratörer och profiler säkert på Sophos Firewall; för automationer är det separata servicekontot som beskrivs här fortfarande avgörande. I Sophos-dokumentationen förekommer detta som Allow API access to administrators: det är inte bara källan som tillåts, även administratören eller profilen måste ha rätt åtkomst.

1. Skapa en administratörsprofil med nödvändiga rättigheter under Profiles > Device access.
2. Skapa en administratörsanvändare för API-processen under Authentication > Users.
3. Tilldela rätt administratörsprofil.
4. För tillfällig API-åtkomst, utse en ansvarig och planera manuell borttagning av det dedikerade API-kontot och/eller den dedikerade API-källauktoriseringen när den godkända perioden löper ut; kontrollera sedan att denna API-åtkomst faktiskt har återkallats utan att legitim delad åtkomst inaktiveras. Access Time för vanliga användare styr internetåtkomst; Schedule for device access för administratörer styr WebAdmin-inloggningar. Ingen av inställningarna är här dokumenterad som automatisk utgång av XML-API-åtkomst: förlita dig inte på dem för att avsluta API-åtkomst. Om ett tidsschema måste kunna upprätthållas, inhämta först bekräftelse i primärdokumentationen för den installerade versionen eller genom en auktoriserad verifiering.
5. Om möjligt, begränsa Login restriction for device access till de avsedda källorna.
6. Tillåt därefter API access och Device Access för rätt källa.

I det officiella exemplet får profilen Read-write för Objects och Network. Det är ingen generell rekommendation: för integrationer med endast läsbehörighet och andra API-uppgifter står onödiga områden kvar på None eller Read-only; skrivbehörighet tilldelas först efter ett kontrollerat lästest.

Sophos stöder de officiella API:erna och oförändrade exempelskript. Sophos tekniska support ger inte rådgivning eller felsökning för anpassade integrationer; Sophos hänvisar sådant arbete till ansvarig Sophos Partner eller Sophos Professional Services. Egna integrationer, wrappers och automationer behöver därför en intern ägare, tester och ett rollback-koncept. ”Fungerar i labbet” räcker inte för produktiva skrivoperationer.

Profilrättigheter är inte källauktorisering: Profiler under Profiles > Device access gäller WebAdmin och API; den lokala tjänste-ACL:n under Administration > Device access är en annan kontroll. Standardprofiler kan inte redigeras. Använd Edit för att visa rättigheterna; skapa och redigera en egen profil för anpassade rättigheter. Ta bort profilens tilldelning från alla administratörer innan profilen raderas. Varje område stöder None, Read-only och Read-write. Med None är konfigurationen varken synlig i WebAdmin eller åtkomlig via API:t; saknade API-data innebär därför inte automatiskt ett nätverksfel.

Standardprofilerna har olika omfattning: Administrator, inklusive standardkontot admin, har full WebAdmin-/CLI-åtkomst, alla API-begäranstyper och kan skapa administratörer. Audit admin har Read-write för loggar och rapporter; Crypto admin för säkerhetscertifikat. HAProfile har Read-only-åtkomst till Auxiliary-enheten när HA är konfigurerat. Security admin har Read-write för alla funktioner utom profiler, loggar och rapporter. Anta inte att någon av dessa är en API-profil med minsta möjliga behörighet; kontrollera de effektiva rättigheterna för objektet som behövs.

MFA och API-användare efter SFOS 22

MFA är viktigt för interaktiv administratörsåtkomst. För API- och automationsprocesser måste man däremot planera hur autentiseringen ska fungera. Ett skript, monitoreringsverktyg eller integrationssystem kan inte utan vidare ange en OTP-kod om användaren kräver MFA.

Den aktuella Known Issues-listan dokumenterar NC-177609 för SFOS 22.0.0 GA Respin Build 411: efter en uppgradering kan API-baserade konfigurationsändringar misslyckas för migrerade användare om MFA är aktivt och ingen one-time token skickas med. Icke-migrerade användare behåller det tidigare beteendet tills MFA-onboarding genomförs. Den officiella workarounden är ett separat API-konto utan MFA eller att undanta kontot från MFA. Detta är inget skäl att stänga av MFA för interaktiva administratörer; kontrollera först Release Notes och Known Issues för nyare builds.

Rekommenderad metod:

1. Använd ett eget servicekonto för API-processer.
2. Ge kontot endast nödvändiga rättigheter.
3. Begränsa dessutom API access till fasta IP Hosts eller managementnät.
4. Kontrollera om MFA är tekniskt och operativt rimligt för kontot.
5. Om MFA inte är praktiskt för API-kontot, kontrollera kontot särskilt strikt via källa, rättigheter, secret-lagring och audit trail.
6. Efter en SFOS 22-uppgradering, testa alla API-processer med läs- och skrivoperationer.

⚠️ API-användare utan MFA är ingen fribiljett för breda rättigheter. Om ett API-konto av tekniska skäl måste köras utan MFA måste käll-IP, rättigheter, lösenordslagring, ansvar och spårbarhet kontrolleras striktare.

Detta är särskilt viktigt för automationer som inte bara läser utan även ändrar konfiguration.

Före produktiva API-ändringar bör minst tre saker kontrolleras:

• En aktuell Sophos Firewall-backup finns.
• Det planerade API-kontot kan utföra en ofarlig läsfråga utan fel.
• Vid förberedda massändringar från Sophos Firewall Config Studio fungerar de genererade API- eller curl-anropen med det planerade kontot.

Avgränsning till Device Access

API-åtkomstkontroll är inte detsamma som Device Access. Device Access styr lokala brandväggstjänster som WebAdmin, SSH, User Portal, VPN Portal, DNS eller Ping. API access settings styr däremot åtkomsten till hanteringsgränssnittet för XML API.

Viktigt: Device Access-behörigheterna för WebAdmin Console gäller också för API-åtkomst. I praktiken betyder det att API access måste vara tillåten, källan måste vara godkänd i API access settings och lokal hanteringsåtkomst till brandväggen får inte blockeras av Device Access. Trots detta hör båda ämnena ihop för att stärka hanteringen. Varje lager begränsar en annan del av attackytan:

• Konfigurera Device Access korrekt: lokala brandväggstjänster som WebAdmin, SSH, User Portal, VPN Portal, DNS eller Ping
• API access control: IP-värdar som dessutom får använda XML API
• Aktivera MFA för Sophos Firewall WebAdmin, VPN Portal och Remote Access: interaktiva inloggningar för WebAdmin, VPN Portal och Remote Access
• Namngivna administratörer och tydliga roller: förbättrar spårbarheten och begränsar skadeomfånget för admin- och servicekonton.

Om ett adminnätverk får använda WebAdmin, SSH och API bör detta nätverk skyddas särskilt väl. En komprometterad klient i hanteringsnätverket är annars en direkt ingång till brandväggshanteringen.

För åtkomst från WAN bör HTTPS/WebAdmin inte aktiveras för hela WAN-zonen. Om extern API- eller administratörsåtkomst verkligen behövs ska en Local service ACL exception rule användas med en snävt avgränsad Source, lämplig Service HTTPS, fastställd regelposition och dokumenterad tidsperiod.

HA: verifiera åtkomst efter failover

I ett HA-kluster synkroniseras brandväggskonfigurationen från Primary till Auxiliary; den dedikerade HA-länken och Administration Ports synkroniseras inte. API-klienter bör därför använda det avsedda klusternamnet eller den delade gränssnittsadressen och inte omedvetet vara beroende av en nodspecifik administrationsadress.

Upprepa ett lästest och ett negativt test efter HA-konfiguration, certifikatbyte eller failover. Kontrollera DNS-upplösning, certifikatnamn, käll-IP, adminport, API access och Device Access. Ett synkroniserat hostobjekt bevisar inte i sig att hela nätverks- och TLS-vägen fungerar efter rollbytet.

Drift och granskning

API-åtkomst bör regelbundet granskas. Särskilt efter migrationer, tjänsteleverantörsbyten, automationsprojekt eller brandväggsuppgraderingar finns ofta gamla källor kvar.

Lämpliga granskningsfrågor:

• Vilka IP-värdar får för närvarande använda API-åtkomst?
• Finns det objekt med prefixet apiconfig?
• Är dessa objekt fortfarande nödvändiga?
• Stämmer namn och beskrivningar med det faktiska syftet?
• Finns det dokumenterade ansvariga?
• Beaktas API-åtkomst i en förändrings- eller granskningsprocess?
• Finns det en aktuell säkerhetskopiering före större API-baserade ändringar?

Innan API-baserade ändringar bör alltid en säkerhetskopiering finnas tillgänglig. Artikeln Skapa eller återställa säkerhetskopiering av Sophos Firewall beskriver vad man bör tänka på vid säkerhetskopiering, återställning och kompatibilitet.

Typiska fel

• API access tillåts för ett helt klientnät: Varje komprometterad klient i nätet kan nå API:t.
• Gamla apiconfig-objekt har inte kontrollerats: Migrerade äldre undantag förblir aktiva obemärkt.
• Servicekonto använder fulla adminrättigheter: Ett komprometterat secret får onödigt stor skadeverkan.
• API-automation använder en admin med MFA-krav: Skript eller verktyg kan misslyckas vid skrivoperationer efter SFOS-uppgradering.
• Fel port i verktyget: Admin-HTTPS-porten har ändrats, men verktyget använder fortfarande den gamla porten.
• REST-logik förväntas: Verktyget skickar REST-metoder i stället för XML-payload via HTTP POST till APIController.
• Endast HTTP-status kontrollerades: Den egentliga API-operationen misslyckades trots att transporten lyckades. Utvärdera <Response> och <Status>.
• Set skickades utan operation: Förlita dig inte på ett standardbeteende och upprepa inte begäran blint. De dokumenterade beskrivningarna motsäger varandra; bekräfta den explicita operationen för objekt och build före varje skrivning, annars ska processen stoppas.
• MFA-inställningar eller token kan inte importeras: Payloaden måste innehålla det tomma elementet <tokenid/>.
• En användare kan inte tas bort: Ange det exakta användarnamnet i <Remove>-payloaden som <Name>username</Name>. Kontrollera kontot, beroenden, backup och rollback innan requesten skickas.
• Usage Count tolkades som en fullständig beroendelista: Statistiken returnerar antal och namn, men inte berörda regler eller profiler.
• Live User loggades in utan sessionskorrelation: Användarnamn, IP-adress och MAC-adress stämmer inte med den faktiska sessionen, vilket kan ge felaktiga beslut i användarbaserade regler.
• Certifikatarkivet lagrades oskyddat: API-exporten kan innehålla Private Keys och hör inte hemma i Hämtade filer, ärenden eller delad lagring.
• Tillfällig leverantörs-IP ligger kvar: Extern åtkomst är möjlig längre än planerat.
• Ingen dokumentation av syftet: Senare administratörer vet inte om tillåtelsen fortfarande behövs.
• API-ändringar utan backup: Felaktig automation är svårare att rulla tillbaka.

Felsökning

Om ett verktyg inte når XML API bör man strukturerat kontrollera:

1. Stämmer käll-IP:n ur brandväggens perspektiv?
2. Är källan tillåten som IP-värd, IP-område eller nätverk?
3. Har ett apiconfig-objekt skapats efter en uppgradering men inte anpassats korrekt?
4. Tillåter Device Access lokal WebAdmin/API-åtkomst från denna zon?
5. Använder verktyget rätt brandväggsadress och rätt admin-HTTPS-port?
6. Stämmer användarnamn, lösenord eller hemlighet?
7. Har kontot de nödvändiga rättigheterna?
8. Tvingar kontot MFA, även om verktyget inte kan överföra en engångstoken?
9. Finns det routing-, NAT- eller proxy-effekter mellan verktyget och brandväggen?
10. Har åtkomsten avsiktligt tagits bort genom en härdningsåtgärd?
11. Testades åtkomsten från rätt källsystem eller bara från adminklienten?

Om en API-ändring har oväntade effekter, säkerställ först den senaste säkerhetskopieringen och kontrollera sedan granskningsspår, Config Studio-jämförelse och berörda brandväggsobjekt. Vid problem med live-trafik är Log Viewer och Packet Capture mer användbara än själva API:n.

Spara först <Response> och <Status> vid en avvisad eller felaktig XML-operation. Kontrollera därefter apiparser.log, validation.log och validationError.log under Diagnostics > Tools > Troubleshooting logs; Sophos kopplar filerna till API-översättning och API-validering. Sophos Firewall-tjänster och loggfiler beskriver filtrering och export. Ta bort secrets innan ett loggutdrag delas.

Checklista

Innan aktivering:

• Dokumentera syftet med API-åtkomsten.
• Bestäm källsystemet tydligt.
• Skapa IP-värdobjekt med beskrivande namn.
• Kontrollera servicekonto och behörigheter.
• Fastställ medvetet MFA-beteendet för API-kontot.
• Fastställ säkerhetskopierings- och återställningsprocess.
• Fastställ testmetod utan läckage av hemligheter.
• Dokumentera planerad XML-operation och förväntad <Status>.

Under drift:

• Tillåt API-åtkomst endast för definierade källor.
• Tillåt inte åtkomst från hela klient-, gäst- eller IoT-nätverk.
• Granska apiconfig-objekt efter uppgraderingar.
• Kontrollera tjänsteleverantörsåtkomster tidsmässigt och funktionellt.
• Lagra hemligheter skyddat och förnya vid personal- eller verktygsbyte.
• Rotera hemligheter om de har hamnat i shellhistorik, ärenden eller osäker lagring.
• Testa API-läs- och skrivoperationer specifikt efter SFOS-uppgraderingar.
• Kontrollera Object Usage och beroende konfigurationer före update- eller remove-operationer.
• Validera API-baserade Live User-inloggningar med API client, regelbeslutet och en korrekt utloggning.
• Hantera certifikatfiler, Private Keys och API-exporter endast på skyddade platser.

Vid granskning:

• Granska tillåtna API-källor regelbundet.
• Ta bort IP-värdar som inte längre behövs.
• Jämför ändringar med granskningsspår och ändringsärenden.
• Testa automationsprocesser efter firmwareuppdateringar.

FAQ