libre-devops-helpers 0.4.1__py3-none-any.whl

libre_devops_helpers/servicenow/config.py

@@ -0,0 +1,261 @@
+"""The ``[servicenow]`` config section: named instances, and how to sign in to each.
+
+Each profile is one instance and one account on it. Sign-in is OAuth by default, through
+an OAuth application registry entry on the instance: in a browser (single sign-on and
+MFA included, and headless too, by pasting back the address the browser lands on), or
+with a password once. Either way the refresh token is kept, so later commands sign in by
+themselves. ``basic`` (the password with every request) is there for instances that allow
+it.
+
+Passwords and client secrets never go in the file. They come from environment variables
+(``SNOW_INSTANCE_PASSWORD`` and ``SNOW_CLIENT_SECRET`` unless a profile names others), or
+are asked for, hidden, when you sign in. Without a ``[servicenow]`` section,
+``SNOW_INSTANCE_URL`` makes a profile called ``env``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from libre_devops_helpers.core import brand
+from libre_devops_helpers.core.config import (
+    ConfigFile,
+    check_name,
+    load_config_file,
+    reject_unknown,
+    table,
+    text,
+)
+from libre_devops_helpers.core.errors import ConfigError
+from libre_devops_helpers.core.token_store import DEFAULT_TOKEN_CACHE, TOKEN_CACHES
+
+SECTION = "servicenow"
+ENV_PROFILE = "env"
+URL_ENV = "SNOW_INSTANCE_URL"
+USERNAME_ENV = "SNOW_INSTANCE_USERNAME"
+PASSWORD_ENV = "SNOW_INSTANCE_PASSWORD"
+CLIENT_ID_ENV = "SNOW_CLIENT_ID"
+CLIENT_SECRET_ENV = "SNOW_CLIENT_SECRET"
+PLACEHOLDER_HOST = "dev00000.service-now.com"
+# Where the browser is sent after an OAuth sign-in: set it as the application registry
+# entry's Redirect URL. Nothing needs to listen there; you paste the address back.
+DEFAULT_REDIRECT_URI = "http://localhost:8765/callback"
+
+# oauth: a token and a kept refresh token, through an OAuth application registry entry.
+# basic: the username and password with every request.
+AUTH_METHODS = ("oauth", "basic")
+# How an oauth profile signs in when it has no kept refresh token.
+SIGN_INS = ("browser", "password")
+_ENV_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_INSTANCE_NAME = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+_SECTION_KEYS = frozenset({"default_profile", "profiles"})
+_PROFILE_KEYS = frozenset(
+    {
+        "description",
+        "instance",
+        "username",
+        "auth",
+        "client_id",
+        "sign_in",
+        "redirect_uri",
+        "token_cache",
+        "password_env",
+        "client_secret_env",
+    }
+)
+
+CONFIG_TEMPLATE = f"""\
+# ServiceNow instances. Each profile is an instance and the account you sign in with.
+# Passwords and client secrets come from the environment, never this file. Without
+# this section, {URL_ENV} and {USERNAME_ENV} make a profile called "{ENV_PROFILE}".
+# Replace the placeholder instance, then run: {brand.COMMAND} snow whoami
+[servicenow]
+default_profile = "dev"
+
+[servicenow.profiles.dev]
+description = "Personal developer instance"
+instance = "https://{PLACEHOLDER_HOST}"
+# The OAuth application registry entry's client id (or {CLIENT_ID_ENV}). Its secret comes
+# from {CLIENT_SECRET_ENV}, or is asked for when you sign in and then kept.
+client_id = "<client id>"
+# sign_in = "browser"   the default: a link to open in any browser, where you sign in as
+#                       usual (single sign-on and MFA too); paste back where it lands
+# sign_in = "password"  the username and password, once (from {PASSWORD_ENV}, or asked)
+# username = "admin"    needed for sign_in = "password" and auth = "basic"
+# redirect_uri = "{DEFAULT_REDIRECT_URI}"   must match the entry's Redirect URL
+# token_cache = "file"  where the refresh token is kept: file (the default), keychain
+#                       or memory
+# auth = "basic"        instead of OAuth: the password with every request, where the
+#                       instance allows it
+# password_env = "{PASSWORD_ENV}"   another variable, for a second instance
+# client_secret_env = "{CLIENT_SECRET_ENV}"
+"""
+
+
+@dataclass(frozen=True)
+class Profile:
+    """One ServiceNow instance, and the account to sign in to it with."""
+
+    name: str
+    instance: str
+    username: str | None = None  # None: read from SNOW_INSTANCE_USERNAME when needed
+    auth: str = "oauth"
+    client_id: str | None = None  # None: read from SNOW_CLIENT_ID when signing in
+    sign_in: str = "browser"
+    redirect_uri: str = DEFAULT_REDIRECT_URI
+    token_cache: str = DEFAULT_TOKEN_CACHE
+    password_env: str = PASSWORD_ENV
+    client_secret_env: str = CLIENT_SECRET_ENV
+    description: str = ""
+
+    @property
+    def host(self) -> str:
+        return urlsplit(self.instance).netloc
+
+    @property
+    def has_placeholder(self) -> bool:
+        return self.host == PLACEHOLDER_HOST
+
+    def require_real_instance(self) -> None:
+        if self.has_placeholder:
+            raise ConfigError(
+                f"ServiceNow profile {self.name!r} still has the template's placeholder instance",
+                hint="set its instance in the config file",
+            )
+
+
+@dataclass(frozen=True)
+class ServiceNowConfig:
+    """The parsed ``[servicenow]`` section."""
+
+    path: Path | None
+    profiles: Mapping[str, Profile]
+    default_profile: str | None = None
+
+    def get(self, name: str) -> Profile:
+        try:
+            return self.profiles[name]
+        except KeyError:
+            known = ", ".join(sorted(self.profiles)) or "none"
+            raise ConfigError(
+                f"unknown ServiceNow profile {name!r} (configured: {known})",
+                hint=f"edit {self.path}" if self.path else None,
+            ) from None
+
+
+def instance_url(value: str, where: str) -> str:
+    """``https://<name>.service-now.com``, or another https URL, without a trailing slash.
+
+    A bare instance name (``dev12345``) means ``https://dev12345.service-now.com``.
+    """
+    value = value.strip()
+    if _INSTANCE_NAME.match(value):
+        return f"https://{value}.service-now.com"
+    parts = urlsplit(value)
+    # The password or token goes with every request, so plain http is never acceptable.
+    if parts.scheme != "https" or not parts.netloc:
+        raise ConfigError(f"{where}: instance must be an https:// URL or an instance name")
+    if parts.path.strip("/") or parts.query or parts.fragment:
+        raise ConfigError(f"{where}: instance must be the instance's address, with no path")
+    return f"https://{parts.netloc.lower()}"
+
+
+def load_config(path: Path | None = None) -> ServiceNowConfig | None:
+    """Read the config file's ``[servicenow]`` section, or None when it has none."""
+    return from_file(load_config_file(path))
+
+
+def from_file(file: ConfigFile) -> ServiceNowConfig | None:
+    """Validate the ``[servicenow]`` section; None when the file has none."""
+    section = file.section(SECTION)
+    if section is None:
+        return None
+    where = f"{file.path}: [{SECTION}]"
+    reject_unknown(section, _SECTION_KEYS, where)
+    profiles = {
+        name: _parse_profile(name, value, str(file.path))
+        for name, value in table(section.get("profiles", {}), f"{where}.profiles").items()
+    }
+    default = text(section, "default_profile", where)
+    if default is not None and default not in profiles:
+        raise ConfigError(f"{where}: default_profile {default!r} is not a configured profile")
+    return ServiceNowConfig(path=file.path, profiles=profiles, default_profile=default)
+
+
+def profile_from_env(environ: Mapping[str, str] = os.environ) -> Profile | None:
+    """The ``env`` profile from ``SNOW_INSTANCE_URL`` (and friends), or None without it."""
+    url = environ.get(URL_ENV, "").strip()
+    if not url:
+        return None
+    # OAuth once there is an application to sign in through; with a password to hand,
+    # it signs in with that rather than a browser.
+    return Profile(
+        name=ENV_PROFILE,
+        instance=instance_url(url, URL_ENV),
+        username=environ.get(USERNAME_ENV, "").strip() or None,
+        auth="oauth" if environ.get(CLIENT_ID_ENV, "").strip() else "basic",
+        sign_in="password" if environ.get(PASSWORD_ENV) else "browser",
+        description=f"from {URL_ENV}",
+    )
+
+
+def _parse_profile(name: str, value: object, path: str) -> Profile:
+    where = f"{path}: [{SECTION}.profiles.{name}]"
+    check_name(name, where)
+    data = table(value, where)
+    reject_unknown(data, _PROFILE_KEYS, where)
+    instance = text(data, "instance", where)
+    if not instance:
+        raise ConfigError(f"{where}: instance is required")
+    auth = text(data, "auth", where) or "oauth"
+    if auth not in AUTH_METHODS:
+        raise ConfigError(f"{where}: auth must be one of {', '.join(AUTH_METHODS)}")
+    sign_in = text(data, "sign_in", where)
+    if sign_in is not None and sign_in not in SIGN_INS:
+        raise ConfigError(f"{where}: sign_in must be one of {', '.join(SIGN_INS)}")
+    redirect = text(data, "redirect_uri", where)
+    if redirect is not None and not _redirect_ok(redirect):
+        raise ConfigError(f"{where}: redirect_uri must be http://localhost... or an https:// URL")
+    if auth == "basic" and (sign_in or redirect):
+        raise ConfigError(f'{where}: sign_in and redirect_uri apply to auth = "oauth"')
+    token_cache = text(data, "token_cache", where)
+    if token_cache is not None and token_cache not in TOKEN_CACHES:
+        raise ConfigError(f"{where}: token_cache must be one of {', '.join(TOKEN_CACHES)}")
+    if token_cache is not None and auth != "oauth":
+        raise ConfigError(
+            f'{where}: token_cache applies to auth = "oauth"',
+            hint="basic sign-in sends the password each time, so there is nothing to keep",
+        )
+    return Profile(
+        name=name,
+        instance=instance_url(instance, where),
+        username=text(data, "username", where) or None,
+        auth=auth,
+        client_id=text(data, "client_id", where) or None,
+        sign_in=sign_in or "browser",
+        redirect_uri=redirect or DEFAULT_REDIRECT_URI,
+        token_cache=token_cache or DEFAULT_TOKEN_CACHE,
+        password_env=_env_name(data, "password_env", where) or PASSWORD_ENV,
+        client_secret_env=_env_name(data, "client_secret_env", where) or CLIENT_SECRET_ENV,
+        description=text(data, "description", where) or "",
+    )
+
+
+def _redirect_ok(uri: str) -> bool:
+    parts = urlsplit(uri)
+    if parts.scheme == "https" and parts.netloc:
+        return True
+    return parts.scheme == "http" and parts.hostname in {"localhost", "127.0.0.1"}
+
+
+def _env_name(data: Mapping[str, Any], key: str, where: str) -> str | None:
+    value = text(data, key, where)
+    if value is not None and not _ENV_NAME.match(value):
+        raise ConfigError(f"{where}: {key} must be an environment variable name")
+    return value

