Skip to content
This repository was archived by the owner on Jan 21, 2021. It is now read-only.

Commit 7157507

Browse files
author
mattifestation
committed
Added Capstone Engine PowerShell binding
Consider this to be an alpha release until the C# binding is published.
1 parent 46baff5 commit 7157507

File tree

10 files changed

+266
-0
lines changed

10 files changed

+266
-0
lines changed

‎Capstone/Capstone.psd1

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
@{
2+
3+
# Script module or binary module file associated with this manifest.
4+
ModuleToProcess = 'Capstone.psm1'
5+
6+
# Version number of this module.
7+
ModuleVersion = '1.0.0.0'
8+
9+
# ID used to uniquely identify this module
10+
GUID = 'bc335667-02fd-46c4-a3d9-0a5113c9c03b'
11+
12+
# Author of this module
13+
Author = 'Matthew Graeber'
14+
15+
# Copyright statement for this module
16+
Copyright = 'BSD 3-Clause'
17+
18+
# Description of the functionality provided by this module
19+
Description = 'Capstone Disassembly Framework Binding Module'
20+
21+
# Minimum version of the Windows PowerShell engine required by this module
22+
PowerShellVersion = '3.0'
23+
24+
# Minimum version of the common language runtime (CLR) required by this module
25+
CLRVersion = '4.0'
26+
27+
# Processor architecture (None, X86, Amd64) required by this module
28+
ProcessorArchitecture = 'Amd64'
29+
30+
# Assemblies that must be loaded prior to importing this module
31+
RequiredAssemblies = 'lib/capstone.dll'
32+
33+
# Format files (.ps1xml) to be loaded when importing this module
34+
FormatsToProcess = 'Get-CSDisassembly.format.ps1xml'
35+
36+
# Functions to export from this module
37+
FunctionsToExport = '*'
38+
39+
# List of all modules packaged with this module.
40+
ModuleList = @(@{ModuleName = 'Capstone'; ModuleVersion = '1.0.0.0'; GUID = 'bc335667-02fd-46c4-a3d9-0a5113c9c03b'})
41+
42+
# List of all files packaged with this module
43+
FileList = 'Capstone.psm1',
44+
'Capstone.psd1',
45+
'Get-CSDisassembly.ps1',
46+
'Usage.md',
47+
'lib/capstone.dll',
48+
'lib/libcapstone.dll'
49+
50+
}

‎Capstone/Capstone.psm1

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Get-ChildItem (Join-Path $PSScriptRoot *.ps1) | % { . $_.FullName}

‎Capstone/Get-CSDisassembly.format.ps1xml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<?xml version="1.0" encoding="utf-8" ?>
2+
<Configuration>
3+
<ViewDefinitions>
4+
<View>
5+
<Name>InstructionView</Name>
6+
<ViewSelectedBy>
7+
<TypeName>Capstone.Instruction</TypeName>
8+
</ViewSelectedBy>
9+
<TableControl>
10+
<AutoSize/>
11+
<TableHeaders>
12+
<TableColumnHeader>
13+
<Label>Address</Label>
14+
</TableColumnHeader>
15+
<TableColumnHeader>
16+
<Label>Mnemonic</Label>
17+
</TableColumnHeader>
18+
<TableColumnHeader>
19+
<Label>Operands</Label>
20+
</TableColumnHeader>
21+
</TableHeaders>
22+
<TableRowEntries>
23+
<TableRowEntry>
24+
<TableColumnItems>
25+
<TableColumnItem>
26+
<PropertyName>Address</PropertyName>
27+
<FormatString>0x{0:X8}</FormatString>
28+
</TableColumnItem>
29+
<TableColumnItem>
30+
<PropertyName>Mnemonic</PropertyName>
31+
</TableColumnItem>
32+
<TableColumnItem>
33+
<PropertyName>Operands</PropertyName>
34+
</TableColumnItem>
35+
</TableColumnItems>
36+
</TableRowEntry>
37+
</TableRowEntries>
38+
</TableControl>
39+
</View>
40+
</ViewDefinitions>
41+
</Configuration>

