Securing Sophos Firewall XML API Access

The XML API of the Sophos Firewall is useful for automation, monitoring, backups, evaluations, and integrations. It can also apply the same configuration consistently to multiple firewalls when the process is narrowly scoped and tested. For this reason, it is also part of the management attack surface. Allowing API access gives a system the ability to read configuration data or make changes depending on permissions.

API access should therefore not be broadly allowed from internal networks or arbitrary sources. It is better to have a small, documented set of management networks, automation hosts, or fixed partner accesses.

Since SFOS 22, Sophos has expanded API access control. The API access settings are located under Administration > API access, and allowed sources can be defined as IP hosts. This allows not only individual IP addresses but also IP ranges and networks to be cleanly modeled.

In older SFOS versions, API configuration was located under Backup and firmware > API. Keep this changed menu path in mind when comparing older instructions.

When XML API Access is Useful

The XML API is not a standard access for normal admin work. Its use is sensible when there is a specific technical process behind it.

Typical use cases:

• Monitoring or inventory.
• Automated configuration checks.
• Backup or documentation processes.
• MSP or integration platforms.
• Scripts for recurring administrative tasks.
• Prepared changes from tools like Sophos Firewall Config Studio.

If a process can manage without the API, API access should not remain enabled as a precaution. Every additional interface needs an owner, a source, an access concept, and control.

What Changed with SFOS 22

With SFOS 22, XML API access control has become significantly more manageable for operations:

• The API access settings have been moved to the Administration > API access menu.
• API access is disabled by default and must be enabled deliberately.
• API access can be restricted to IP hosts.
• As sources, IP addresses, IP ranges, and networks are possible.
• Up to 64 IP hosts can be allowed.
• During the upgrade, previously allowed IP addresses are automatically converted into IP host objects.
• Migrated objects receive the prefix apiconfig.

This is helpful for operations because API sources no longer need to be maintained as loose individual addresses. A management network, an automation host, or a dedicated host group can be cleanly named and later recognized in reviews.

Basic rule: allow API only from defined sources

API access should be treated like WebAdmin or SSH: as narrow as possible, as broad as necessary.

Useful sources include:

• a dedicated automation server,
• a monitoring system,
• a configuration management host,
• an internal management network,
• a VPN or admin network,
• a clearly defined partner or MSP source address.

Not useful are:

• entire client networks,
• guest or IoT networks,
• Any,
• vague “whole server network” exceptions,
• temporary test IP addresses that are later forgotten.

If external service providers need API access, the source should be defined as specifically as possible. It should also be documented what the access is used for and when it will be removed.

Recommended procedure

The exact UI path can vary slightly depending on the SFOS version. In SFOS 22, the API configuration is under Administration > API access.

Practical procedure:

1. Check which system needs API access.
2. Under Hosts and services > IP host, create a clear IP Host object for this system.
3. If several sources are required, name IP Hosts, IP ranges or networks cleanly.
4. Under Administration > API access, enable API access.
5. Under Allowed IP hosts, allow only these objects.
6. Click Apply.
7. Do not add broad client or server networks.
8. Test access from the real automation or monitoring host, not from the admin notebook.
9. Remove sources that are no longer required.
10. Document the change in the change process.

For existing installations after an upgrade to SFOS 22, also search for objects with the apiconfig prefix. These objects were created from older API allow entries and should be checked, renamed or cleaned up.

Test access deliberately

The API endpoint is typically:

https://<Firewall-IP-or-hostname>:<Port>/webconsole/APIController

The port is the HTTPS port of the WebAdmin Console. If the admin port was changed under Administration > Admin settings, the API tool must use the same port. The API works with XML payloads over HTTP POST, not like a classic REST API with separate GET, POST, PUT and DELETE endpoints.

HTTPS only protects credentials reliably against interception and manipulation when the client validates the firewall certificate. The automation system should therefore use the name contained in the certificate, trust the issuing CA, and stop on certificate or hostname errors. Options such as curl -k bypass this check and don’t belong in production jobs.

A useful test does not only answer whether login is possible at all. It should show whether the correct source is allowed, whether the account may perform the required operation and whether the result remains traceable in the audit or change process.

