DbgShell

Un frontal PowerShell pour le moteur de débogage Windows.

Prêt à tabuler votre chemin vers la gloire ? Pour une introduction rapide, jetez un œil à Pour commencer.

Avertissements

1. Ce projet n'est pas produit, approuvé ni surveillé par l'équipe de débogage Windows. Bien que l'équipe de débogage accueille les commentaires concernant leur API et leurs interfaces (windbg, kd, etc.), elle n'a aucun lien avec ce projet. Ne signalez pas de bogues ou de retours à l'équipe de débogage concernant ce projet.

2. Ce projet n'est pas financé : aucune ressource officielle ne lui est allouée, et il n'est travaillé que par des bénévoles. Ne prenez aucune dépendance de production sur ce projet à moins d'être prêt à le supporter entièrement vous-même. N'hésitez pas à signaler des problèmes et à soumettre des Pull Requests, mais sachez qu'avec des ressources bénévoles limitées, il faudra peut-être un certain temps avant que vos soumissions soient traitées.

3. Ce projet est expérimental : il n'est pas complètement abouti, et vous devez vous attendre à des changements cassants souvent.

Corollaire des avertissements ci-dessus : j'éviterais d'attacher DbgShell à des cibles en direct de grande valeur.

Binaires

https://aka.ms/dbgshell-latest

Motivation

Avez-vous déjà essayé d'automatiser quelque chose dans le débogueur ? (cdb/ntsd/kd/windbg) Comment cela s'est-il passé pour vous ?

La principale impulsion pour DbgShell est qu'il est tout simplement beaucoup trop difficile d'automatiser quoi que ce soit dans le débogueur. Il existe certes des outils aujourd'hui pour aider à automatiser le débogueur, bien sûr. Mais à mon avis, ils ne répondent pas aux besoins des gens.