‎Capstone/Get-CSDisassembly.ps1

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
#requires -Version 3
2+
3+
function Get-CSDisassembly
4+
{
5+
<#
6+
.SYNOPSIS
7+
8+
Disassembles a byte array using the Capstone Engine disassembly framework.
9+
10+
PowerSploit Function: Get-CSDisassembly
11+
Author: Matthew Graeber (@mattifestation)
12+
License: See LICENSE.TXT
13+
Required Dependencies: lib\capstone.dll, lib\libcapstone.dll (64-bit)
14+
Optional Dependencies: None
15+
16+
.PARAMETER Architecture
17+
18+
Specifies the architecture of the code to be disassembled.
19+
20+
.PARAMETER Mode
21+
22+
Specifies the mode in which to disassemble code. For example, to disassemble Amd64 code, architecture is set to 'X86' and Mode is set to 'MODE_64'.
23+
24+
.PARAMETER Code
25+
26+
A byte array consisting of the code to be disassembled.
27+
28+
.PARAMETER Offset
29+
30+
Specifies the starting address of the disassembly listing.
31+
32+
.PARAMETER Count
33+
34+
Specifies the maximum number of instructions to disassemble.
35+
36+
.PARAMETER Syntax
37+
38+
Specifies the syntax flavor to be used (INTEL vs. ATT).
39+
40+
.PARAMETER DetailOff
41+
42+
Specifies that detailed parsing should not be performed - i.e. do not perform additional analysis beyond disassembling.
43+
44+
.EXAMPLE
45+
46+
C:\PS>$Bytes = [Byte[]] @( 0x8d, 0x4c, 0x32, 0x08, 0x01, 0xd8, 0x81, 0xc6, 0x34, 0x12, 0x00, 0x00 )
47+
C:\PS>Get-CSDisassembly -Architecture X86 -Mode MODE_16 -Code $Bytes -Offset 0x1000
48+
49+
.EXAMPLE
50+
51+
C:\PS>$Bytes = [Byte[]] @( 0x8d, 0x4c, 0x32, 0x08, 0x01, 0xd8, 0x81, 0xc6, 0x34, 0x12, 0x00, 0x00 )
52+
C:\PS>Get-CSDisassembly -Architecture X86 -Mode MODE_32 -Code $Bytes -Syntax ATT
53+
54+
.INPUTS
55+
56+
None
57+
58+
You cannot pipe objects to Get-CSDisassembly.
59+
60+
.OUTPUTS
61+
62+
Capstone.Instruction[]
63+
64+
Get-CSDisassembly returns an array of Instruction objects.
65+
66+
.NOTES
67+
68+
Get-CSDisassembly must be run from 64-bit PowerShell v3.
69+
#>
70+
71+
[OutputType([Capstone.Instruction])]
72+
[CmdletBinding()] Param (
73+
[Parameter(Mandatory)]
74+
[Capstone.ARCH]
75+
$Architecture,
76+
77+
[Parameter(Mandatory)]
78+
[Capstone.MODE]
79+
$Mode,
80+
81+
[Parameter(Mandatory)]
82+
[ValidateNotNullOrEmpty()]
83+
[Byte[]]
84+
$Code,
85+
86+
[UInt64]
87+
$Offset = 0,
88+
89+
[UInt32]
90+
$Count = 0,
91+
92+
[ValidateSet('Intel', 'ATT')]
93+
[String]
94+
$Syntax,
95+
96+
[Switch]
97+
$DetailOff
98+
)
99+
100+
$Disassembly = New-Object Capstone.Capstone($Architecture, $Mode)
101+
102+
if ($Syntax)
103+
{
104+
switch ($Syntax)
105+
{
106+
'Intel' { $SyntaxMode = [Capstone.OPT_VALUE]::SYNTAX_INTEL }
107+
'ATT' { $SyntaxMode = [Capstone.OPT_VALUE]::SYNTAX_ATT }
108+
}
109+
110+
$Disassembly.SetSyntax($SyntaxMode)
111+
}
112+
113+
if ($DetailOff)
114+
{
115+
$Disassembly.SetDetail($False)
116+
}
117+
118+
$Disassembly.Disassemble($Code, $Offset, $Count)
119+
}