libre_devops_helpers/servicenow/instance/__init__.py

@@ -0,0 +1,32 @@
+"""The instance itself: the signed-in user and roles, the release, and applications.
+
+Public API::
+
+    from libre_devops_helpers.servicenow.instance import InstanceClient
+
+    InstanceClient(tables).current_user("admin")
+"""
+
+from libre_devops_helpers.servicenow.instance.client import (
+    SIR_PLUGIN,
+    SIR_SCOPE,
+    SIR_TABLE,
+    InstanceClient,
+)
+from libre_devops_helpers.servicenow.instance.models import Application, AppStatus, Release, User
+from libre_devops_helpers.servicenow.roles import RoleRequirement
+
+# Reading applications and system properties takes admin on a default instance.
+REQUIREMENTS = (RoleRequirement("instance release and applications", ("admin",)),)
+
+__all__ = [
+    "REQUIREMENTS",
+    "SIR_PLUGIN",
+    "SIR_SCOPE",
+    "SIR_TABLE",
+    "AppStatus",
+    "Application",
+    "InstanceClient",
+    "Release",
+    "User",
+]

libre_devops_helpers/servicenow/instance/client.py

@@ -0,0 +1,91 @@
+"""Questions about the instance: who am I, which roles, which release, which applications."""
+
+from __future__ import annotations
+
+from libre_devops_helpers.core.errors import ApiError, NotFoundError
+from libre_devops_helpers.servicenow.instance.models import Application, AppStatus, Release, User
+from libre_devops_helpers.servicenow.tables import TableClient, condition
+
+# Security Incident Response: its plugin, its application scope and its main table.
+SIR_PLUGIN = "com.snc.security_incident"
+SIR_SCOPE = "sn_si"
+SIR_TABLE = "sn_si_incident"
+
+
+class InstanceClient:
+    """Reads the instance's own records through the Table API."""
+
+    def __init__(self, tables: TableClient) -> None:
+        self.tables = tables
+
+    def current_user(self, user_name: str | None = None) -> User:
+        """The signed-in user, as the instance sees it; or the user called ``user_name``."""
+        # gs.getUserID() is one of the functions an encoded query may call, and it names
+        # whoever the request is authenticated as, however they signed in.
+        query = (
+            condition("user_name", user_name) if user_name else "sys_id=javascript:gs.getUserID()"
+        )
+        record = self.tables.first("sys_user", query=query, fields=User.FIELDS)
+        if record is None:
+            who = f"named {user_name!r}" if user_name else "for this sign-in"
+            raise NotFoundError(f"no ServiceNow user {who}")
+        return User.from_record(record)
+
+    def roles(self, user: User) -> tuple[str, ...]:
+        """Every role the user holds, directly or through a group or another role."""
+        rows = self.tables.records(
+            "sys_user_has_role",
+            query=f"{condition('user', user.sys_id)}^state=active",
+            fields=("role.name",),
+        )
+        return tuple(sorted({str(row.get("role.name")) for row in rows if row.get("role.name")}))
+
+    def release(self) -> Release | None:
+        """The release, or None when this account may not read system properties."""
+        try:
+            rows = self.tables.records(
+                "sys_properties",
+                query="nameINglide.buildtag.last,glide.war",
+                fields=("name", "value"),
+            )
+        except ApiError as exc:
+            if exc.status == 403:
+                return None
+            raise
+        values = {str(row.get("name")): str(row.get("value") or "") for row in rows}
+        # glide.buildtag.last is not kept as a record on every release; glide.war is.
+        tag = values.get("glide.buildtag.last") or values.get("glide.war")
+        return Release.from_build_tag(tag) if tag else None
+
+    def applications(
+        self, search: str | None = None, *, active_only: bool = True
+    ) -> list[Application]:
+        """Scoped applications, by name or scope, active ones first."""
+        query = None
+        if search:
+            query = f"{condition('name', search, 'LIKE')}^OR{condition('scope', search, 'LIKE')}"
+        found = [
+            Application.from_record(row)
+            for row in self.tables.records("sys_scope", query=query, fields=Application.FIELDS)
+        ]
+        if active_only:
+            found = [app for app in found if app.active]
+        return sorted(found, key=lambda app: (not app.active, app.name.casefold()))
+
+    def table_exists(self, name: str) -> bool:
+        return (
+            self.tables.first("sys_db_object", query=condition("name", name), fields=("name",))
+            is not None
+        )
+
+    def security_incident_response(self) -> AppStatus:
+        """Whether Security Incident Response is installed: its table is the proof."""
+        name = "Security Incident Response"
+        if not self.table_exists(SIR_TABLE):
+            return AppStatus(name, False, detail=f"no {SIR_TABLE} table")
+        app = self.tables.first(
+            "sys_scope", query=condition("scope", SIR_SCOPE), fields=("version", "active")
+        )
+        if app is not None:
+            return AppStatus(name, True, str(app.get("version") or ""), f"application {SIR_SCOPE}")
+        return AppStatus(name, True, detail=f"table {SIR_TABLE}")

