Troubleshooting Scenario Questions

/files/

Why it fails: The /files/ domain returns metadata about files submitted to Umbrella, such as hashes and associated samples. It is queried when investigating a suspicious file's reputation. Checking an IP address requires the /ip/ domain, which returns ASN, geolocation and threat scores for that address.

/domains/

Why it fails: The /domains/ domain returns categorisation, WHOIS and threat data for a hostname. It is queried when investigating a suspicious domain. Resolving an IP address to associated domains is a different operation; the /ip/ domain directly returns reputation and threat intelligence for the address in question.

/security/

Why it fails: The Investigate API exposes categorisation, co-occurrence, domain and IP reputation under /domains/ and /ips/; /security/ is not a valid endpoint, so the query returns nothing. It tempts because Umbrella's product is security-focused, but security classification is delivered through the reputation and categorisation endpoints, not a security path.

The local machine's DNS settings.

Why it fails: DNS is rarely the cause of a specific pxGrid subscription failure.

The ISE ERS API status.

Why it fails: ERS handles CRUD operations on ISE objects, not the pub/sub notification stream the script subscribes to; pxGrid delivers those. Verifying ERS status leaves the actual failure untouched. ERS would be the right check when a script's REST calls to create or read endpoints, users or network devices return errors.

The TACACS+ shared secret.

Why it fails: TACACS+ carries device administration credentials, not pxGrid's publish/subscribe transport, so verifying it cannot restore notifications. It is tempting because TACACS+ also secures ISE communications, and would be the right check when a network device's CLI login or command authorisation against ISE fails.

The block rate of a policy

Why it fails: Co-occurrences map related domains and IPs sharing resolution history with the queried indicator. Block rate belongs to policy or reporting data, not Investigate's co-occurrence output. Tempting since Umbrella enforces blocking, but policy statistics are surfaced elsewhere, not through this API result.

Malware infection rate

Why it fails: Co-occurrences list domains or IPs resolved alongside a queried domain, revealing infrastructure relationships. Infection rate is a reputation metric, not a co-occurrence. Tempting because Investigate does expose threat scores, but those come from separate reputation fields, not the co-occurrences endpoint.

The number of users on a network

Why it fails: Co-occurrences counts domains or IPs observed together in DNS requests, not users on a network. It is tempting because Umbrella aggregates DNS activity, and user counts would be the right interpretation if the query concerned network-level client statistics rather than domain relationships.

The API endpoint is down.

Why it fails: An unreachable endpoint produces ConnectionError or Timeout, not SSLError, because the TLS handshake never begins. Endpoint availability is the diagnostic focus when requests fail immediately with connection refused or DNS resolution errors, which is a distinct failure class from certificate verification.

The authentication token is invalid.

Why it fails: An invalid token yields HTTP 401 or 403 responses after TLS succeeds, so no SSLError is raised. Token validity is the correct avenue when the connection completes but the server rejects authorisation, which is unrelated to the certificate verification failure that SSLError represents.

The JSON payload contains invalid characters.

Why it fails: An SSLError arises from TLS negotiation or certificate verification, not payload content; invalid JSON characters would surface as a decoding or HTTP 400 error. Malformed payload handling is the concern when validating request bodies, but it never triggers certificate-related exceptions in the requests library.

The identities collection, by adding a new identity for the malicious domain.

Why it fails: Identities represent the users, networks, or roaming clients whose DNS traffic Umbrella evaluates; they are not domain entries. Adding an identity for a malicious domain makes no sense because identities are the subjects of policy, not the objects being blocked. The script must target the destination list's destinations collection instead, which is where blocked domains are stored.

The Investigate API's domain categorization endpoint, by submitting a new category label for the domain.

Why it fails: The Investigate API provides intelligence and categorization data; it is not a policy enforcement interface. Submitting a category label does not block traffic and would not change Umbrella's DNS responses. Enforcement happens through destination lists in the Management API, so the script must write the domain there after Investigate confirms it is malicious.

The policies collection, by creating a new policy that references the domain as a rule name.

Why it fails: Policies define which lists apply to which identities; they do not store individual domain entries. Creating a policy per malicious domain would create thousands of policies and quickly hit management limits. The correct approach is to add the domain to an existing destination list and let the policy that already references that list enforce the block across the intended identities.