For acceptance, check these points separately:

• Source: The test runs from the real automation, monitoring or integration host, not from the admin notebook.
• Access: The firewall accepts the source IP only when the matching IP Host object is allowed in API access.
• Negative test: From a controlled test host that is deliberately absent from Allowed IP hosts, send the same harmless read request and verify that the API rejects it without returning configuration data. Don’t weaken or remove a production allow entry just to create this test case.
• Account: The API or service account used has only the required rights.
• Secret: Usernames, passwords or tokens do not end up in shell history, tickets, chat logs or screenshots.
• Audit: The access or change is traceable in the audit or change process.
• Rollback: Before write operations, a backup, rollback point and harmless read test exist.

curl examples with username and password in the URL are quickly copied and later hard to remove from logs. A short test with a dedicated service account, temporary test secret, secure storage and later rotation is safer if a secret was used in an unsafe context.

For structured tests, a Postman collection is often cleaner than a quickly copied shell command. Firewall address, port, username, password and object values should also be maintained as variables or secrets there, not hardcoded in requests, screenshots or tickets. The collection is not a security concept, but it helps test read and write operations more reproducibly.

An API that is reachable is not proof that the planned change is technically safe. Before productive write operations, a harmless read query should work first, followed by a small, controlled change.

Build and evaluate XML requests deliberately

Version boundary: The SFOS 22 instructions list browsers as possible XML clients. From SFOS 23.0, the specific instructions for sending XML requests explicitly exclude browsers; use Postman or a controlled Linux command line for these POST requests. The general XML overview still mentions browsers. This does not authorize browser POST in SFOS 23.0. The local REST API with administrator keys is a separate interface, not a new authentication method for these XML payloads.

The configuration queries and changes shown here use HTTP POST to the same APIController. Whether SFOS reads, creates, updates, or deletes is defined in the XML payload, not in the HTTP method. XML <Get> denotes a read operation, not automatically HTTP GET; the Object Usage query described as an “API GET request” is also sent by HTTP POST. Certificate export below is a separately documented HTTP GET exception. The outer structure consists of <Request>, <Login>, and exactly the required operation:

• <Set operation="add"> creates supported objects, rules, or policies.
• <Set operation="update"> changes settings that can’t be created as new objects.
• <Get> reads configurations or status data.
• <Remove> deletes supported objects. Fixed settings such as the SSL/TLS inspection configuration can’t be removed, only updated.
• <Filter> limits a read query. The general XML reference documents only the object name Name, with the criteria =, !=, and like and the syntax <key name="Name" ...>. The separately documented Object Usage statistics support additional keys and criteria; do not apply these to ordinary object queries.

Do not rely on an omitted operation on <Set> for write operations. The documentation gives conflicting descriptions of the omitted value: the XML overview specifies add, while the complete XML reference for SFOS 22 and 23 describes Add followed by Update. This establishes neither a tested add-only default nor universally applicable upsert or overwrite behavior. Use only an explicit operation confirmed in API help for the specific object and installed build; if this remains unresolved, do not execute the write request and ask Support to clarify it. APIXMLTags documents the optional alphanumeric transactionid attribute on <Set>; it makes it easier to match a request with its response. For specialized operations, follow the object example in API help for the installed SFOS build. The certificate example places transactionid on <Certificate>; this exception is not a general rule for placing it on object tags inside <Set>.

APIVersion in <Request> is version-specific: the XML reference for SFOS 22 shows 2200.1, while the reference for SFOS 23 shows 2300.1. These are documentation examples, not a recommendation to use that value on every build. According to the reference, APIVersion in <Response> contains the value supplied in the request; if it is omitted from the request, the API version of the active firmware is considered. However, the Request section describes the version as necessary, while later examples omit it. This internal inconsistency establishes neither a universal requirement nor universal optionality at runtime. The exact object tags, attributes, status codes, and sample configurations must therefore come from API help for the installed SFOS build; confirm version and object compatibility before use, and do not transfer payloads unchecked between versions.

A small read request has this basic structure:

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