libre_devops_helpers/servicenow/instance/models.py

@@ -0,0 +1,131 @@
+"""Records about the instance itself: the signed-in user, the release, and applications."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+# glide-yokohama-12-18-2024__patch4-06-25-2025 (glide.buildtag.last), or the same with a
+# .zip suffix (glide.war), for example.
+_BUILD_TAG = re.compile(
+    r"^glide-(?P<family>[a-z]+)-(?P<date>\d{2}-\d{2}-\d{4})(?:__(?P<patch>[a-z0-9]+))?"
+)
+
+
+def _flag(value: object) -> bool:
+    return str(value).strip().lower() in {"true", "1", "active", "yes"}
+
+
+def _text(record: Mapping[str, Any], key: str) -> str:
+    value = record.get(key)
+    return "" if value is None else str(value)
+
+
+@dataclass(frozen=True)
+class User:
+    """A ``sys_user`` record."""
+
+    sys_id: str
+    user_name: str
+    name: str
+    email: str
+    active: bool
+    locked_out: bool
+    web_service_only: bool
+    last_login: str
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    FIELDS = (
+        "sys_id",
+        "user_name",
+        "name",
+        "email",
+        "active",
+        "locked_out",
+        "web_service_access_only",
+        "last_login_time",
+    )
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> User:
+        return cls(
+            sys_id=_text(record, "sys_id"),
+            user_name=_text(record, "user_name"),
+            name=_text(record, "name"),
+            email=_text(record, "email"),
+            active=_flag(record.get("active")),
+            locked_out=_flag(record.get("locked_out")),
+            web_service_only=_flag(record.get("web_service_access_only")),
+            last_login=_text(record, "last_login_time"),
+            raw=dict(record),
+        )
+
+
+@dataclass(frozen=True)
+class Release:
+    """The instance's release, from its build tag: family, build date and patch."""
+
+    build_tag: str
+    family: str = ""
+    build_date: str = ""
+    patch: str = ""
+
+    @classmethod
+    def from_build_tag(cls, tag: str) -> Release:
+        match = _BUILD_TAG.match(tag.strip())
+        if not match:
+            return cls(build_tag=tag)
+        return cls(
+            build_tag=tag,
+            family=match["family"].capitalize(),
+            build_date=match["date"],
+            patch=match["patch"] or "",
+        )
+
+    @property
+    def label(self) -> str:
+        if not self.family:
+            return self.build_tag or "unknown"
+        return f"{self.family} {self.patch}".strip()
+
+
+@dataclass(frozen=True)
+class Application:
+    """A scoped application (``sys_scope``): from the ServiceNow Store, or built here.
+
+    The plugin tables (``v_plugin``, ``sys_plugins``, ``sys_store_app``) refuse the REST
+    API even to admin, but every scoped application, Security Incident Response
+    (``sn_si``) among them, is listed in ``sys_scope``, which it may read.
+    """
+
+    scope: str
+    name: str
+    active: bool
+    version: str
+    kind: str  # "store app" or "custom app"
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    FIELDS = ("scope", "name", "active", "version", "sys_class_name")
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> Application:
+        return cls(
+            scope=_text(record, "scope"),
+            name=_text(record, "name"),
+            active=_flag(record.get("active")),
+            version=_text(record, "version"),
+            kind="store app" if record.get("sys_class_name") == "sys_store_app" else "custom app",
+            raw=dict(record),
+        )
+
+
+@dataclass(frozen=True)
+class AppStatus:
+    """Whether an application is on the instance, and how we know."""
+
+    name: str
+    installed: bool
+    version: str = ""
+    detail: str = ""

