|packagestatus|

.. contents::

uncompyle6

Un décompilateur natif Python multi-versions et décompilateur de fragments. Le successeur de decompyle, uncompyle et uncompyle2.

J'ai donné une conférence à ce sujet au BlackHat Asia 2024 <https://youtu.be/H-7ZNrpsV50?si=nOaixgYHr7RbILVS>_.

Introduction

uncompyle6 traduit le bytecode Python en code source Python équivalent. Il accepte les bytecodes des versions 1.0 à 3.8 de Python, couvrant plus de 24 ans de versions Python. Nous incluons le bytecode Python 2.5 de Dropbox et certains bytecodes PyPy.

Pourquoi celui-ci ?

D'accord, je vais le dire : ce logiciel est incroyable. Il est plus qu'un simple décompilateur bricolé. En utilisant la technologie compiler_, le programme crée un arbre syntaxique du programme à partir des instructions ; des nœuds aux niveaux supérieurs qui ressemblent un peu à ce qui pourrait provenir d'un AST Python. Nous pouvons donc vraiment classer et comprendre ce qui se passe dans les sections de bytecode Python.

En s'appuyant sur cela, une autre chose qui rend ce décompilateur différent des autres décompilateurs de bytecode CPython est qu'il peut déparser juste des fragments de code source et donner des informations sur le code source autour d'un offset de bytecode donné.

J'utilise les fragments d'arbre pour déparser des fragments de code au moment de l'exécution dans mes trepan_ debuggers_. Pour cela, les offsets de bytecode sont enregistrés et associés à des fragments du code source. Ce but, bien que compatible avec l'intention originale, est néanmoins un peu différent. Voir this_ pour plus d'informations.

Le déparsing de fragments Python, étant donné un offset d'instruction, est utile pour afficher les traces de pile et peut être intégré dans tout programme qui souhaite afficher un emplacement plus en détail qu'un simple numéro de ligne au moment de l'exécution. Ce code peut également être utilisé lorsque les informations de code source n'existent pas et qu'il n'y a que du bytecode. Encore une fois, mes débogueurs en tirent parti.

Il y avait (et il y a encore) plusieurs forks de decompyle, uncompyle, uncompyle2, uncompyle3. Beaucoup viennent essentiellement de la même base de code, et (presque?) tous ne sont plus activement maintenus. L'un était très bon pour décompiler Python 1.5-2.3, un autre est très bon pour Python 2.7, mais seulement cela. Un autre ne gère que Python 3.2 ; un autre l'a corrigé et ne gérait que 3.3. Vous voyez l'idée. Ce code rassemble tous ces forks et avance. Il y a une refactorisation et un nettoyage sérieux dans cette base de code par rapport à ces anciens forks. Une refactorisation encore plus expérimentale est en cours dans decompyle3_.

Ce projet fait démonstrativement le meilleur travail de décompilation Python sur toutes les versions de Python. Et même lorsqu'il existe un autre projet qui ne fournit la décompilation que pour un sous-ensemble de versions Python, nous faisons généralement démonstrativement mieux pour celles-ci également.

Comment le savons-nous ? En prenant le bytecode Python distribué avec cette version de Python et en le décompilant. Parmi ceux qui se décompilent avec succès, nous pouvons ensuite nous assurer que les programmes résultants sont syntaxiquement corrects en exécutant l'interpréteur Python pour cette version de bytecode. Enfin, dans les cas où le programme a un test pour lui-même, nous pouvons exécuter la vérification sur le code décompilé.

Nous utilisons des processus automatisés pour trouver des bogues. Dans les trackers de problèmes des autres décompilateurs, vous trouverez plusieurs bogues que nous avons découverts en cours de route. Très peu d'entre eux sont corrigés dans les autres décompilateurs.

Prérequis

Le code dans le dépôt git peut être exécuté de Python 2.4 à la dernière version de Python, à l'exception de Python 3.0 à 3.2. Les bénévoles sont les bienvenus pour remédier à ces lacunes si le désir s'en fait sentir.

La façon dont il fait cela, cependant, est en séparant les versions consécutives de Python dans des branches git :

