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 request. The general criteria are =, !=, and like; individual statistics queries support additional criteria.

If operation is omitted from <Set>, SFOS treats the request as add. This isn’t a harmless default: A request intended as an update may fail or operate on the wrong object. 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 sample 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 entity tags inside <Set>.

The optional APIVersion attribute in <Request> uses version-specific syntax. The exact object tags, attributes, status codes, and sample configurations must therefore come from API help for the installed SFOS build; payloads shouldn’t be transferred 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.

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.

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.

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

Certificates are a special case because files are transferred in addition to XML. To create or update a certificate, use a form-data request in the Postman desktop app with three parts: certificate file, private-key file, and reqxml containing a <Set><Certificate>...</Certificate></Set> payload. 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.

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. If the access is only needed temporarily, limit Access time.
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.

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: SFOS treats the request as add even though an update was intended.
• 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 > 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