Writing a Active Directory Audit Module - Creating the Project

I got in my head this week that I would like to write a Windows PowerShell module for getting information from Active Directory for the purpose of gathering information to aid in detecting miss configurations and also aid in incident response. My idea is to write the module and start publishing blog posts as I go through the process of writing the code and how I go about it. This will be my first experience with Pester also so I think it would be a fun adventure.

Requirements

I start by setting goals for the module, these are:

  • All output from each function will be objects.
  • I will assign each object a custom type so I can create custom views for the output.
  • The module must not depend on the ActiveDirectory module that ships with the different RSAT tools and use .NET and COM so as to leverage the use alternate credentials.
  • Module should be able to pull information as a base for Users, Groups, Computers, Sites, Domains, Forest, OUs and GPOs.
  • Module will be PSv3 or above so as to use new improvements int he latest versions of Windows PowerShell.

Creating the Git Project

One of the first tasks I do depending on the purpose of the project is either create a project on a local GitLab server or create it in GitHub is the project will be public. Since this project will be public I start by creating the project in GitHub and set:

  • Project name
  • Project description
  • License
  • Status to Public

Once the project is created I create a "dev" branch so as to keep master as the stable branch and use the dev branch and the one to take pull requests in to.

I now clone the master branch of the project in to my Documents folder. My personal preference is that modules I'm developing I generally do not put them in my Windows PowerShell module and prefer to load them manually as I work in them since I may create parallel copies of it sometimes for testing and debugging.

I navigate in to the cloned project and create a local tracking branch for the dev branch.

One of the things I learned from my good friend Matt Graeber and working in the Metasploit project is to have a clear set of guidelines in the README.md file of a project to make it easier for people that want to contribute know what would be the criteria for accepting pull requests (So I borrowed most of Matt Readme).

We create the README.md file and we modify it to put our rules and general guidelines.

After creating the file I add and commit the file in to the dev branch and then merge it in to the master branch.

Now my git project is all set.

Creating a Module Manifest

Since this will be a module one of the first thing I like to do is to create a module manifest and empty master module file that will be used to load all other module files.I first make sure I'm in the dev branch so as to get in to the habit of working in it and then merging in to master. After changing branches I create an empty psm1 file with the same name as the module using New-Item cmdlet

Now I can create a manifest that describes the module and sets parameters for its execution using the New-ModuleManifest cmdlet. The parameter I will set are:

  • Manifest name, this is the same as the folder and main module file.
  • Description of the module.
  • Author of the module
  • The lowest version of PowerShell supported by the module. 

We can test the manifest by importing the empty module with Import-Module cmdlet and then using Get-Module to look at its information. 

The rest of the parameters we will modify as we progress in later blog posts. Now that we have the manifest we can commit, merge and push like we did for the readme file. 

This is only the beginning of the series and I hope as always that you have found the information useful.