libre_devops_helpers/servicenow/roles.py

@@ -0,0 +1,23 @@
+"""What each ServiceNow feature needs: roles, since the instance's access controls decide.
+
+``admin`` passes every access control, so it satisfies every requirement.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+ADMIN = "admin"
+
+
+@dataclass(frozen=True)
+class RoleRequirement:
+    """``feature`` needs any one of ``any_of`` (or admin)."""
+
+    feature: str
+    any_of: tuple[str, ...]
+
+    def met_by(self, roles: Iterable[str]) -> bool:
+        held = {role.casefold() for role in roles}
+        return ADMIN in held or any(role.casefold() in held for role in self.any_of)

libre_devops_helpers/servicenow/tables.py

@@ -0,0 +1,133 @@
+"""The ServiceNow Table API: read records from any table, a page at a time.
+
+Every ServiceNow feature reads through this. It turns the instance's errors into ones
+that say what to do: a refused sign-in, a missing role (an ACL), a table whose plugin is
+not installed, or a developer instance that is hibernating and answers with a web page.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, Self
+
+import requests
+
+from libre_devops_helpers.core.errors import ApiError, InputError
+from libre_devops_helpers.core.http import ApiClient
+
+log = logging.getLogger(__name__)
+
+PAGE_SIZE = 1000
+HIBERNATING_HINT = (
+    "the instance answered with a web page, not JSON: a developer instance may be "
+    "hibernating (wake it at developer.servicenow.com), or the address is not an instance"
+)
+ACL_HINT = "your account lacks a role (an access control) for this table"
+
+
+def condition(field: str, value: str, operator: str = "=") -> str:
+    """One encoded query condition, refusing values that would change the query.
+
+    ``^`` separates conditions in an encoded query, so a value holding one could add
+    conditions of its own; such values are refused rather than escaped.
+    """
+    if any(mark in value for mark in ("^", "\n", "\r")):
+        raise InputError(f"{field}: {value!r} cannot be used in a ServiceNow query")
+    return f"{field}{operator}{value}"
+
+
+class TableClient:
+    """Reads records through ``/api/now/table``, for one instance and one sign-in."""
+
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+
+    @classmethod
+    def create(
+        cls,
+        instance: str,
+        authorization: Callable[[], str],
+        *,
+        scheme: str = "Bearer",
+        session: requests.Session | None = None,
+        verify: bool | str = True,
+    ) -> Self:
+        """A client for ``instance``, sending ``scheme`` and ``authorization()`` each time."""
+        return cls(
+            ApiClient(
+                instance,
+                authorization,
+                name="ServiceNow",
+                session=session,
+                verify=verify,
+                auth_scheme=scheme,
+            )
+        )
+
+    def close(self) -> None:
+        self.api.close()
+
+    def records(
+        self,
+        table: str,
+        *,
+        query: str | None = None,
+        fields: Iterable[str] | None = None,
+        limit: int | None = None,
+        display_value: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Records of ``table`` matching the encoded ``query``, up to ``limit``."""
+        found: list[dict[str, Any]] = []
+        params = {
+            "sysparm_exclude_reference_link": "true",
+            "sysparm_display_value": "true" if display_value else "false",
+        }
+        if query:
+            params["sysparm_query"] = query
+        if fields:
+            params["sysparm_fields"] = ",".join(fields)
+        while True:
+            size = PAGE_SIZE if limit is None else min(PAGE_SIZE, limit - len(found))
+            page = self._get(
+                f"/api/now/table/{table}",
+                {**params, "sysparm_limit": str(size), "sysparm_offset": str(len(found))},
+            )
+            rows = page.get("result")
+            if not isinstance(rows, list):
+                raise ApiError(f"ServiceNow: the {table} response has no result list")
+            found.extend(row for row in rows if isinstance(row, dict))
+            if len(rows) < size or (limit is not None and len(found) >= limit):
+                return found
+
+    def first(
+        self, table: str, *, query: str, fields: Iterable[str] | None = None
+    ) -> dict[str, Any] | None:
+        """The first record matching ``query``, or None."""
+        rows = self.records(table, query=query, fields=fields, limit=1)
+        return rows[0] if rows else None
+
+    def _get(self, path: str, params: Mapping[str, str]) -> dict[str, Any]:
+        try:
+            return self.api.get(path, params=params)
+        except ApiError as exc:
+            raise _explained(exc) from None
+
+
+def _explained(exc: ApiError) -> ApiError:
+    """``exc`` with a hint for the ways a ServiceNow instance says no."""
+    text = str(exc)
+    hint = exc.hint
+    if exc.status == 401:
+        hint = (
+            "the instance did not accept the sign-in: check the account and its password or "
+            "token. ServiceNow blocks basic sign-in to its APIs for interactive accounts "
+            "unless they hold the snc_basic_auth_api_access role"
+        )
+    elif exc.status == 403:
+        hint = ACL_HINT
+    elif exc.status == 400 and "invalid table" in text.lower():
+        hint = "the table does not exist on this instance: its plugin or app is not installed"
+    elif exc.status == 200 and "did not return json" in text.lower():
+        hint = HIBERNATING_HINT
+    return ApiError(text, status=exc.status, code=exc.code, request_id=exc.request_id, hint=hint)