api-reader and SECRET are placeholders. The real secret belongs in the tool’s protected secret store, not in an XML file in the repository. The test is successful only when the response contains the expected content under <Response> and an appropriate result under <Status>. An HTTP success or Send successful in Postman alone doesn’t prove that SFOS performed the intended operation. For write operations, also check the target object in WebAdmin and the change in the audit trail.

The following values are documented XML status codes in the code attribute of <Status>, not HTTP status codes. The message and Status Message Information for the specific object in the installed build determine the exact interpretation:

• 200: configuration applied successfully; 201: only partially successful. For 203, the operation succeeded, but some configurations were not applied; the reference directs you to Support. 204–210 indicate partial failure, not complete success.
• 211–215: warnings; 216: success explained in the object-specific documentation. For both, read the relevant Status Message Information rather than treating every XML 2xx value as complete configuration success.
• 500: operation cannot be performed on the object; 501: parameter validation failed; 502: name already exists; 503: identical parameters already exist. For 504–510, a reference from another object prevents deletion; check dependencies first. For 511–520, the reference requires clarification with Support.
• 521: request incompatible with the current API version; 522–525: object limit reached; 526: record does not exist; 528: non-editable default object; 529: invalid XML for the object; 530: API version not supported for this object. 541–590 are object-specific errors with further details under Status Message Information; 599 indicates missing permission to create or modify.

For partial success or warnings, compare the response with the actual object state before attempting another write; do not assume that everything was applied or that a retry is harmless. Share only sanitized responses and logs with Support.

Use the official Postman collection securely

Download and import the current Postman collection. The collection covers only a subset of supported requests; the firewall’s local API help shows the complete set of operations and build-specific sample configurations and entity definitions. Before the first request, replace all four bundled example values apiadmin, Admin@12345, 172.16.16.16, and 4444 in Collection Variables with the environment’s username, password, firewall-ip, and firewall-port. The included object values are also examples and must not be sent without review.

For a custom request, use method POST, the endpoint shown above, and the key reqxml under Body > form-data. First test Authenticate > Sign in, followed by a harmless <Get> query. Only after source access, account, response, and audit are correct should a small write operation with a prepared rollback follow.

Sensitive XML imports: Before importing passwords or other sensitive values, check API help for the installed build to establish whether the specific operation requires SecureStorageMasterKey and the Token attribute on <Request>, and which inputs are valid. In the SFOS 23 POST example, SecureStorageMasterKey is a separate body input; Token is on <Request> in the XML of the reqxml body field. Supply only the inputs confirmed for that operation in the approved POST body/XML locations. Keep keys, passwords and tokens out of URLs, shell history and logs in this workflow; this does not mean every XML query requires a token.

Regarding its origin, the XML reference describes SecureStorageMasterKey as the master key of the source firewall from which the configuration was exported. According to the reference, without this key, sensitive information such as passwords and the settings that depend on them are not imported; if the key is missing, it directs you to the default administrator with username admin. Token and encrypted password values come from the documented Get/export result. The marker hashform="mode1", for example on <Password>, describes an encrypted password value there; the reference also lists an unencrypted password as an alternative. This explains origin and interpretation, not permission to copy ciphertext, tokens, or markers between arbitrary objects and builds. XML <Get> does not automatically permit the HTTP GET method. This introduces no new import or export command; object- and build-specific confirmation and the stop requirement below for unresolved inputs remain mandatory.

The documentation also retains a conflicting URL example for the master key. If a source conflict, required input or its interpretation remains unresolved for the installed build, do not perform the sensitive import; ask Support to clarify it. The separately guarded HTTP GET certificate export below remains a distinct exception.

An exported collection may contain credentials or environment values. Sanitize collections before sharing them, don’t store secrets in plaintext as Initial Values, and rotate test passwords after a leak.

Query Object Usage before changes

The API can return names and usage counts for supported objects. Use statistics tags such as <IPHostStatistics> instead of the normal object tag. A filter on IP Host names looks like this:

<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 supports this usage query for IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts and groups, Country Groups, Services and Service Groups, as well as Interfaces, Zones, Gateways, and SD-WAN Profiles. Name filters include like, not like, startswith, in, =, and !=; the usage count additionally supports >, >=, and lists of numbers with in.

