diff --git a/AUTHORS.rst b/AUTHORS.rst index 9f408c53..4dcdeddf 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -13,3 +13,4 @@ Authors * Nathan McDougall - https://github.com/nathanjmcdougall * Oleksandr Zaiats - https://github.com/z4y4ts * Nikhil Dabas - https://github.com/ndabas +* GitHub Copilot - https://github.com/copilot diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 8ee3b38a..91e75fb3 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -5,6 +5,8 @@ Changelog latest ------ +* Document Windows Application Control limitations and protection-preserving + alternatives (https://github.com/python-grimp/grimp/issues/319). * Fix missing macOS wheels for regular (non-freethreaded) Python 3.14+ (https://github.com/python-grimp/grimp/issues/317). diff --git a/docs/installation.rst b/docs/installation.rst index d643446b..a743351b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,3 +5,37 @@ Installation At the command line:: pip install grimp + +Windows Application Control +=========================== + +Grimp requires a native Rust extension, ``grimp._rustgrimp``. On Windows this is +a ``.pyd`` file. Smart App Control or another Windows Application Control policy +may prevent Python from loading it, with an error such as:: + + ImportError: DLL load failed while importing _rustgrimp: + An Application Control policy has blocked this file. + +The current Windows wheel release process does not publisher-sign the native +extension. Publisher signing would require a trusted code-signing certificate or +signing service and changes to the release process; no signed release date is +currently committed. A wheel's PyPI SHA-256 hash and its ``RECORD`` metadata +can help verify file integrity, but are not Windows code signatures and do not +establish that Windows will allow the extension to load. + +There is no Grimp setting or pure-Python fallback that resolves an Application +Control block. Upgrading or building from source does not guarantee that the +resulting extension will be accepted by the policy. Even a valid code signature +does not guarantee acceptance under every policy. + +If your policy blocks the extension, there is currently no supported Grimp-only +fix for running it in that Windows environment while retaining the policy. +You can instead run Grimp and Import Linter in a Linux environment, such as a +Linux CI runner, with the same source tree and architecture contracts. This +leaves the Windows protections in place. Do not disable or bypass them to load +the extension. + +When reporting a block, please include the Grimp and Python versions, Windows +version and architecture, the wheel filename and hash, and sanitized Code +Integrity event details (for example, events 3077 and 3033). A block reported +for one version does not establish whether another version will be blocked.