• L'utilisation du langage de script intégré est archaïque, limité, difficile à maîtriser, et difficile d'obtenir de l'aide.
• Écrire une DLL d'extension de débogueur complète est très puissant, mais c'est un investissement important—beaucoup trop coûteux pour résoudre des problèmes rapides et « uniques » lors du débogage de problèmes réels aléatoires. Malgré le coût, il existe un grand nombre d'extensions de débogueur dans l'existence. Je pense qu'il ne devrait pas y en avoir autant ; je pense que la seule raison pour laquelle il y en a autant est qu'il n'existe pas d'alternatives viables.
• Les tentatives existantes pour fournir une meilleure interface (comme PowerDbg) sont basées sur le « scraping » et l'analyse de texte, ce qui est extrêmement limitant (sans parler d'être idéologiquement ennuyeux) et ne peut donc pas tenir la promesse d'une interface vraiment meilleure (elles ne sont tout au plus que marginalement meilleures).
• Les tentatives existantes pour fournir un moyen plus simple d'écrire une extension de débogueur ne sont qu'un palliatif pour atténuer la douleur de développer une extension de débogueur ; elles ne résolvent pas vraiment le problème plus large. (par exemple, deux lacunes majeures sont : elles sont encore trop bas niveau (vous devez traiter avec l'API COM dbgeng), et il n'y a pas de REPL)
• L'équipe de débogage a récemment introduit Javascript scripting. Javascript est un langage bien meilleur (et mieux défini) que l'ancien langage de script windbg, mais je pense que PowerShell a certains avantages, dont le plus grand est que personne n'utilise vraiment un shell Javascript—PowerShell est bien meilleur en tant que shell et langage de script combinés.

L'objectif du projet DbgShell est d'apporter la bonté du monde objet de PowerShell au monde du débogage. Lorsque vous faites 'dt' pour vider un 'objet', vous devriez obtenir un objet réel. Le script devrait être aussi simple que d'écrire un script PowerShell.

Le projet DbgShell fournit une interface PowerShell pour dbgeng.dll, comprenant :

• un « modèle objet » géré (utilisable depuis C# si vous le souhaitez), qui est de plus haut niveau que l'API COM dbgeng,
• un « fournisseur de navigation » PowerShell, qui expose les aspects d'une cible de débogage sous forme d'un espace de noms hiérarchique (afin que vous puissiez « cd » vers un thread particulier, taper « dir » pour voir la pile, « cd » dans un frame, faire un autre « dir » pour voir les variables locales/registres/etc.),
• des cmdlets pour manipuler la cible,
• un hôte PowerShell personnalisé qui permet un meilleur contrôle de l'expérience CLI du débogueur, ainsi que la fourniture de fonctionnalités non disponibles dans l'hôte powershell.exe standard (à savoir, la prise en charge de la colorisation du texte à l'aide de codes d'échappement ANSI (à la ISO/IEC 6429))

L'hôte personnalisé est toujours un programme en ligne de commande (basé sur conhost.exe) (analogue à ntsd/cdb/kd), mais il peut être invoqué depuis windbg (!DbgShell).

En plus de rendre l'automatisation beaucoup plus facile et plus puissante, il répondra également à d'autres préoccupations, telles que la facilité d'utilisation pour les personnes qui n'ont pas à utiliser les débogueurs si souvent. (une plainte que j'ai entendue est que « quand je finis par devoir utiliser windbg, je passe tout mon temps dans le .CHM »)

Pour les utilisateurs expérimentés de windbg, d'autre part, un autre objectif est de rendre la transition aussi transparente que possible. Ainsi, par exemple, le fournisseur d'espace de noms n'est pas le seul moyen d'accéder aux données ; vous pouvez toujours utiliser des commandes traditionnelles comme « ~3 s », « k », etc.

Que voulez-vous dire par « automatisation » et « script » ?

Je ne parle pas uniquement de ce genre de choses où vous ouvrez un éditeur de texte et écrivez un gros script pour faire quelque chose de complexe—je parle aussi de pouvoir sortir des choses relativement simples directement en ligne de commande. Il existe de nombreuses situations où vous aimeriez pouvoir utiliser un peu de logique, mais rien d'assez gros ou réutilisable pour que vous vouliez même le sauvegarder. Il devrait être facile de sortir des « one-liners » comme « break sur CreateFile si le fichier en cours d'ouverture est sur le bureau de l'utilisateur et que la fonction Blah est dans la pile. »

Pourquoi PowerShell ?

Soyons clairs : il m'a fallu environ 4 ans pour « apprivoiser » PowerShell. Je ressens qu'il a des angles vifs, des aspects qui sont simplement difficiles, et plein de bugs, tant dans la conception que dans l'implémentation. Parfois, cela m'irrite vraiment. Cependant, les avantages de PowerShell sont convaincants et m'ont convaincu que c'est la meilleure chose à utiliser pour ce projet :

• C'est à la fois un environnement de script et un environnement CLI. Le fait qu'il doive faire les deux conduit à certaines choses négatives comme une courbe d'apprentissage plus abrupte, mais au final c'est extrêmement pratique, car vous voulez pouvoir à la fois faire des choses rapidement dans un REPL en ligne de commande, ainsi qu'écrire des scripts robustes et complets.
• Il est très découvrable—des choses comme Get-Command, la complétion par tabulation, la capacité d'exposer des données hiérarchiques comme un système de fichiers, les facilités pour fournir et synthétiser de l'aide, sont très bonnes.
• La complétion par tabulation. Je sais que je l'ai mentionnée dans le point précédent, mais elle est assez géniale pour mériter son propre point.
• Le pipeline d'objets : la nature orientée objet du pipeline PowerShell est tellement plus puissante et facile à utiliser que les mauvais vieux jours du script basé sur l'analyse de chaînes que ce n'est même pas drôle. Imaginez faire « dt » pour « vider » un « objet », et obtenir réellement un objet. DbgShell fait cela.
• Les gens le connaissent : j'estime que le nombre de personnes qui connaissent PowerShell et/ou C# est au moins plusieurs ordres de grandeur plus grand que les personnes qui connaissent les techniques de script windbg. Cela signifie que plus de personnes pourront facilement « prendre en main » un débogueur basé sur PowerShell ; et cela signifie aussi que lorsque les gens ont besoin d'aide, le pool d'aide potentiel est beaucoup plus large (pour les problèmes de script, en tout cas).
• PowerShell est toujours un shell généraliste : lors de l'utilisation de DbgShell, vous avez accès non seulement aux commandes du débogueur, mais vous pouvez « cd » vers le système de fichiers, le registre, AD, etc. ; vous pouvez exécuter Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod, exécuter des programmes arbitraires, etc.

Statut actuel

DbgShell est en « mode prototypage » depuis longtemps. J'ai passé beaucoup de temps à déterminer comment quelque chose pourrait ou devrait être fait, mais pas nécessairement à « finir » tout. Il y a un nombre énorme de TODOs dans le code actuel. Bien qu'il ait commencé à devenir réellement utile, le projet est encore assez vert. Cependant, il peut certainement démontrer assez pour vous donner un bon aperçu de ce à quoi il devrait ressembler.

Voici quelques captures d'écran. Il est important de noter que rien de ce que vous voyez n'est un texte de sortie dbgeng. Bien que certains éléments de la sortie vous sembleront familiers, c'est uniquement parce que j'ai utilisé les fonctionnalités de formatage et de sortie de PowerShell pour personnaliser la façon dont certains objets sont affichés—toute la sortie que vous voyez correspond en réalité à de véritables objets .NET complets. Par exemple, ces messages ModLoad correspondent chacun à un objet MS.Dbg.ModuleLoadedEventArgs, qui a plus de propriétés que celles affichées lorsqu'ils sont envoyés à Out-Default. Il n'y a aucune analyse de chaîne de quoi que ce soit de dbgeng. (Enfin... presque. J'ai fait quelques compromis là où il n'y a pas d'autre moyen d'obtenir des informations. Par exemple, le désassemblage, ou l'analyse du nom symbolique d'une fonction d'ajusteur de thunk pour trouver le décalage.)

Voici une sorte de scénario « hello world » : s'attacher à une instance de cmd.exe. J'utilise d'abord la commande intégrée PowerShell Start-Process, puis je dirige la sortie vers la commande DbgShell Connect-Process, et ensuite je me promène dans l'espace de noms :

Ici, je me suis attaché à un programme de test, j'ai regardé la pile, suis passé à un frame de pile particulier, vidé les variables locales, inspecté la valeur d'un std::map local, et inspecté des informations de type pour une valeur d'énumération locale. Notez l'affichage de la valeur d'énumération : non seulement DbgShell gère la recherche du nom symbolique pour les énumérants simples, mais aussi lorsque plusieurs énumérants sont combinés par OR. Vous ne pouvez pas le dire à partir de la capture d'écran, mais il y a une complétion par tabulation pour tout cela.

Fonctionnalités notables

• Couleur: prise en charge de la colorisation du texte à l'aide de codes d'échappement ANSI (à la ISO/IEC 6429)
• Moteur de formatage personnalisé: Vous n'aimez pas le .ps1xml ? Moi non plus. En plus des vues standard table, liste et personnalisées, vous pouvez définir des vues « sur une seule ligne » qui sont très pratiques pour personnaliser l'affichage des valeurs de symboles.
• Conversion personnalisée de valeur de symbole: Pour la plupart des variables, la conversion et l'affichage par défaut sont bons. Mais parfois, vous aimeriez que le débogueur fasse un peu plus de travail pour vous. La fonction de conversion de valeur de symbole permet, par exemple, aux objets de collection STL d'être transformés en objets de collection .NET beaucoup plus faciles à manipuler.
• Détection de type dérivé: Pour lorsque votre variable est un IFoo, mais que l'objet réel est un FooImpl.
• Informations de type riches: exposées pour votre plaisir programmatique.
• Q: Est-ce que ça fonctionne dans WinDbg ? Je n'utiliserai que WinDbg. R: Oui—chargez la DLL d'extension DbgShellExt.dll, puis exécutez « !dbgshell » pour ouvrir une console DbgShell.

Déficiences actuelles

• La plus grande lacune actuellement est qu'il ne prend pas bien en charge le mode noyau (si vous êtes déjà dans le contexte approprié, vous pouvez afficher des valeurs, mais vous ne pouvez pas changer de contexte depuis DbgShell, et l'espace de noms n'est pas câblé).
• Bien que vous puissiez charger et exécuter des extensions de débogueur traditionnelles de la manière habituelle, il manque encore de nombreuses commandes windbg.
• Les connexions à distance ne sont pas prises en charge : l'API dbgeng prend en charge la connexion à un débogueur distant. Malheureusement, les informations de symbole et de type exposées par l'API dbgeng sont gravement insuffisantes pour les besoins de DbgShell, donc DbgShell utilise l'API dbghelp. Malheureusement, il n'existe pas de dbghelp distant. Nous devrons travailler avec l'équipe de débogage pour résoudre ce problème.

Licence

Sous licence MIT.

Contribuer

Ce projet accepte les contributions et les suggestions. La plupart des contributions nécessitent que vous acceptiez un Contrat de Licence de Contributeur (CLA) déclarant que vous avez le droit, et que vous nous accordez effectivement, les droits d'utiliser votre contribution. Pour plus de détails, visitez https://cla.microsoft.com.

Lorsque vous soumettez une pull request, un bot CLA déterminera automatiquement si vous devez fournir un CLA et décorera la PR en conséquence (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n'aurez besoin de faire cela qu'une seule fois pour tous les dépôts utilisant notre CLA.

Voir Contributing pour plus d'informations sur la contribution au projet.

Code de conduite

Ce projet a adopté le Code de conduite Open Source Microsoft.

Pour plus d'informations, consultez la FAQ sur le Code de conduite ou contactez [email protected] pour toute question ou commentaire supplémentaire.

Autres sujets

• Pour commencer avec DbgShell

• Couleur

• Moteur de formatage personnalisé

• Conversion personnalisée de valeur de symbole

• Détection de type dérivé

• Informations de type riches

• Hacker sur DbgShell

• DbgEngWrapper

Vous pouvez trouver une courte introduction vidéo (3 minutes) ici : https://youtu.be/ynbg2zZ1Igc