The response currently contains only the object name and number of uses, not the dependent configurations. A usage count of 3 therefore doesn’t identify the three affected rules or profiles. Before an update or remove operation, also check Object usage in WebAdmin or Config Studio. A count of 0 isn’t permission for an uncontrolled deletion either: Backup, dependency checks, and a narrow test remain mandatory.

In WebAdmin, Usage is shown for interfaces, zones, gateways, SD-WAN profiles, and hosts and services. The count refreshes once a day; refresh it using the control next to Usage before making a change. Click the object’s usage count, expand the relevant category, and open the listed rule or policy to replace or remove the object there. This removes the reference, not automatically the object itself. Some WAN-gateway and CLI configurations cannot be edited from the Object Usage popup; use the relevant configuration page or CLI instead.

Sign live users in and out through the API

SFOS can sign a user in or out as a live user through the API. This is useful for a clearly owned integration with an external authentication system, but it isn’t a general shortcut around normal user authentication. An incorrect sign-in assigns traffic to an identity and can therefore affect user-based firewall or web rules.

For the administrator performing the operation, set Manage live users to Read-write under Profiles > Device access > Identity. The endpoint for this purpose is:

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

This endpoint processes sign-in and sign-out operations in parallel. The general APIController can process the same operations serially. An existing integration should therefore not be migrated without testing solely because the behavior differs.

A sign-in payload can look like this:

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

To sign the user out, send the same logical user with 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, and the MAC address are example values. The username, IP address, and MAC address must match the actual session. Store the admin secret in the tool’s protected secret store and send it in the HTTP POST body, not in a URL, shell history, log file, or shared collection.

After sign-in, the user must appear under Current activities > Live users with Client type API client. A controlled test then checks the expected user-based rule decision. After sign-out, the session must no longer be listed as an active API client. If the user remains visible, check the payload, username, IP address, MAC address, and API response first; don’t sign out an unrelated live-user session on suspicion.

Transfer or export certificates through the API

In Postman, create a request through New > HTTP Request, name it with Save, and save it in a collection. Use POST and the APIController endpoint above with the actual WebAdmin port. By default the desktop app sends from the local administrator workstation; allow its source IP as seen by the firewall. Under Body > form-data, create a named File entry for each of the certificate and private key, and select the local files; the third entry, reqxml, is Text. Keep files in access-restricted local storage, not a synchronized cloud folder.

The Postman example uses C:/Users/[yourname]/Postman/files as a Windows storage location. Replace [yourname] and check access restrictions and the app’s local file access; this path is not a general SFOS parameter.

⚠️ Vendor example for documentation only; do not execute: The following PEM certificate payload for reqxml omits operation on <Set>. Because the default descriptions conflict, do not send it, even to create a new certificate. First clarify the explicit operation and complete certificate payload for the object and installed build in API help or with Support. All account, secret, object, and filenames are placeholders:

<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 and PrivateKeyFile identify the selected upload files. The optional transactionid correlates this request with its response. The omitted operation proves neither creation nor updating; the unchanged vendor example remains blocked from execution until the object- and build-specific details have been clarified. For an existing certificate in particular, check the exact update payload in API help rather than blindly resending it. Send a confirmed payload only after this clarification; then inspect the response under Body and check the target certificate in WebAdmin.

Certificates are a special case because files are transferred in addition to XML. For a confirmed create or update payload, use a form-data request in the Postman desktop app with three parts: certificate file, private-key file, and reqxml with the confirmed explicit operation on <Set> and the corresponding <Certificate> fields. The abbreviated structure of the blocked example is not an executable template. Filenames, format, action, and certificate name in the XML must match the uploaded files.

Private keys belong only on the protected administrator endpoint and must never reach a cloud collection, ticket, or repository. After Send, first evaluate <Response> and <Status>, then check under Certificates > Certificates that exactly the expected certificate, matching key, and correct chain are present. Assignment and service testing follow Import and assign certificates on Sophos Firewall. The complete automation path from the public CA through the build-specific upload to service assignment and external verification is described in Renew a Sophos Firewall certificate via XML API and verify services.

