Codecepticon is a .NET software that permits you to obfuscate C#, VBA/VB6 (macros), and PowerShell supply code, and is developed for offensive safety engagements akin to Pink/Purple Groups. What separates Codecepticon from different obfuscators is that it targets the supply code quite than the compiled executables, and was developed particularly for AV/EDR evasion.
Codecepticon permits you to obfuscate and rewrite code, but in addition supplies options akin to rewriting the command line as nicely.
Learn This First
! Earlier than we start !
-
This documentation is on the best way to set up and use Codecepticon solely. Compilation, utilization, and assist for instruments like Rubeus and SharpHound won’t be supplied. Refer to every mission’s repo individually for extra info.
-
Codecepticon is actively developed/examined in VS2022, however it ought to work in VS2019 as nicely. Any tickets/points created for VS2019 and under, won’t be investigated except the difficulty is reproducible in VS2022. So please use the newest and best VS2022.
-
The next packages MUST be v3.9.0, as newer variations have the next concern which continues to be open: dotnet/roslyn#58463
- Microsoft.CodeAnalysis.CSharp.Workspaces
- Microsoft.CodeAnalysis.Workspaces.MSBuild
Codecepticon checks the model of those packages on runtime and can inform you if the model is totally different to v3.9.0.
-
It can’t be harassed this sufficient: at all times check your obfuscated code regionally first.
Conditions
Visible Studio Professional/Neighborhood 2022
Roslyn Compiler
Open and Compile
Open Codecepticon, wait till all NuGet packages are downloaded after which construct the answer.
Utilizing Codecepticon
There are two methods to make use of Codecepticon, both by placing all arguments within the command line or by passing a single XML configuration file. Because of the excessive stage of supported customisations, It is not advisable manually going by --help output to attempt to determine which parameters to make use of and the way. Use CommandLineGenerator.html and generate your command shortly:
The command generator’s output format might be both Console or XML, relying what you favor. Console instructions might be executed as:
Codecepticon.exe --action obfuscate --module csharp --verbose ...and many others
Whereas when utilizing an XML config file, as:
Codecepticon.exe --config C:YourPathToTheFile.xml
If you wish to deep dive into Codecepticon’s performance, take a look at this doc.
For suggestions you need to use, take a look at this doc.
C#
Obfuscating a C# mission is easy, merely choose the answer you want to goal. Be aware {that a} backup of the answer itself won’t be taken, and the present one would be the one which can be obfuscated. Just be sure you can independently compile the goal mission earlier than making an attempt to run Codecepticon in opposition to it.
VBA/VB6
The VBA obfuscation works in opposition to supply code itself quite than a Microsoft Workplace doc. Because of this you can not go a doc(x) or xls(x) file to Codecepticon. It should be the supply code of the module itself (press Alt-F11 and duplicate the code from there).
PowerShell
Because of the complexity of PowerShell scripts, together with the liberty it supplies in the best way to write scripts it’s difficult to cowl all edge circumstances and be sure that the obfuscated consequence can be absolutely purposeful. Though it is anticipated for Codecepticon to work wonderful in opposition to easy scripts/performance, working it in opposition to advanced ones akin to PowerView won’t work – this can be a work in progress.
Obfuscating Command Line Arguments
After obfuscating an software or a script, it is vitally possible that the command line arguments have additionally been renamed. The answer to that is to make use of the HTML mapping file to search out what the brand new names are. For instance, let’s convert the next command line:
SharpHound.exe --CollectionMethods DCOnly --OutputDirectory C:temp
By looking out by the HTML mapping file for every argument, we get:
And by changing all strings the result’s:
ObfuscatedSharpHound.exe --AphylesPiansAsp TurthsTance --AnineWondon C:temp
Nonetheless, some values might exist in multiple class:
Due to this fact it’s essential to at all times check your end in an area surroundings first.
FAQ
Why is not there a compiled model underneath Releases that I can obtain?
The compiled output contains quite a lot of dependency DLLs, which attributable to licensing necessities we won’t re-distribute with out written consent.
Does Codecepticon solely work for C# tasks that have already got a supported profile?
No, Codecepticon ought to work with every part. The profiles are only a bit of additional tweaks which might be performed to the goal mission with the intention to make it extra dependable and simpler to work with.
However as all code is exclusive, there can be situations the place obfuscating a mission will find yourself with an error or two that will not enable it to be compiled or executed. On this case a brand new profile could also be so as – please increase a brand new concern if that is so.
Identical precept applies to PowerShell/VBA code – though these at the moment don’t have any profiles that include Codecepticon, it is a simple activity so as to add if some are wanted.
Can I contribute?
For reporting bugs and suggesting new options, please create a difficulty.
For submitting pull requests, please see the Contributions part.
Troubleshooting
I am utilizing Codecepticon in opposition to a C# mission, it runs, however afterwards I am unable to compile the goal mission.
Earlier than working Codecepticon be sure to can compile a clear model of the goal mission. Fairly often when this concern seems, it is attributable to lacking dependencies for the goal resolution quite than Codecepticon. But when it nonetheless does not compile:
- Is it a public mission? Create a difficulty and paste the hyperlink with as a lot element as potential. If the device is a part of SharpCollection, even higher.
- Is it a personal mission? Within the spirit of bettering Codecepticon we’ll attempt to present as a lot assist as potential through screenshots and error/debug messages. However we won’t be accessing/working any clear/obfuscated code through personal repos and many others.
Identical as above, however it’s a PowerShell/VBA script – are you able to assist?
I’ll do my greatest, however as PowerShell scripts might be VERY advanced and the PSParser is not as superior as Roslyn for C#, no guarantees might be made. Identical applies for VBA/VB6.
I hold getting: “Technique not discovered: ‘System.Collections.Immutable.ImmutableArray”
You could in some unspecified time in the future encounter the next error:
Nonetheless making an attempt to unravel this one, a fast repair is to uninstall and reinstall the System.Collections.Immutable package deal, from the NuGet Bundle Supervisor.
Contributions
Whether or not it is a typo, a bug, or a brand new function, Codecepticon may be very open to contributions so long as we agree on the next:
- You’re OK with the MIT license of this mission.
- Earlier than making a pull request, create a difficulty so it may very well be mentioned earlier than doing any work as inner improvement just isn’t tracked through the general public GitHub repository. In any other case you danger having a pull request rejected if for instance we’re already engaged on the identical/comparable function, or for every other motive.
References / Credit