‎Capstone/LICENSE.TXT

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
This is the software license for Capstone disassembly framework.
2+
Capstone has been designed & implemented by Nguyen Anh Quynh <[email protected]>
3+
See http://www.capstone-engine.org for further information.
4+
5+
Copyright (c) 2013, COSEINC.
6+
All rights reserved.
7+
8+
Redistribution and use in source and binary forms, with or without
9+
modification, are permitted provided that the following conditions are met:
10+
11+
* Redistributions of source code must retain the above copyright notice,
12+
this list of conditions and the following disclaimer.
13+
* Redistributions in binary form must reproduce the above copyright notice,
14+
this list of conditions and the following disclaimer in the documentation
15+
and/or other materials provided with the distribution.
16+
* Neither the name of the developer(s) nor the names of its
17+
contributors may be used to endorse or promote products derived from this
18+
software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23+
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24+
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25+
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26+
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27+
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28+
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29+
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30+
POSSIBILITY OF SUCH DAMAGE.

‎Capstone/Usage.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
This module has two dependencies:
2+
* lib\libcapstone.dll (the 64-bit unmanaged Capstone library)
3+
* lib\capstone.dll (the managed C# bindings to the Capstone Framework)
4+
5+
To install this module, drop the entire ScriptModification folder into one of your module directories. The default PowerShell module paths are listed in the $Env:PSModulePath environment variable.
6+
7+
The default per-user module path is: "$Env:HomeDrive$Env:HOMEPATH\Documents\WindowsPowerShell\Modules"
8+
The default computer-level module path is: "$Env:windir\System32\WindowsPowerShell\v1.0\Modules"
9+
10+
To use the module, type `Import-Module Capstone`
11+
12+
To see the commands imported, type `Get-Command -Module Capstone`
13+
14+
For help on each individual command, Get-Help is your friend.
15+
16+
Note: The tools contained within this module were all designed such that they can be run individually. Including them in a module simply lends itself to increased portability.

‎Capstone/lib/capstone.dll

76.5 KB
Binary file not shown.

‎Capstone/lib/libcapstone.dll

6.03 MB
Binary file not shown.

‎PowerSploit.psd1

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ ModuleList = @( @{ModuleName = 'PowerSploit'; ModuleVersion = '1.0.0.0'; GUID =
7979
@{ModuleName = 'ReverseEngineering'; ModuleVersion = '1.0.0.0'; GUID = 'cbffaf47-c55a-4901-92e7-8d794fbe1fff'},
8080
@{ModuleName = 'ScriptModification'; ModuleVersion = '1.0.0.0'; GUID = 'a4d86266-b39b-437a-b5bb-d6f99aa6e610'},
8181
@{ModuleName = 'Persistence'; ModuleVersion = '1.0.0.0'; GUID = '633d0f10-a056-41da-869d-6d2f75430195'}
82+
@{ModuleName = 'Capstone'; ModuleVersion = '1.0.0.0'; GUID = 'bc335667-02fd-46c4-a3d9-0a5113c9c03b'}
8283
)
8384

8485
# List of all files packaged with this module

‎README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,14 @@ Displays symbolic information from Windows lib files.
8080

8181
Returns the path from which Windows will load a Dll for the given executable.
8282

83+
## Capstone
84+
85+
**A PowerShell binding for the Capstone Engine disassembly framework.**
86+
87+
#### `Get-CSDisassembly`
88+
89+
Disassembles a byte array using the Capstone Engine disassembly framework.
90+
8391
## ReverseEngineering
8492

8593
**Tools to aid in reverse engineering.**

0 commit comments

Comments
 (0)