[!IMPORTANT]
Ce dépôt est désormais archivé. Même si ce fut un voyage amusant, je pense que PSArmoury a perdu son utilité.

PowerShellArmoury

Le PowerShell Armoury est conçu pour les pentesteurs, les « membres d’équipe de toutes les couleurs » et toute personne utilisant une variété d’outils PowerShell lors de ses missions. Il vous permet de télécharger et de stocker tous vos scripts PowerShell préférés dans un seul fichier obfusqué.

Vous n’avez plus à vous soucier de la mise à jour manuelle de Rubeus, PowerView, etc. Créez simplement un fichier de configuration une fois ou utilisez celui par défaut fourni avec l’outil. Désormais, il vous suffit d’exécuter « New-PSArmoury » avant de vous lancer dans votre prochaine mission. De plus, PSArmoury obfusque votre code et intègre un contournement AMSI. La conception modulaire devrait vous permettre de modifier facilement le code d’évasion ou d’obfuscation en cas de détection.

Structure générale

La version actuelle de PSArmoury privilégie une conception modulaire.

 New-PSArmoury.ps1
 PSArmoury.json
 utilities
    ConvertTo-Powershell.ps1
    Invoke-Shuffle.ps1
 modules
    evasion.ps1
    obfuscation.ps1

Le code est divisé en un script générateur principal appelé New-PSArmoury.ps1, qui est celui que vous exécutez. Le code pour l’évasion, l’obfuscation et la désobfuscation est stocké dans des fichiers .ps1 séparés dans le répertoire modules. Ces fichiers séparés sont appelés par le script principal et devraient vous permettre de modifier plus facilement des fonctions spécifiques (comme un contournement AMSI). En plus du répertoire modules, il y a aussi le répertoire utilities. Vous y trouverez des scripts autonomes qui peuvent être utiles dans des scénarios spécifiques.

Le répertoire modules

Le chemin par défaut du répertoire modules est .\modules, où le point fait référence au répertoire de travail actuel de votre shell. Vous pouvez modifier le chemin du répertoire modules en utilisant l’argument -ModulesDirectory de New-PSArmoury. Les noms des fichiers de script eux-mêmes sont cependant codés en dur dans le script principal et doivent toujours être :

• evasion.ps1
• obfuscation.ps1

Examinons ces deux fichiers de plus près.

evasion.ps1

Ce script doit contenir le code destiné à contourner ce que vous souhaitez contourner. Par défaut, il contient un contournement AMSI bien connu (merci amsi.fail). Veuillez noter que :

• le code ici s’exécute AVANT tout le reste (par exemple, la désobfuscation)
• il n’y a ABSOLUMENT AUCUNE VALIDATION ! Tout ce que vous mettez ici sera redirigé vers IEX tel quel.

obfuscation.ps1

Ce script doit contenir le code utilisé pour l’obfuscation et la désobfuscation. Le fichier obfuscation.ps1 par défaut utilise le chiffrement RC2. Exemples prêts à l’emploi :

• TEMPLATE_obfuscation_RC2.ps1 --> c’est le fichier par défaut
• TEMPLATE_obfuscation_byte_convert.ps1
• TEMPLATE_obfuscation_empty.ps1

Notez que le fichier TEMPLATE_obfuscation_empty.ps1 ne fait vraiment rien du tout et sert de modèle pour que vous construisiez votre propre fonction.

Si vous souhaitez utiliser l’un de ces fichiers, renommez-le simplement en « obfuscation.ps1 » et supprimez le fichier par défaut.

Si vous souhaitez créer une version personnalisée, gardez à l’esprit les points suivants concernant l’obfuscation :

• Le nom de la fonction DOIT toujours être « Get-PSArmouryObfuscation » avec un seul paramètre chaîne appelé « Code », car c’est ce que le script principal appellera pour chaque élément que vous souhaitez placer dans l’armurerie.
• La fonction DEVRAIT retourner la version obfusquée du code sous forme d’une seule valeur chaîne. Le code principal des scripts exécute une boucle supplémentaire de codage/décodage base64 pour garantir que nous puissions également gérer d’autres éléments que vous lui transmettez, mais il serait plus simple que vous puissiez simplement le renvoyer en tant que chaîne ;-)
• La fonction de désobfuscation correspondante DOIT comprendre tout ce que vous renvoyez ici. Le script principal se contente de transmettre les résultats – aucune magie ici.

