{"id":13598940,"url":"https://github.com/cfalta/PowerShellArmoury","last_synced_at":"2025-04-10T10:30:44.354Z","repository":{"id":38237794,"uuid":"88872604","full_name":"cfalta/PowerShellArmoury","owner":"cfalta","description":"A PowerShell armoury for security guys and girls","archived":true,"fork":false,"pushed_at":"2024-01-23T10:28:33.000Z","size":103,"stargazers_count":461,"open_issues_count":0,"forks_count":67,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-06T23:40:53.624Z","etag":null,"topics":["amsi","avbypass","encryption","powershell","redteam-tools","security-tools","windows"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfalta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-20T14:05:58.000Z","updated_at":"2024-10-19T08:31:36.000Z","dependencies_parsed_at":"2024-11-06T23:36:29.299Z","dependency_job_id":null,"html_url":"https://github.com/cfalta/PowerShellArmoury","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfalta%2FPowerShellArmoury","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfalta%2FPowerShellArmoury/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfalta%2FPowerShellArmoury/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfalta%2FPowerShellArmoury/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfalta","download_url":"https://codeload.github.com/cfalta/PowerShellArmoury/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199136,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amsi","avbypass","encryption","powershell","redteam-tools","security-tools","windows"],"created_at":"2024-08-01T17:00:58.304Z","updated_at":"2025-04-10T10:30:44.348Z","avatar_url":"https://github.com/cfalta.png","language":"PowerShell","readme":"\u003e [!IMPORTANT]  \n\u003e This repository is now archived. Though it was a fun journey, I think PSArmoury has outlived its usefulness.\n\u003c/br\u003e\n\n# PowerShellArmoury\n\n\u003cimg align=\"left\" width=\"200\" height=\"300\" src=\"https://user-images.githubusercontent.com/7213829/72599954-fae92780-3912-11ea-9ad4-7da273ee75dd.png\"\u003e\n\nThe PowerShell Armoury is meant for pentesters, \"insert-color-here\"-teamers and everyone else who uses a variety of PowerShell tools during their engagements. It allows you to download and store all of your favourite PowerShell scripts in a single, obfuscated file.\n\nYou do not have to hassle with updating Rubeus, PowerView, ... manually. Just create a configuration file once or use the default one included with the tool. From now on, you just have to run \"New-PSArmoury\" before you head to the next engagement.\nIn addition, PSArmoury obfuscates your code and comes with an included AMSI bypass. The modular design should it make it easy for you to change the evasion or obfuscation code in case there's a detection on that.\n\n\u003c/br\u003e\n\u003c/br\u003e\n\n## General structure\n\nThe current version of PSArmoury favours a modular design. \n\n```\n New-PSArmoury.ps1\n PSArmoury.json\n utilities\n    ConvertTo-Powershell.ps1\n    Invoke-Shuffle.ps1\n modules\n    evasion.ps1\n    obfuscation.ps1\n```\n\nThe code is split into a main generator script called `New-PSArmoury.ps1`, which is the one you execute. The code for evasion, obfuscation and deobfuscation is stored in separate .ps1 files in the `modules` directory. These separate files are invoked by the main script and should make it easier for you to change specific functions (like an AMSI bypass).\nIn addition to the modules directory, there's also the `utilities` directory. Here you'll find standalone scripts that can be useful in specific scenarios.\n\n## The modules directory\n\nThe default path of the modules directory is `.\\modules` where the dot refers to the current working directory of your shell. You can change the path of the modules directory by using the `-ModulesDirectory` argument of `New-PSArmoury`. \nThe names of the script files themselves however are hard-coded in the main script and always expected to be:\n\n- evasion.ps1\n- obfuscation.ps1\n\nLet's have a closer look at these two.\n\n### evasion.ps1\n\nThis script should contain the code intended to bypass whatever you intend to bypass. By default, it contains a well-known AMSI bypass (thanks amsi.fail).\nPlease note that:\n- the code in here runs BEFORE everything else runs (e.g. deobfuscation)\n- there is absolutely NO KIND OF VALIDATION! Everything you put here will be piped to IEX as is.\n\n### obfuscation.ps1\n\nThis script should contain the code used for obfuscation and deobfuscation. The default obfuscation.ps1 uses RC2 encryption. Ready-to-use examples:\n\n- TEMPLATE_obfuscation_RC2.ps1 --\u003e this is the default\n- TEMPLATE_obfuscation_byte_convert.ps1\n- TEMPLATE_obfuscation_empty.ps1\n\nNote that the `TEMPLATE_obfuscation_empty.ps1` really does nothing at all and serves as a template for you to build your own function.\n\nIf you want to use any one of those, just rename it to \"obfuscation.ps1\" and delete the default file.\n\nIf you want to create a customized version, keep the following in mind regarding obfuscation:\n- The function name MUST always be \"Get-PSArmouryObfuscation\" with a single string-parameter called \"Code\" cause that's what the main script will call on any item you want to put in the armoury.\n- The function SHOULD return the obfuscated version of the code again as a single string value. The main code of the scripts runs an additonal base64 encode/decode loop to make sure that we can also handle other stuff you throw at it but it would be easier if you could just make it a string ;-)\n- The corresponding deobfuscation function MUST understand whatever you return here. The main script is just passing around results --\u003e no magic happens here\n\nAnd make sure to remember these things in terms of deobfuscation:\n- The function name MUST always be Get-PSArmouryDeObfuscation with no parameter since it itterates over a fixed, global variable.\n- The function MUST return the deobfuscated version of the code again as a single string value, ready to execute. We are just piping everything you return into IEX so the rest is up to you.\n\n## The utilities directory\n\nThe utilities directory contains useful standalone scripts.\n\n- ConvertTo-Powershell.ps1\n    - Converts a console c# application into a powershell script. For more details, see [the corresponding blog post](https://cyberstoph.org/posts/2020/09/convertto-powershell-wrapping-applications-with-ps/).\n- Invoke-Shuffle.ps1\n    - A simple obfuscation script that converts a single line of code into multiple variables holding parts of the original string that are then merged and invoked during execution.\n\n## Config reference\n\nThe config file needs to be a valid json that consists of a single array with one or more objects, where every object is interpreted as a single script source. Every object has the following attributes\n\n**Name (Mandatory)**\n\nA name of your choice to identify the script included in this object. This is just meant as a reference for yourself.\n\n**URL (Mandatory)**\n\nThe location to get the script content from. This can be a URL to a web resource (https://) or a local path (C:\\) or a network resource (\\\\...). The URL is thrown into Net.Webclient or Powershells Get-Item respectively. So basically every format that one of those two can handle by default should work.\n\n**Type (Mandatory)**\n\nThis gives a hint about the script location to the armoury creator. There are three valid types:\n\n- GitHub\n    - Will prompt for credentials so we can authenticate against the github API. Will also try to distinguish between a \"raw\" URL that directly poins to a file or a URL that points to a repository. If the URL points to a repository, the script will automatically search all Powershell files in that repository and include them. Like \"https://github.com/cfalta/PoshRandom\"\n- WebDownloadSimple\n    - Means a file that can be downloaded without authentication or stuff using an HTTP GET. Like \"http://mywebserver.com/file.ps1\"\n- LocalFile\n    - A file on disk like \"C:\\temp\\test.ps1\". If the path points to a directory, all files (recursive) with the extension \".ps1\" will be included. \n\n**FileInclusionFilter (Optional)**\n\nWill only be interpreted in an object of type \"GitHub\". Will be matched with Powershells \"like\" comparison operator against the whole filename so keep in mind that you need to include the wildcards yourself. Don't forget to include a star (\\*) if you want to match part of a filename. \"*.ps1\" means all files that end with \".ps1\" but \".ps1\" just means \".ps1\".\n\nYou don't have to include a filter but if you do, you have to use it. An empty InclusionFilter means no files.\n\n**FileExclusionFilter (Optional)**\n\nLike the InclusionFilter but obviously the other way round. Exclusion takes precedence.\n\n## Arguments\n\nSee inline Powershell help (man -full New-PSArmoury) for more details.\n\n**-Path**\n\nThe path to your new armoury file. The default ist \".\\MyArmoury.ps1\"\n\n**-FromFile**\n\nLoad your Powershell scripts directly from a local folder or file and you don't have to provide a config file.\n\n**-Config**\n\nThe path to your JSON-config file. Have a look at the sample that comes with this script for ideas.\n\n**-ModulesDirectory**\n\nThe path to the modules directory. The default is \".\\modules\".\nIf ModulesDirectory is used, then the EvasionPath and ObfuscationPath Parameters cannot be used.\n\n**-EvasionPath**\n\nThe path to the evasion script. If EvasionPath and ObfuscationPath are used, then the ModulesDirectory-Parameter cannot be used.\n\n**-ObfuscationPath**\n\nThe path to the obfuscation script. If EvasionPath and ObfuscationPath are used, then the ModulesDirectory-Parameter cannot be used.\n\n**-ValidateOnly**\n\nUse this together with \"-Config\" to let the script validate the basic syntax of your JSON config file without executing it.\n\n**-GithubCredentials**\n\nPass Github username and access token as a credential object so the script won't prompt for it. Useful if you create an armoury repeatedly for testing.\n\nUse like this:\n\n``` powershell\n$c = get-credential\nNew-PSArmoury -GithubCredentials $c\n```\n\n## Github access token\n\nYou have to provide a valid github username as well as a personal access token, so the script can properly use the github API. Do not use username/password since this will not work anyway if you have MFA enabled (and you should enable MFA). Also accessing the API with basic username/password is deprecated.\n\nFollow [this guide](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) to create a personal access token. \n\n**Please note: the only permission we need on the access token is `public_repo` in the `repo` section.**\n\nThis is because you only need the token so Github won't block us if you parse larger repositories (like PowerSploit) for .ps1 files to include.\n\n## Example usage\n\n### Example 1 - All default\n\nIf you want to create an armoury with default settings (note: this will not obfuscate at all besides base64 encoding), then just run the following.\n\n``` powershell\n. .\\New-PSArmoury.ps1\nNew-PSArmoury\n```\nThis will create a .ps1 file called \"MyArmoury.ps1\" in the current working directory using\n- the default config \".\\PSArmoury.json\"\n- the default AMSI bypass found at \".\\modules\\evasion.ps1\"\n- the default obfuscation/deobfuscation (base64) found at \".\\modules\\obfuscation.ps1\" and \".\\modules\\deobfuscation.ps1\" respectively.\n\nYou can load the armoury into your current session by using\n\n``` powershell\ncat -raw .\\MyArmoury.ps1 | iex\n```\n\nLoading your armoury invokes the following steps:\n* Invoke evasion code\n* Hand over control to the deobfuscation function which in turn should\n* Go over every obfuscated item and \n    * deobfuscate\n    * pipe into IEX\n\nAfter that, all powershell code you put in the armoury will be available. Just invoke the cmdlets as usual like this\n\n``` powershell\nInvoke-Rubeus -Command \"kerberoast /stats\"\nGet-DomainGroupMember -Identity \"Domain Admins\" -Recurse\n```\n\nIf it happens that you don't remember what you put inside the armoury, just load it and call the inventory :-)\n\n``` powershell\nGet-PSArmoury\n```\n\n### Example 2 - Use the byte-convert/json-format obfuscation technique that comes with PSArmoury and different config file\n\nStart New-PSArmoury with the `-EvasionPath` and `-ObfuscationPath` Parameters like this:\n\n``` powershell\nNew-PSArmoury -Config C:\\myarmouryconfig.json -ObfuscationPath .\\modules\\TEMPLATE_obfuscation_byte_convert.ps1 -EvasionPath .\\modules\\evasion.ps1\n```\n\n### Example 3 - Create an armoury from a local folder containing powershell scripts\n\nNote: in this case, all .ps1 files in the folder will be added since we submit a folder path. If we submit the path to a single file, then only that file we be processed.\n\n``` powershell\nNew-PSArmoury -FromFile C:\\myscriptfolder\n```\n","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfalta%2FPowerShellArmoury","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfalta%2FPowerShellArmoury","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfalta%2FPowerShellArmoury/lists"}