A <Get><Certificate/></Get> request doesn’t return a normal XML result. It produces a .tar archive containing certificates, private keys, and Entities.xml, so it doesn’t work as a normal Postman response. The dedicated certificate guide documents HTTP GET from a Linux command line or browser; both variants place credentials in the URL’s reqxml.

SFOS 23.0: This specific GET guide still mentions browsers, while the POST guide excludes them. This does not establish a blanket ban on all HTTP GET requests, nor a browser export tested on this firmware. Do not carry browser-export instructions forward from older versions or assume POST delivers the same download. Before a required export, verify the CLI GET path and safe credential handling for the installed build with Support or in an authorized test system; without that verification, do not perform the export.

For a verified export, use only a temporary, narrowly privileged account on a protected management host, do not log the URL or command, and rotate the secret afterward. Validate the TLS certificate and hostname; do not carry the vendor examples’ -k option into production jobs. The archive is highly sensitive: store it encrypted with restricted access, extract it in a controlled location, and securely remove unneeded copies.

For an approved CLI export, choose an explicit local output path for filename.tar. Before extraction, inspect the entries with tar -tf filename.tar; do not accept unexpected paths or links. Extract with tar -xvf filename.tar only inside an empty, access-restricted destination directory. filename.tar is a placeholder. These commands can disclose sensitive filenames in their output, which must not enter public logs.

API Access and User Rights

A source IP alone is not a complete security concept. The restriction only limits from where the API is reachable. Additionally, it must be clear which account is used for API access and what rights this account has.

For productive environments, you should check:

• Is a separate API or service account used?
• Does the account have only the necessary permissions?
• Is it clearly documented which person or team is responsible for the account?
• Is the password or secret stored securely?
• Is access removed when the integration is no longer used?
• Are changes traceable through audit logs?

Shared admin accounts are problematic for API processes. If multiple systems or people use the same account, traceability is weaker. For change analyses, checking Sophos Firewall Audit Trail Logs is relevant.

For a dedicated API account, a narrow process is better than a quickly copied full admin. Set up Sophos Firewall administrators and profiles securely explains the general planning of personal accounts and restricted profiles; for automation, the separate service account described here remains the relevant approach. Sophos documentation refers to this concept as Allow API access to administrators: it is not only the source that is allowed, the administrator or profile must also have the appropriate access.

1. Create an administrator profile with the required rights under Profiles > Device access.
2. Create an administrator user for the API process under Authentication > Users.
3. Assign the appropriate administrator profile.
4. For temporary API access, assign an owner and schedule manual removal of the dedicated API account and/or dedicated API source authorization at the end of the approved window; then verify that this API access has been revoked without disabling legitimate shared access. Access Time for ordinary users controls internet access; Schedule for device access for administrators controls WebAdmin sign-ins. Neither setting is documented here as providing automatic expiry of XML API access: do not rely on either to expire API access. If schedule enforcement is required, obtain primary-documentation confirmation for the installed build or authorized verification before relying on it.
5. If possible, restrict Login restriction for device access to the intended sources.
6. Then allow API access and Device Access for the appropriate source.

In the official example, the profile receives Read-write for Objects and Network. This isn’t a blanket recommendation: For read-only integrations and other API tasks, unneeded areas remain set to None or Read-only; write access is granted only after a controlled read test.

Sophos supports the official APIs and unchanged sample scripts. Sophos Technical Support does not provide advice or troubleshooting for custom integrations; Sophos refers this work to the responsible Sophos Partner or Sophos Professional Services. Custom integrations, wrappers and automations therefore need an internal owner, tests and a rollback concept. “Works in the lab” is not enough for production write operations.

Profile permissions are not source authorization: Profiles under Profiles > Device access apply to WebAdmin and API; the local service ACL under Administration > Device access is a different control. Default profiles cannot be edited. Use Edit to view permissions; create and edit a custom profile for tailored rights. Unassign a profile from every administrator before deleting it. Each area supports None, Read-only, or Read-write. With None, the configuration is neither visible in WebAdmin nor retrievable through the API, so missing API data is not automatically a network fault.

