Säkra åtkomst till Sophos Firewall XML API

Sophos Firewalls XML API är praktisk för automatisering, övervakning, säkerhetskopiering, analyser och integrationer. 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.

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

XML API använder alltid HTTP POST till samma APIController för konfigurationsfrågor och ändringar. Om SFOS läser, skapar, uppdaterar eller tar bort definieras i XML-payloaden, inte i HTTP-metoden. 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. De allmänna kriterierna är =, != och like; enskilda statistikfrågor stöder ytterligare kriterier.

Om operation saknas i <Set> behandlar SFOS requesten som add. Det är inget ofarligt standardvärde: en request som var avsedd som uppdatering kan misslyckas eller arbeta på fel objekt. Ett valfritt alfanumeriskt transactionid gör det enklare att koppla samman request och response.

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.

Använd den officiella Postman-collectionen säkert

Sophos tillhandahåller en förberedd collection på https://docs.sophos.com/nsg/sophos-firewall/api-collections/sophosfirewall.postman_collection.json. Efter importen anpassas username, password, firewall-ip och firewall-port under Collection Variables till miljön. De inkluderade objektvärdena är 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.

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.

Överför eller exportera certifikat via API:t

Certifikat är ett specialfall eftersom filer överförs utöver XML. För att skapa eller uppdatera ett certifikat används i Postman Desktop en form-data-request med tre delar: certifikatfil, Private Key-fil och reqxml med en <Set><Certificate>...</Certificate></Set>-payload. 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.

En <Get><Certificate/></Get>-request returnerar inget normalt XML-resultat utan ett .tar-arkiv med certifikat, Private Keys och Entities.xml. Hämtningen fungerar därför inte som ett vanligt Postman-response; Sophos dokumenterar en webbläsare eller Linux-kommandorad. Arkivet är mycket känsligt: hämta det endast från en tillåten managementhost, lagra det krypterat med begränsad åtkomst, extrahera det på en kontrollerad plats och ta säkert bort kopior som inte längre behövs. Credentials i URL, webbläsarhistorik, processlista eller proxylogg är en separat risk som den valda hanteringen av secrets och exekveringsmetoden måste förebygga.

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. Om åtkomsten bara behövs tillfälligt, begränsa Access time.
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.

Sophos stöder de officiella API:erna och oförändrade exempelskript. Egna integrationer, wrappers och automationer behöver ändå en intern ägare, tester och ett rollback-koncept. ”Fungerar i labbet” räcker inte för produktiva skrivoperationer.

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.

I Known Issues-listan finns ett särskilt SFOS 22-fall dokumenterat: 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 kan i vissa fall bete sig annorlunda. För drift är det viktigt att inte dra slutsatsen “stäng av MFA överallt”, utan att separera API-konton på ett rent sätt.

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: Spårbarhet och skadeomfång 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.

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: SFOS behandlar requesten som add trots att en uppdatering var planerad.
• Usage Count tolkades som en fullständig beroendelista: Statistiken returnerar antal och namn, men inte berörda regler eller profiler.
• 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.

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.
• Frigör inga breda 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.
• 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 förändringsbiljetter.
• Testa automationsprocesser efter firmwareuppdateringar.

FAQ