Et n’oubliez pas ces points concernant la désobfuscation :

• Le nom de la fonction DOIT toujours être Get-PSArmouryDeObfuscation sans paramètre, car elle itère sur une variable globale fixe.
• La fonction DOIT retourner la version désobfusquée du code sous forme d’une seule valeur chaîne, prête à être exécutée. Nous redirigeons tout ce que vous renvoyez vers IEX, le reste vous appartient.

Le répertoire utilities

Le répertoire utilities contient des scripts autonomes utiles.

• ConvertTo-Powershell.ps1
  • Convertit une application console C# en script PowerShell. Pour plus de détails, voir l’article de blog correspondant.
• Invoke-Shuffle.ps1
  • Un script d’obfuscation simple qui convertit une seule ligne de code en plusieurs variables contenant des parties de la chaîne originale, qui sont ensuite fusionnées et invoquées lors de l’exécution.

Référence de configuration

Le fichier de configuration doit être un JSON valide composé d’un seul tableau contenant un ou plusieurs objets, chaque objet étant interprété comme une source de script unique. Chaque objet possède les attributs suivants :

Nom (Obligatoire)

Un nom de votre choix pour identifier le script inclus dans cet objet. C’est simplement une référence pour vous-même.

URL (Obligatoire)

L’emplacement pour obtenir le contenu du script. Il peut s’agir d’une URL vers une ressource web (https://), d’un chemin local (C:) ou d’une ressource réseau (\...). L’URL est transmise respectivement à Net.Webclient ou à Get-Item de PowerShell. En gros, tout format que l’un de ces deux peut gérer par défaut devrait fonctionner.

Type (Obligatoire)

Celui-ci donne une indication sur l’emplacement du script au créateur de l’armurerie. Il existe trois types valides :

• GitHub
  • Demandera des identifiants pour que nous puissions nous authentifier auprès de l’API GitHub. Tentera également de faire la distinction entre une URL « raw » pointant directement vers un fichier et une URL pointant vers un dépôt. Si l’URL pointe vers un dépôt, le script recherchera automatiquement tous les fichiers PowerShell de ce dépôt et les inclura. Exemple : « https://github.com/cfalta/PoshRandom »
• WebDownloadSimple
  • Signifie un fichier pouvant être téléchargé sans authentification via une requête HTTP GET. Exemple : « http://mywebserver.com/file.ps1 »
• LocalFile
  • Un fichier sur le disque, par exemple « C:\temp\test.ps1 ». Si le chemin pointe vers un répertoire, tous les fichiers (récursifs) avec l’extension « .ps1 » seront inclus.

FileInclusionFilter (Optionnel)

Sera interprété uniquement dans un objet de type « GitHub ». Sera comparé avec l’opérateur de comparaison « like » de PowerShell sur le nom complet du fichier, alors gardez à l’esprit que vous devez inclure les caractères génériques vous-même. N’oubliez pas d’inclure un astérisque (*) si vous souhaitez correspondre à une partie d’un nom de fichier. « *.ps1 » signifie tous les fichiers se terminant par « .ps1 », mais « .ps1 » signifie simplement « .ps1 ».

Vous n’êtes pas obligé d’inclure un filtre, mais si vous le faites, vous devez l’utiliser. Un InclusionFilter vide signifie aucun fichier.

FileExclusionFilter (Optionnel)

Comme le filtre d’inclusion, mais évidemment dans l’autre sens. L’exclusion a priorité.

Arguments

Voir l’aide PowerShell intégrée (man -full New-PSArmoury) pour plus de détails.

-Path

Le chemin vers votre nouveau fichier d’armurerie. La valeur par défaut est « .\MyArmoury.ps1 »

-FromFile

Chargez vos scripts PowerShell directement depuis un dossier ou fichier local sans avoir à fournir de fichier de configuration.

-Config

Le chemin vers votre fichier de configuration JSON. Jetez un œil à l’exemple fourni avec ce script pour des idées.

-ModulesDirectory

Le chemin vers le répertoire modules. La valeur par défaut est « .\modules ». Si ModulesDirectory est utilisé, les paramètres EvasionPath et ObfuscationPath ne peuvent pas être utilisés.

-EvasionPath

Le chemin vers le script d’évasion. Si EvasionPath et ObfuscationPath sont utilisés, le paramètre ModulesDirectory ne peut pas être utilisé.

-ObfuscationPath

Le chemin vers le script d’obfuscation. Si EvasionPath et ObfuscationPath sont utilisés, le paramètre ModulesDirectory ne peut pas être utilisé.

-ValidateOnly

Utilisez ceci avec « -Config » pour que le script valide la syntaxe de base de votre fichier de configuration JSON sans l’exécuter.

-GithubCredentials

Transmettez le nom d’utilisateur GitHub et le jeton d’accès sous forme d’objet d’identification afin que le script ne les demande pas. Utile si vous créez une armurerie à plusieurs reprises pour des tests.

Utilisation comme ceci :

$c = get-credential
New-PSArmoury -GithubCredentials $c

Jeton d’accès GitHub

Vous devez fournir un nom d’utilisateur GitHub valide ainsi qu’un jeton d’accès personnel afin que le script puisse utiliser correctement l’API GitHub. N’utilisez pas nom d’utilisateur/mot de passe car cela ne fonctionnera de toute façon pas si vous avez activé l’authentification multifacteur (MFA) (et vous devriez activer MFA). De plus, l’accès à l’API avec un nom d’utilisateur/mot de passe de base est déprécié.

Suivez ce guide pour créer un jeton d’accès personnel.

Veuillez noter : la seule autorisation dont nous avons besoin sur le jeton d’accès est public_repo dans la section repo.

En effet, vous n’avez besoin du jeton que pour que GitHub ne nous bloque pas si vous analysez des dépôts plus volumineux (comme PowerSploit) à la recherche de fichiers .ps1 à inclure.

Exemples d’utilisation

Exemple 1 – Par défaut

Si vous souhaitez créer une armurerie avec les paramètres par défaut (note : cela n’obfusquera rien en plus du codage base64), exécutez simplement ce qui suit.

. .\New-PSArmoury.ps1
New-PSArmoury

Cela créera un fichier .ps1 appelé « MyArmoury.ps1 » dans le répertoire de travail actuel en utilisant :

• la configuration par défaut « .\PSArmoury.json »
• le contournement AMSI par défaut situé dans « .\modules\evasion.ps1 »
• l’obfuscation/désobfuscation par défaut (base64) située respectivement dans « .\modules\obfuscation.ps1 » et « .\modules\deobfuscation.ps1 ».

Vous pouvez charger l’armurerie dans votre session actuelle en utilisant :

cat -raw .\MyArmoury.ps1 | iex

Le chargement de votre armurerie invoque les étapes suivantes :

• Exécution du code d’évasion
• Transfert du contrôle à la fonction de désobfuscation qui doit à son tour
• Parcourir chaque élément obfusqué et
  • le désobfusquer
  • le rediriger vers IEX

Après cela, tout le code PowerShell que vous avez placé dans l’armurerie sera disponible. Invoquez simplement les cmdlets comme d’habitude, par exemple :

Invoke-Rubeus -Command "kerberoast /stats"
Get-DomainGroupMember -Identity "Domain Admins" -Recurse

S’il vous arrive de ne pas vous souvenir de ce que vous avez mis dans l’armurerie, chargez-la et appelez l’inventaire :-)

Get-PSArmoury

Exemple 2 – Utiliser la technique d’obfuscation byte-convert/format JSON fournie avec PSArmoury et un fichier de configuration différent

Lancez New-PSArmoury avec les paramètres -EvasionPath et -ObfuscationPath comme ceci :

New-PSArmoury -Config C:\myarmouryconfig.json -ObfuscationPath .\modules\TEMPLATE_obfuscation_byte_convert.ps1 -EvasionPath .\modules\evasion.ps1

Exemple 3 – Créer une armurerie à partir d’un dossier local contenant des scripts PowerShell

Remarque : dans ce cas, tous les fichiers .ps1 du dossier seront ajoutés puisque nous soumettons un chemin de dossier. Si nous soumettons le chemin vers un seul fichier, seul ce fichier sera traité.

New-PSArmoury -FromFile C:\myscriptfolder