Default profiles differ deliberately: Administrator, including the default admin account, has full WebAdmin/CLI access, all API request types, and can create administrators. Audit admin has Read-write for logs and reports; Crypto admin for security certificates. HAProfile has Read-only access to the auxiliary device when HA is configured. Security admin has Read-write for all features except profiles, logs, and reports. Do not assume any of these is a least-privilege API profile; inspect the effective permissions for the required object.

MFA and API users after SFOS 22

MFA is important for interactive administrator access. For API and automation processes, however, authentication must be planned deliberately. A script, monitoring tool or integration system cannot simply enter an OTP code if the user account enforces MFA.

The current Known Issues list documents NC-177609 for SFOS 22.0.0 GA Respin Build 411: after an upgrade, API-based configuration changes can fail for migrated users when MFA is active and no one-time token is supplied. Non-migrated users retain the previous behavior until MFA onboarding. The official workaround is a separate API account without MFA or excluding that account from MFA. This isn’t a reason to disable MFA for interactive administrators; for newer builds, check the release notes and Known Issues first.

Recommended approach:

1. Use a dedicated service account for API processes.
2. Give the account only the required rights.
3. Additionally restrict API access to fixed IP Hosts or management networks.
4. Check whether MFA is technically and operationally sensible for this account.
5. If MFA is not practical for the API account, control the account especially tightly through source, permissions, secret storage and audit trail.
6. After an SFOS 22 upgrade, test all API processes with read and write operations.

⚠️ API users without MFA are not a free pass for broad rights. If an API account must run without MFA for technical reasons, source IP, rights, password storage, ownership and auditability must be controlled more tightly.

This point is particularly important for automations that do not only read but also change configuration.

Before productive API changes, check at least three things:

• A current Sophos Firewall backup exists.
• The planned API account can successfully perform a harmless read query.
• For prepared bulk changes from Sophos Firewall Config Studio, the generated API or curl calls work with the planned account.

Distinction from Device Access

API access control is not the same as Device Access, but both controls interact. Device Access controls local firewall services such as WebAdmin, SSH, User Portal, VPN Portal, DNS, or Ping. The API access settings additionally control which IP hosts may use the XML API. Important: the Device Access permissions for the WebAdmin Console also apply to API access.

In practice, this means that API access must be enabled, the source must be allowed in the API access settings, and local management access to the firewall must not be blocked by Device Access. Each layer limits a different part of the attack surface:

• Properly configure Device Access: local firewall services like WebAdmin, SSH, User Portal, VPN Portal, DNS, or Ping
• API access control: IP hosts that may additionally use the XML API
• Enable MFA for Sophos Firewall WebAdmin, VPN Portal, and Remote Access: interactive logins for WebAdmin, VPN Portal, and Remote Access
• Named Admins and clear roles: traceability and damage radius of admin and service accounts

If an admin network is allowed to use WebAdmin, SSH, and API, this network should be particularly well protected. A compromised client in the management network is otherwise a direct entry into firewall management.

For WAN access, do not enable HTTPS/WebAdmin for the entire WAN zone. If external API or admin access is genuinely required, use a Local service ACL exception rule with a narrowly scoped Source, the appropriate Service HTTPS, a defined rule position, and a documented time period.

HA: Verify access after failover

In an HA cluster, the firewall configuration is synchronized from the primary to the auxiliary; the dedicated HA link and administration ports aren’t synchronized. API clients should therefore use the intended cluster name or shared interface address and not unknowingly depend on a node-specific administration IP address.

Repeat one read test and one negative test after HA setup, a certificate change, or failover. Check DNS resolution, certificate name, source IP, admin port, API access, and Device Access. A synchronized host object alone doesn’t prove that the complete network and TLS path works after the roles change.

Operation and Review

API access should be regularly reviewed. Especially after migrations, service provider changes, automation projects, or firewall upgrades, old sources often remain.

Sensible review questions:

• Which IP hosts are currently allowed API access?
• Are there objects with the prefix apiconfig?
• Are these objects still necessary?
• Do names and descriptions match the actual purpose?
• Are there documented responsible parties?
• Are API accesses considered in a change or audit process?
• Is there a current backup before major API-based changes?

