Skip to content

Commit b0a2bf0

Browse files
MichaelGrafnetterMichaelGrafnetter
committed
Documentation improvements
1 parent 39d092a commit b0a2bf0

27 files changed

+345
-225
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 170 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -23,20 +23,57 @@ Any contributions to this project are warmly welcome. These are the most importa
2323

2424
### Development Environment
2525

26-
If you want to build the module from source code yourself, you need to install these programs first:
26+
If you want to build the module from source code yourself,
27+
you will need a Windows machine with either the [Microsoft Visual Studio Community 2026](https://visualstudio.microsoft.com/vs/community/)
28+
or the [Build Tools for Visual Studio 2026](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2026)
29+
with these components installed:
2730

28-
- [Microsoft Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) 2026 with these features installed:
29-
- .NET Framework 4.8 targeting pack
30-
- C++ 2022 Redistributable Update
31-
- C++/CLI support for v143 build tools (Latest)
32-
- MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
33-
- MSVC v143 - VS 2022 C++ ARM64/ARM64EC build tools (Latest)
34-
- Windows 11 SDK (you might have to retarget the `DSInternals.Replication.Interop` projects to the version you have)
35-
- PowerShell Tools for Visual Studio (optional)
36-
- Git for Windows (optional)
37-
- GitHub Extension for Visual Studio (optional)
31+
| Component ID | Name |
32+
|----------------------------------------------------------|---------------------------------------------|
33+
| Microsoft.VisualStudio.Workload.ManagedDesktopBuildTools | .NET desktop build tools |
34+
| Microsoft.VisualStudio.Workload.VCTools | Desktop development with C++ |
35+
| Microsoft.VisualStudio.Component.VC.CLI.Support | C++/CLI support (Latest MSVC) |
36+
| Microsoft.VisualStudio.Component.VC.Tools.x86.x64 | MSVC Build Tools for x64/x86 (Latest) |
37+
| Microsoft.VisualStudio.Component.VC.Tools.ARM64 | MSVC Build Tools for ARM64/ARM64EC (Latest) |
38+
| Microsoft.VisualStudio.Component.Windows11SDK.26100 | Windows 11 SDK (10.0.26100.6901) |
39+
| Microsoft.Net.Component.4.8.1.SDK | .NET Framework 4.8.1 SDK |
40+
| Microsoft.Net.Component.4.8.TargetingPack | .NET Framework 4.8 targeting pack |
41+
| Microsoft.NetCore.Component.SDK | .NET SDK |
42+
| Microsoft.NetCore.Component.Runtime.10.0 | .NET 10.0 Runtime (Long Term Support) |
43+
| Microsoft.NetCore.Component.Runtime.9.0 | .NET 9.0 Runtime |
44+
| Microsoft.NetCore.Component.Runtime.8.0 | .NET 8.0 Runtime (Long Term Support) |
3845

39-
To make IntelliSense work with `*.ps1xml` files, the following code needs to be added to the `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Xml\Schemas\catalog.xml` file:
46+
[Git for Windows](https://git-scm.com/install/windows) is also required to clone the repository.
47+
48+
The following PowerShell script can be used to install the required components using [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):
49+
50+
```powershell
51+
# Install Visual Studio Build Tools with the required components
52+
[string] $components = @(
53+
'Microsoft.VisualStudio.Workload.ManagedDesktopBuildTools',
54+
'Microsoft.VisualStudio.Workload.VCTools',
55+
'Microsoft.VisualStudio.Component.VC.CLI.Support',
56+
'Microsoft.VisualStudio.Component.VC.Tools.x86.x64',
57+
'Microsoft.VisualStudio.Component.VC.Tools.ARM64',
58+
'Microsoft.VisualStudio.Component.Windows11SDK.26100',
59+
'Microsoft.Net.Component.4.8.1.SDK',
60+
'Microsoft.Net.Component.4.8.TargetingPack',
61+
'Microsoft.NetCore.Component.SDK',
62+
'Microsoft.NetCore.Component.Runtime.10.0',
63+
'Microsoft.NetCore.Component.Runtime.9.0',
64+
'Microsoft.NetCore.Component.Runtime.8.0'
65+
) -join ' --add '
66+
67+
winget install --id Microsoft.VisualStudio.BuildTools --exact --override "--wait --passive --productId Microsoft.VisualStudio.Product.BuildTools --channelId VisualStudio.18.Stable --addProductLang En-us --add $components"
68+
69+
# Install Git for Windows
70+
winget install --id Git.Git --exact
71+
```
72+
73+
### PowerShell XML Authoring Support
74+
75+
To make IntelliSense work with `*.ps1xml` files,
76+
the following code needs to be added to the `C:\Program Files\Microsoft Visual Studio\18\Community\Xml\Schemas\catalog.xml` file:
4077

4178
```xml
4279
<Association extension="ps1xml" schema="https://raw.githubusercontent.com/PowerShell/PowerShell/master/src/Schemas/Format.xsd" enableValidation="true"/>
@@ -45,16 +82,128 @@ To make IntelliSense work with `*.ps1xml` files, the following code needs to be
4582

4683
### Build and Debug Steps
4784

48-
1. Install the prerequisities.
49-
2. Checkout or download the source codes.
50-
3. Open the [Src\DSInternals.slnx](/Src/DSInternals.slnx) file in Visual Studio.
51-
2. Put any cmdlets you wish to debug into the [Src\DSInternals.PowerShell\Debug.ps1](/Src/DSInternals.PowerShell/Debug.ps1) script.
52-
3. Set the [DSInternals.PowerShell](/Src/DSInternals.PowerShell/DSInternals.PowerShell.csproj) project as StartUp Project.
53-
4. Switch to the _Debug_ configuration.
54-
5. Start debugging (F5).
85+
1. Install the [required software](#development-environment).
86+
2. Checkout or download the source code.
87+
3. Open the [Src/DSInternals.slnx](/Src/DSInternals.slnx) file in Visual Studio.
88+
4. Put any cmdlets you wish to debug into the [Src/DSInternals.PowerShell/Debug.ps1](/Src/DSInternals.PowerShell/Debug.ps1) script.
89+
5. Set the [DSInternals.PowerShell](/Src/DSInternals.PowerShell/DSInternals.PowerShell.csproj) project as StartUp Project.
90+
6. Switch to the _Debug_ configuration.
91+
7. Build the `DSInternals.Replication.Interop.*` projects for x86, x64, and ARM64 architectures.
92+
8. Start debugging the PowerShell module (F5).
93+
94+
Alternatively, you can use the following PowerShell script to clone, build, and load the module for debugging:
5595

56-
### Continuous Integration
96+
```powershell
97+
# Ensure that the NuGet.org package source is available
98+
dotnet nuget add source "https://api.nuget.org/v3/index.json" --name "nuget.org"
99+
100+
# Create a directory for the source code
101+
mkdir ~/source/repos
102+
cd ~/source/repos/
103+
104+
# Clone the repository
105+
git clone https://github.com/MichaelGrafnetter/DSInternals.git
106+
107+
# Build the solution
108+
cd ~/source/repos/DSInternals/Src
109+
$msbuild = "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\\MSBuild\Current\Bin\amd64\MSBuild.exe"
110+
$configuration = 'Debug'
111+
& $msbuild DSInternals.slnx /t:Restore /p:Configuration=$configuration /p:Platform=x64
112+
& $msbuild DSInternals.ArchitectureSpecific.slnf /t:Build /p:Configuration=$configuration /p:Platform=Win32
113+
& $msbuild DSInternals.ArchitectureSpecific.slnf /t:Build /p:Configuration=$configuration /p:Platform=ARM64
114+
& $msbuild DSInternals.slnx /t:Build /p:Configuration=$configuration /p:Platform=x64
115+
116+
# Load the PowerShell module
117+
~/source/repos/DSInternals/Src/DSInternals.PowerShell/Debug.ps1 -Configuration $configuration
118+
```
119+
120+
### Testing
57121

58122
[![CI Build](https://github.com/MichaelGrafnetter/DSInternals/actions/workflows/autobuild.yml/badge.svg)](https://github.com/MichaelGrafnetter/DSInternals/actions/workflows/autobuild.yml)
59123

60-
GitHub Actions are used for CI builds.
124+
To run the .NET unit tests, either use Visual Studio's Test Explorer
125+
or execute the following commands in a PowerShell terminal:
126+
127+
```powershell
128+
cd ~/source/repos/DSInternals/Src
129+
130+
# Run all unit tests
131+
dotnet test --solution DSInternals.TestsOnly.slnf --configuration Debug --no-build
132+
133+
# Run tests for a specific project
134+
dotnet test --project DSInternals.Common.Test --configuration Debug --no-build
135+
```
136+
137+
To run the PowerShell Pester integration / smoke tests, either use Visual Studio's Test Explorer
138+
or execute the following commands in a PowerShell terminal:
139+
140+
```powershell
141+
cd ~/source/repos/DSInternals/Scripts
142+
143+
# Windows PowerShell 5.1
144+
powershell -File ./Invoke-SmokeTests.ps1 -Configuration 'Debug'
145+
146+
# PowerShell Core 7+
147+
pwsh -File ./Invoke-SmokeTests.ps1 -Configuration 'Debug'
148+
```
149+
150+
GitHub Actions are used for Continuous Integration (CI) builds.
151+
152+
## Directory Structure
153+
154+
```plaintext
155+
Src/ # Source code
156+
├── DSInternals.Common/ # Shared utilities and cryptographic functions
157+
│ └── DSInternals.Common.csproj
158+
├── DSInternals.Common.Test/ # Unit tests for Common
159+
│ └── DSInternals.Common.Test.csproj
160+
├── DSInternals.DataStore/ # Offline ntds.dit database access (ESE/JET)
161+
│ └── DSInternals.DataStore.csproj
162+
├── DSInternals.DataStore.Test/ # Unit tests for DataStore
163+
│ └── DSInternals.DataStore.Test.csproj
164+
├── DSInternals.Replication/ # Replication (MS-DRSR) protocol implementation
165+
│ └── DSInternals.Replication.csproj
166+
├── DSInternals.Replication.Interop/ # Native C++/CLI interop for MS-DRSR RPC calls
167+
│ ├── Directory.Build.props # C++/CLI-specific MSBuild properties
168+
│ ├── DSInternals.Replication.Interop.Shared.vcxitems # C++/CLI items shared between .NET and .NET Framework projects
169+
│ ├── NetCore/
170+
│ │ └── DSInternals.Replication.Interop.NetCore.vcxproj
171+
│ └── NetFramework/
172+
│ └── DSInternals.Replication.Interop.NetFramework.vcxproj
173+
├── DSInternals.Replication.Model/ # Replication data model
174+
│ └── DSInternals.Replication.Model.csproj
175+
├── DSInternals.Replication.Model.Test/ # Unit tests for Replication Model
176+
│ └── DSInternals.Replication.Model.Test.csproj
177+
├── DSInternals.Replication.Test/ # Unit tests for Replication
178+
│ └── DSInternals.Replication.Test.csproj
179+
├── DSInternals.SAM/ # Security Accounts Manager (MS-SAMR) protocol implementation
180+
│ └── DSInternals.SAM.csproj
181+
├── DSInternals.SAM.Test/ # Unit tests for SAM
182+
│ └── DSInternals.SAM.Test.csproj
183+
├── DSInternals.ADSI/ # Active Directory Service Interfaces (ADSI) / LDAP client wrapper
184+
│ └── DSInternals.ADSI.csproj
185+
├── DSInternals.PowerShell/ # PowerShell cmdlet implementations
186+
│ ├── DSInternals.PowerShell.csproj
187+
│ └── DSInternals.psd1 # PowerShell module manifest
188+
├── Directory.Build.props # Common MSBuild properties
189+
├── Directory.Packages.props # Central Package Management
190+
├── global.json # .NET SDK configuration
191+
├── DSInternals.slnx # Full solution (requires Visual Studio for C++/CLI projects)
192+
├── DSInternals.DotNetSdk.slnf # C# projects only (works with dotnet CLI)
193+
├── DSInternals.TestsOnly.slnf # Test projects only
194+
└── DSInternals.SkipTests.slnf # Non-test projects only
195+
196+
Documentation/ # Project documentation
197+
├── CHANGELOG.md # Version history and release notes
198+
└── PowerShell/ # PowerShell module documentation
199+
200+
Keys/ # Strong name signing keys
201+
├── DSInternals.Public.snk # Public key for delay signing
202+
└── README.md # Instructions for key management
203+
204+
Scripts/ # Build and test automation scripts
205+
├── Get-TestData.ps1 # Downloads test data files
206+
├── Invoke-SmokeTests.ps1 # Runs PowerShell Pester smoke tests
207+
├── Update-Licenses.ps1 # Updates third-party license information
208+
└── Update-PSHelp.ps1 # Regenerates PowerShell MAML help files
209+
```

‎.github/README.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ This package is self-contained and it will also install all dependencies.
108108

109109
The DSInternals PowerShell module is part of FireEye's [Commando VM](https://github.com/fireeye/commando-vm), the Windows-based alternative to Kali Linux.
110110

111-
### NuGet Packages
111+
### NuGet Packages
112112

113113
The easiest way of integrating the DSInternals functionality into .NET applications is by using the [DSInternals Framework NuGet packages](https://www.nuget.org/profiles/DSInternals):
114114

@@ -119,10 +119,12 @@ The easiest way of integrating the DSInternals functionality into .NET applicati
119119

120120
### Building from Source Code
121121

122-
[![Visual Studio 2022](https://img.shields.io/badge/Visual%20Studio-2022-383278.svg)](CONTRIBUTING.md#building-from-source-code)
122+
[![Visual Studio 2026](https://img.shields.io/badge/Visual%20Studio-2026-383278.svg)](CONTRIBUTING.md#building-from-source-code)
123123
[![CI Build](https://github.com/MichaelGrafnetter/DSInternals/actions/workflows/autobuild.yml/badge.svg)](https://github.com/MichaelGrafnetter/DSInternals/actions/workflows/autobuild.yml)
124124

125-
You can of course download the [source code](https://github.com/MichaelGrafnetter/DSInternals/archive/master.zip), perform a review and compile the Module/Framework yourself. See the [CONTRIBUTING](CONTRIBUTING.md#building-from-source-code) guide for more info.
125+
You can of course download the [source code](https://github.com/MichaelGrafnetter/DSInternals/archive/master.zip),
126+
perform a review, and compile the Module/Framework yourself.
127+
See the [CONTRIBUTING](CONTRIBUTING.md#building-from-source-code) guide for more info.
126128

127129
## Documentation
128130

@@ -132,7 +134,8 @@ The online version of [PowerShell Get-Help documentation](../Documentation/Power
132134

133135
### Blog Posts
134136

135-
I have also published a series of articles about the DSInternals module on [my blog](https://www.dsinternals.com/en/). Here are a few of them:
137+
I have also published a series of articles about the DSInternals module on [my blog](https://www.dsinternals.com/en/).
138+
Here are a few of them:
136139

137140
- [Juicing ntds.dit Files to the Last Drop](https://specterops.io/blog/2025/08/14/juicing-ntds-dit-files-last-drop-dsinternals-powershell-active-directory-offline-attacks/)
138141
- [New Offline Capabilities in DSInternals 4.11](https://www.dsinternals.com/en/dsinternals-v4.11/)

‎.github/copilot-instructions.md‎

Lines changed: 4 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -8,71 +8,21 @@ DSInternals is a .NET-based project consisting of:
88

99
The project primarily focuses on Active Directory security auditing, offline database manipulation, and password management.
1010

11+
Read the [README.md](README.md), [CHANGELOG.md](../Documentation/CHANGELOG.md), and [CONTRIBUTING.md](CONTRIBUTING.md) files
12+
and the [PowerShell module documentation](../Documentation/PowerShell/Readme.md) for further context.
13+
1114
## Technology Stack
1215

1316
- **Languages**: C#, C++/CLI, PowerShell
1417
- **Frameworks**: .NET Framework 4.8, .NET 10.0 (Windows-only)
1518
- **Build System**: MSBuild with Central Package Management
1619
- **Testing**: MSTest with Microsoft.Testing.Platform runner
17-
- **IDE**: Visual Studio 2022+ with the `DSInternals.slnx` solution
18-
19-
## Project Structure
20-
21-
```
22-
Src/
23-
├── DSInternals.Common/ # Shared utilities and cryptographic functions
24-
│ └── DSInternals.Common.csproj
25-
├── DSInternals.Common.Test/ # Unit tests for Common
26-
│ └── DSInternals.Common.Test.csproj
27-
├── DSInternals.DataStore/ # Offline ntds.dit database access (ESE/JET)
28-
│ └── DSInternals.DataStore.csproj
29-
├── DSInternals.DataStore.Test/ # Unit tests for DataStore
30-
│ └── DSInternals.DataStore.Test.csproj
31-
├── DSInternals.Replication/ # Replication (MS-DRSR) protocol implementation
32-
│ └── DSInternals.Replication.csproj
33-
├── DSInternals.Replication.Interop/ # Native C++/CLI interop for MS-DRSR RPC calls
34-
│ ├── Directory.Build.props # C++/CLI-specific MSBuild properties
35-
│ ├── DSInternals.Replication.Interop.Shared.vcxitems # C++/CLI items shared between .NET and .NET Framework projects
36-
│ ├── NetCore/
37-
│ │ └── DSInternals.Replication.Interop.NetCore.vcxproj
38-
│ └── NetFramework/
39-
│ └── DSInternals.Replication.Interop.NetFramework.vcxproj
40-
├── DSInternals.Replication.Model/ # Replication data model
41-
│ └── DSInternals.Replication.Model.csproj
42-
├── DSInternals.Replication.Model.Test/ # Unit tests for Replication Model
43-
│ └── DSInternals.Replication.Model.Test.csproj
44-
├── DSInternals.Replication.Test/ # Unit tests for Replication
45-
│ └── DSInternals.Replication.Test.csproj
46-
├── DSInternals.SAM/ # Security Accounts Manager (MS-SAMR) protocol implementation
47-
│ └── DSInternals.SAM.csproj
48-
├── DSInternals.SAM.Test/ # Unit tests for SAM
49-
│ └── DSInternals.SAM.Test.csproj
50-
├── DSInternals.ADSI/ # Active Directory Service Interfaces (ADSI) / LDAP client wrapper
51-
│ └── DSInternals.ADSI.csproj
52-
├── DSInternals.PowerShell/ # PowerShell cmdlet implementations
53-
│ ├── DSInternals.PowerShell.csproj
54-
│ └── DSInternals.psd1 # PowerShell module manifest
55-
├── Directory.Build.props # Common MSBuild properties
56-
├── Directory.Packages.props # Central Package Management
57-
├── global.json # .NET SDK configuration
58-
├── DSInternals.slnx # Full solution (requires Visual Studio for C++/CLI projects)
59-
├── DSInternals.DotNetSdk.slnf # C# projects only (works with dotnet CLI)
60-
├── DSInternals.TestsOnly.slnf # Test projects only
61-
└── DSInternals.SkipTests.slnf # Non-test projects only
62-
```
20+
- **IDE**: Visual Studio 2026+ with the [DSInternals.slnx](../Src/DSInternals.slnx) solution
6321

6422
## Build Instructions
6523

6624
> **Important:** The `Src` directory must be the working directory for all build and test commands due to the `global.json` SDK configuration.
6725
68-
### Building the PowerShell Module (Full Build)
69-
70-
The PowerShell module depends on C++/CLI projects (`DSInternals.Replication.Interop`) which require Visual Studio to compile. Use the full solution for complete builds:
71-
72-
1. Open `Src/DSInternals.slnx` in Visual Studio 2022+
73-
2. Select the desired configuration (Debug/Release) and platform
74-
3. Build the solution (Ctrl+Shift+B)
75-
7626
### Building C# Projects Only
7727

7828
For C#-only development, you can use the `dotnet` CLI with the filtered solution:

0 commit comments

Comments
 (0)