master Python 3.11 et supérieur (utilise l'installation poetry et les idiomes Python plus récents) python-3.6-to-3.10 Python 3.6 à 3.10 (utilise les f-strings plus récentes, des idiomes plus modernes et des annotations de type plus modernes) python-3.3-to-3.5 Python 3.3 à 3.5 (Python 3 générique) python-3.0-to-3.2 Python 3.0 à 3.2 (Début Python 3 ; 3.0 était dans certains domaines plus proche de Python 2.6 que de Python 2.7) python-2.4-to-2.7 Python 2.4 à 2.7 (Python 2 générique)

PyPy à partir de la version 2.4 fonctionne également.

Les fichiers bytecode qu'il peut lire ont été testés sur les bytecodes Python des versions 1.4, 2.1-2.7, 3.0-3.8 et versions ultérieures de PyPy.

Installation

Pour les versions récentes de Python (Python 3.11+), vous pouvez installer depuis PyPI en utilisant le nom uncompyle6 ::

pip install uncompyle6

Pour les versions de Python antérieures à 3.11, n'installez pas via PyPI, mais installez plutôt en utilisant un fichier dans la section GitHub Releases. Les anciennes versions de Python utilisaient easy_install <https://python101.pythonlibrary.org/chapter29_pip.html#using-easy-install>_. Mais cela n'est plus supporté sur PyPi ni sur les versions plus récentes de Python. Et inversement, poetry ni pip, (les méthodes plus récentes) ne sont pas supportés sur les anciennes versions de Python.

Si la version de Python sur laquelle vous exécutez uncompyle6 se situe entre Python 2.4 et 2.7, utilisez une archive tar appelée uncompyle6_24-x.y.z.tar.gz.

Si la version de Python sur laquelle vous exécutez uncompyle6 se situe entre Python 3.0 et 3.2, utilisez une archive tar appelée uncompyle6_30-x.y.z.tar.gz.

Si la version de Python sur laquelle vous exécutez uncompyle6 se situe entre Python 3.3 et 3.5, utilisez une archive tar appelée uncompyle6_33-x.y.z.tar.gz.

Si la version de Python sur laquelle vous exécutez uncompyle6 se situe entre Python 3.6 et 3.11, utilisez une archive tar appelée uncompyle6_36-x.y.z.tar.gz.

Si la version de Python sur laquelle vous exécutez uncompyle6 est 3.11 ou ultérieure, utilisez une archive tar appelée uncompyle6-x.y.z.tar.gz.

Vous pouvez également essayer des eggs ou wheels qui ont la même désignation de version, par exemple uncompyle6-x.y.z-py39-none-any.whl pour une installation Python 3.9. *Cependant, notez que la version sans désignation signifie Python 3.11 ou supérieur.

De même, une archive tar sans _xx fonctionne uniquement à partir de Python 3.11 ou supérieur.

Justification de l'utilisation des branches Git +++++++++++++++++++++++++++++++++++++++++++++++

Il est actuellement impossible (sinon peu pratique) d'avoir un seul code source Python de cette complexité et avec autant de fonctionnalités qui puisse fonctionner à la fois sur Python 2.7 et Python 3.13+. Les langages ont tellement divergé, et le packaging est très différent. En fait, la pratique d'empaquetage pour Python 3.11+ est incompatible avec Python 2.7 (et avant jusqu'à Python 2.4), qui privilégiait 'easy_install'.

Installation à partir du code source +++++++++++++++++++++++++++++++++++++

Pour installer à partir du code source, assurez-vous d'avoir la bonne branche Git. Voir la section Prérequis pour les noms des branches Git.

Après avoir défini la bonne branche ::

$ pip install -e .  # set up to run from source tree

Un Makefile GNU est également fourni, donc :code:make install (éventuellement en tant que root ou via sudo) effectuera les étapes ci-dessus.

Exécution des tests

make check

Un Makefile GNU a été ajouté pour faciliter la configuration et l'exécution de la bonne commande, et pour exécuter les tests du plus rapide au plus lent.

Si vous avez remake_ installé, vous pouvez voir la liste de toutes les tâches, y compris les tests, via :code:remake --tasks

Utilisation

Exécutez

$ uncompyle6 compiled-python-file-pyc-or-pyo

Pour obtenir de l'aide sur l'utilisation :

$ uncompyle6 -h

Vérification

Dans les versions plus anciennes de Python, il était possible de vérifier le bytecode en le décompilant puis en le compilant en utilisant l'interpréteur Python pour cette version de bytecode. Ceci fait, le bytecode produit pouvait être comparé au bytecode original. Cependant, à mesure que la génération de code Python s'est améliorée, cela n'est plus réalisable.

Si vous souhaitez une vérification de la syntaxe Python de la correction du processus de décompilation, ajoutez l'option :code:--syntax-verify. Cependant, la syntaxe Python change. Vous devriez utiliser cette option si le bytecode est le bon bytecode pour l'interpréteur Python qui vérifiera la syntaxe.

Vous pouvez également comparer les résultats avec une autre version de uncompyle6 car il y a parfois des régressions dans la décompilation d'un bytecode spécifique, à mesure que la qualité globale s'améliore.

Pour Python 3.7 et 3.8, le code dans decompyle3_ est généralement meilleur.

Ou essayez un autre décompilateur Python spécifique comme uncompyle2_, unpyc37_, ou pycdc_. Comme ces deux derniers fonctionnent différemment, les bogues ici ne s'y retrouvent souvent pas, et vice versa.

Il existe une classe intéressante de ces programmes qui est facilement disponible pour fournir une vérification plus forte : les programmes qui, lorsqu'ils sont exécutés, se testent eux-mêmes. Notre suite de tests les inclut.

Et Python est livré avec un autre ensemble de programmes de ce type : sa suite de tests pour la bibliothèque standard. Nous avons du code dans :code:test/stdlib pour faciliter ce type de vérification également.

Bogues connus / Restrictions

Le plus gros problème connu et potentiellement corrigeable (mais difficile) concerne la gestion du flux de contrôle. (Python a probablement l'ensemble d'instructions composées le plus diversifié et le plus tordu que j'aie jamais vu ; il y a des clauses 'else' sur les boucles et les blocs try que je soupçonne que beaucoup de programmeurs ignorent.)

Tous les décompilateurs Python que j'ai examinés ont des problèmes pour décompiler le flux de contrôle de Python. Dans certains cas, nous pouvons détecter une décompilation erronée et la signaler.

Le support Python est assez bon pour Python 2.

Pour les versions les plus anciennes de Python, la décompilation semble assez bonne, bien que nous n'ayons pas de tests automatisés en place pour les tests distribués de Python. De plus, nous n'avons pas d'interpréteur Python pour les versions 1.6 et 2.0.

Dans la série Python 3, le support Python est le plus fort autour de 3.4 ou 3.3 et diminue à mesure que l'on s'éloigne de ces versions. Python 3.0 est étrange en ce sens qu'il ressemble à certains égards plus à 2.6 qu'à 3.1 ou 2.7. Python 3.6 change les choses radicalement en utilisant des codes de mots plutôt que des codes d'octets. En conséquence, le champ de décalage de saut dans un argument d'instruction de saut a été réduit. Cela rend les instructions :code:EXTENDED_ARG désormais plus répandues dans les instructions de saut ; auparavant elles étaient rares. Peut-être pour compenser les instructions :code:EXTENDED_ARG supplémentaires, une optimisation de saut supplémentaire a été ajoutée. Donc en résumé, la gestion du flux de contrôle par des moyens ad hoc, comme c'est actuellement le cas, est pire.

Entre Python 3.5, 3.6 et 3.7, il y a eu des changements majeurs dans les instructions :code:MAKE_FUNCTION et :code:CALL_FUNCTION.

Python 3.8 supprime les instructions :code:SETUP_LOOP, :code:SETUP_EXCEPT, :code:BREAK_LOOP et :code:CONTINUE_LOOP, ce qui peut rendre la détection du flux de contrôle plus difficile, en l'absence de l'analyse de flux de contrôle plus sophistiquée qui est prévue. Nous verrons.

Actuellement, tous les numéros magiques Python ne sont pas supportés. Plus précisément, dans certaines versions de Python, notamment Python 3.6, le numéro magique a changé plusieurs fois au sein d'une même version.

Nous ne supportons que les versions publiées, pas les versions candidates. Notez cependant que le numéro magique d'une version publiée est généralement le même que celui de la dernière version candidate avant la publication.

Il existe également des interpréteurs Python personnalisés, notamment Dropbox, qui utilisent leur propre numéro magique et chiffrent le bytecode. Sauf pour l'ancien interpréteur Python 2.5 de Dropbox, ce genre de chose n'est pas pris en charge.

Nous ne gérons pas non plus PJOrion_ ou tout code obscurci. Pour PJOrion, essayez : PJOrion Deobfuscator_ pour désembrouiller le bytecode afin d'obtenir un bytecode valide avant d'utiliser cet outil ; pydecipher_ pourrait vous aider.

Ce programme ne peut pas décompiler les fichiers EXE Microsoft Windows créés par Py2EXE_, bien que nous puissions probablement décompiler le code après avoir extrait le bytecode correctement. Pydeinstaller <https://github.com/charles-dyfis-net/pydeinstaller>_ peut aider à dépaqueter les bundles Pyinstaller.

Le traitement de listes d'expressions ou d'instructions pathologiquement longues est lent. Nous ne gérons pas Cython_ ou MicroPython, qui n'utilisent pas de bytecode.

Il y a de nombreux bogues dans la décompilation. Et c'est vrai pour tous les autres décompilateurs CPython que j'ai rencontrés, même ceux qui prétendaient être 'parfaits' sur une version particulière comme 2.4.

À mesure que Python progresse, la décompilation devient également plus difficile car la compilation est plus sophistiquée et le langage lui-même est plus sophistiqué. Je soupçonne qu'il y aura moins de tentatives ad hoc comme unpyc37_ (qui est basé sur un décompilateur 3.3) simplement parce que c'est plus difficile à faire. La bonne nouvelle, du moins de mon point de vue, est que je pense comprendre ce qui est nécessaire pour résoudre les problèmes de manière plus robuste. Mais pour l'instant, tant que le projet n'est pas mieux financé, je n'ai pas l'intention de faire un effort sérieux pour supporter les versions Python 3.8 ou 3.9, y compris les bogues qui pourraient survenir. J'imagine qu'à un moment donné, je pourrais m'y intéresser.

Vous pouvez facilement trouver des bogues en exécutant les tests contre la suite de tests standard que Python utilise pour se vérifier. À tout moment, il existe des dizaines de problèmes connus qui sont assez bien isolés et qui pourraient être résolus si l'on consacrait du temps à le faire. Le problème est qu'il n'y a pas beaucoup de personnes qui ont travaillé sur la correction de bogues.

Certains des bogues dans 3.7 et 3.8 sont simplement une question de rétroportage des correctifs de decompyle3. Des volontaires ?

Vous pourriez rencontrer un bogue que vous souhaitez signaler. Veuillez le faire après avoir lu Comment signaler un bogue <https://github.com/rocky/python-uncompyle6/blob/master/HOW-TO-REPORT-A-BUG.md>_ et suivez les instructions lors de l'ouverture d'un problème <https://github.com/rocky/python-uncompyle6/issues/new?assignees=&labels=&template=bug-report.md>_.

Sachez qu'il se peut que cela n'attire pas mon attention pendant un certain temps. Si vous sponsorisez ou soutenez le projet d'une manière ou d'une autre, je prioriserai vos problèmes par rapport à la file d'attente des autres tâches que je pourrais faire à la place. Dans de rares situations, je peux effectuer une décompilation manuelle de bytecode contre rémunération. Cependant, cela est coûteux, généralement au-delà de ce que la plupart des gens sont prêts à dépenser.

Voir aussi

https://rocky.github.io/blackhat-asia-2024-additional/all-notes-print.html : Comment lire et écrire un décompilateur de bytecode de haut niveau : uncompyle6 decompyle3 -- BlackHat 2024 Asia (vidéo <https://www.youtube.com/watch?v=NA77SFncppE>_). Un grand merci aux organisateurs et aux relecteurs de m'avoir permis de parler. Ce genre de chose m'encourage à travailler sur des projets comme celui-ci.
https://github.com/rocky/python-decompile3 : Code beaucoup plus petit et plus moderne, axé sur 3.7 et 3.8. Les modifications qui y sont apportées seront migrées ici.
https://code.google.com/archive/p/unpyc3/ : supporte uniquement Python 3.2. Les projets ci-dessus utilisent une technique de décompilation différente de celle utilisée ici. Actuellement non maintenu.
https://github.com/figment/unpyc3/ : fork du précédent, mais supporte uniquement Python 3.3. Inclut quelques correctifs comme le support des annotations de fonction. Actuellement non maintenu.
https://github.com/wibiti/uncompyle2 : supporte uniquement Python 2.7, mais le fait assez bien. Il y a des situations où les résultats de :code:uncompyle6 sont incorrects, alors que ceux de :code:uncompyle2 ne le sont pas, mais le plus souvent uncompyle6 est correct quand uncompyle2 ne l'est pas. Parce que :code:uncompyle6 privilégie la précision plutôt que le Python idiomatique, :code:uncompyle2 peut produire un code plus naturel lorsqu'il est correct. Actuellement :code: est légèrement maintenu. Voir son _ de problèmes pour plus de détails.

python-uncompyle6

Populaires