Before API-based changes, a backup should always be available. The article Create or restore a Sophos Firewall backup describes what to consider for backup, restore, and compatibility.

Typical errors

• API access allowed for a whole client network: Every compromised client in that network can reach the API.
• Old apiconfig objects not checked: Migrated legacy exceptions remain active unnoticed.
• Service account uses full admin rights: A compromised secret has an unnecessarily large blast radius.
• API automation uses an MFA-required admin: Script or tool can fail on write operations after an SFOS upgrade.
• Wrong port in the tool: The admin HTTPS port was changed, but the tool still uses the old port.
• REST logic expected: The tool sends REST methods instead of an XML payload over HTTP POST to APIController.
• Only the HTTP status was checked: The actual API operation failed even though transport succeeded. Evaluate <Response> and <Status>.
• Set sent without an operation: Do not rely on a default or blindly retry. The documented descriptions conflict; confirm the explicit operation for the object and build before every write, or stop.
• MFA settings or tokens can’t be imported: The payload must contain the empty <tokenid/> element.
• A user can’t be deleted: Specify the exact username in the <Remove> payload as <Name>username</Name>. Verify the account, dependencies, backup, and rollback before sending the request.
• Usage count treated as a complete dependency list: The statistics return count and name, but not the affected rules or profiles.
• Live user signed in without matching the session: The username, IP address, and MAC address don’t match the actual session, which can cause incorrect user-based rule decisions.
• Certificate archive stored without protection: The API export can contain private keys and doesn’t belong in Downloads, tickets, or shared storage.
• Temporary provider IP remains active: External access remains possible longer than planned.
• No documentation of the purpose: Later admins do not know whether an exception is still required.
• API changes without backup: Faulty automation is harder to roll back.

Troubleshooting

If a tool does not reach the XML API, you should check systematically:

1. Does the source IP match from the firewall’s perspective?
2. Is the source allowed as an IP host, IP range, or network?
3. Was an apiconfig object created after an upgrade but not properly adjusted?
4. Does Device Access allow local WebAdmin/API access from this zone?
5. Does the tool use the correct firewall address and the correct admin HTTPS port?
6. Do username, password, or secret match?
7. Does the account have the necessary rights?
8. Does the account enforce MFA although the tool cannot provide a one-time token?
9. Are there routing, NAT, or proxy effects between the tool and the firewall?
10. Was access intentionally removed by a hardening measure?
11. Was the test performed from the correct source system or only from the admin client?

If an API change has unexpected effects, first secure the last backup and then check the audit trail, Config Studio comparison, and affected firewall objects. For live traffic problems, Log Viewer and Packet Capture are more helpful than the API itself.

For a rejected or faulty XML operation, first save <Response> and <Status>. Then check apiparser.log, validation.log, and validationError.log under Diagnostics > Tools > Troubleshooting logs; Sophos assigns these files to API translation and API validation. Sophos Firewall service and log files explains filtering and export. Remove secrets before sharing a log excerpt.

Checklist

Before activation:

• Document the purpose of API access.
• Clearly determine the source system.
• Create an IP host object with a descriptive name.
• Check service account and permissions.
• Deliberately set the MFA behavior of the API account.
• Establish a backup and rollback process.
• Define a test method without secret leakage.
• Document the planned XML operation and expected <Status>.

During operation:

• Allow API access only for defined sources.
• Do not allow broad client, guest, or IoT networks.
• Check apiconfig objects after upgrades.
• Control service provider accesses temporally and technically.
• Store secrets securely and renew them when personnel or tools change.
• Rotate secrets if they ended up in shell history, tickets, or unsafe storage.
• Specifically test API read and write operations after SFOS upgrades.
• Check Object Usage and dependent configurations before update or remove operations.
• Validate API-based live-user sign-ins with API client, the rule decision, and a clean sign-out.
• Handle certificate files, private keys, and API exports only in protected locations.

During review:

• Regularly check allowed API sources.
• Remove IP hosts that are no longer needed.
• Match changes with audit trail and change tickets.
• Test automation processes after firmware updates.

FAQ