fix: harden Zscaler containment and API handling

[phantom-jacob]

Written by Codex.

Bug Fixes

• Make denylist behavior reflect ZIA allowlist precedence and normalize internationalized hostnames before list operations.
• Narrow user-group lost-update races, encode department query parameters, validate authentication and JSON response shapes, preserve rate-limit failures, and restore finite request timeouts.
• Use ZIA category delta operations and asset-local ownership records so shared list updates preserve concurrent and foreign entries.

This is the refreshed N-Z remediation wave under PAPP-38310 and ESPM-5228. PAPP-38310 was reconciled and expanded because PRs #41 and #44 are merged historical work and do not cover these later findings. PSAAS-33953 remains excluded as platform work, and PSAAS-34406 remains excluded for human review; this PR does not change Jira labels.

Finding provenance

PSAAS	VULN	FS	Fix
PSAAS-32519	VULN-95242	FS-4082	Honor allowlist precedence for block and lookup actions.
PSAAS-33768	VULN-100507	FS-6813	Fetch the user immediately before the required full-object group update and compare memberships by group ID.
PSAAS-33816	VULN-100556	FS-6861	Convert internationalized hostname labels using IDNA2008 and UTS-46.
PSAAS-33898	VULN-100638	FS-6943	Replace stale full-category writes with documented delta operations.
PSAAS-33954	VULN-100696	FS-6999	Encode department search and pagination through Requests parameters.
PSAAS-34202	VULN-101726	FS-7710	Return a controlled error when authentication omits the session cookie.
PSAAS-34297	VULN-101821	FS-7805	Restrict shared-list removals to entries recorded by the current asset.
PSAAS-34786	VULN-102310	FS-8293	Restrict shared-list removals to entries recorded by the current asset.
PSAAS-34869	VULN-102393	FS-8376	Reject unexpected scalar JSON and malformed rate-limit bodies safely.
PSAAS-35035	VULN-103656	FS-8589	Preserve the original failure for unparseable Retry-After values.
PSAAS-35091	VULN-103712	FS-8645	Preserve concurrent category entries and keyword configuration with delta writes.
PSAAS-35134	VULN-104261	FS-9011	Restore the connector's bounded request timeout.

Sources and implementation decisions

• ZIA documents allowlist precedence and the advanced-security list operations: https://help.zscaler.com/zia/adding-urls-denylist and https://help.zscaler.com/zia/security-policy-settings
• ZIA documents ADD_TO_LIST and REMOVE_FROM_LIST category updates, required category identity fields, keyword fields, and rejection of non-ASCII URLs: https://help.zscaler.com/legacy-apis/configuring-url-categories-using-api
• ZIA exposes user updates as full-object PUT operations, so this change narrows but cannot eliminate the external lost-update window: https://help.zscaler.com/zia/user-management
• ZIA documents JSON Retry-After handling: https://help.zscaler.com/legacy-apis/understanding-rate-limiting
• Requests documents structured query parameters, JSON parsing, and finite timeouts: https://requests.readthedocs.io/en/latest/user/quickstart/
• IDNA2008 and UTS-46 processing follow RFC 5890 and the maintained idna implementation: https://www.rfc-editor.org/info/rfc5890/ and https://github.com/kjd/idna

The cached patches were treated as recommendations. The category fix uses the vendor's delta API instead of replaying a fetched category, and the shared-list fix uses an asset-local ownership ledger rather than a caller-controlled force parameter. Entries created before this version cannot be inferred as owned and are intentionally protected from removal.

Checks

• pre-commit autoupdate
• Docker-backed pre-commit baseline; every hook passed except the release-note hook while the unreleased file was intentionally empty, then the tooling refresh was committed separately.
• pre-commit run --all-files after all functional commits: passed, including app lint, compile/static checks, Semgrep, secrets, packaging, NOTICE, and release-note validation.
• In-memory focused smoke checks for IDNA conversion, category delta payloads, ownership filtering, allowlist precedence, department parameters, scalar JSON rejection, and malformed rate-limit handling: passed.
• Direct Python compilation of zscaler_connector.py and zscaler_consts.py: passed.
• Integration tests are deferred because connector asset labs are not a reliable acceptance gate for this repository.

Breaking changes: none. No action parameters, outputs, asset configuration, defaults, or actions were removed or made required.

Merge strategy: merge commit only; do not squash

Manual Documentation

Have you made any changes that should be documented in manual_readme_content.md?

The following changes require documentation in manual_readme_content.md:

• New, updated, or removed REST handlers
• New, updated, or removed authentication methods, especially complex methods like OAuth
• Compatibility considerations with respect to deployment types (e.g. actions that cannot be run on cloud or an automation broker)

• I have verified that no manual documentation change is required.

Other information

• PAPP: PAPP-38310
• Epic: ESPM-5228
• Color: Certified Apps

---

Please refer to our Contribution Guide for any questions on submitting a pull request.

Thanks for contributing!

[github-actions]

Merging this PR will release 3.0.5 with the following release notes:

3.0.5 (2026-08-04)

Connector release changes

• Block and lookup actions now account for ZIA allowlist entries that override the advanced-threat denylist.
• Group membership updates now fetch the user immediately before writing and compare existing memberships by group ID.
• URL list actions now convert internationalized hostnames to IDNA2008 A-labels before sending them to ZIA.
• URL category actions now use incremental list updates that preserve concurrent entries and existing keyword configuration.
• The get departments action now encodes its search and pagination query parameters through the HTTP client.
• Authentication now returns a controlled error when the ZIA response omits its required session cookie.
• Unblock and unallow actions now remove only shared-list entries recorded as added by the current connector asset.
• Unexpected scalar JSON and malformed rate-limit response bodies now return controlled action errors.
• Unparseable Retry-After values now preserve the original rate-limit failure instead of being treated as success.
• URL category updates and user listing now inherit the connector's finite request timeout.

[phantom-jacob]

Blocking upgrade path: installation_added_entries is new and starts empty. Existing URLs added by this same asset before upgrade are indistinguishable from foreign entries, and rerunning block or allow cannot seed the ledger because the existing-entry path returns before the ownership ledger update. The connector can therefore never unblock or unallow those pre-upgrade entries. Please add a safe migration or reconciliation path, or an explicit administrator-controlled claim or override. If this restriction remains, the functional commit should declare a breaking change because existing action capability is removed.

— Written by Codex.