Perch is an event log tracker that can catch a lot of useful information. I like perch because it captures failed login information. It’s easy to sort and exportable. This is why many companies use the software. There are some gatchya’s with perch installs though. If you are installing it on a server, some services don’t auto start. Installing it from PowerShell also has a gatchya. This post is about how to install perch via PowerShell scripts. This method uses your token for the client’s site. Let’s Install Perch with PowerShell.
Let’s break down the script. The first thing we do is create the download repo. I personally like to use the C:\Temp. Not all machines have a c:\. This is why I use the variable $Env:SystemDrive. If the OS drive is d, the code will add a D:\Temp. and so on and so forth.
The next line is the URL for the latest and greatest Perch installer. This keeps your download up to date. With that stated, this also means if they change something you will need to be able to catch that change. So you will need to stay up to date with their deployment. A good way to do that is by registering with their updates emails. I like to have a ticket every 3 to 6 months, randomly placed, to review deployments like this one. This is just a good habit.
Now we have the url, we want to create a path. Using the Env:SystemDrive we place the perch-log-shipper-latest.exe into the temp folder, our local repo. This will make the next command easier.
Now we invoke-webrequest this bad boy. Just like curl and wget, we are able to download the file. Using the PerchURL in the URI position and then the outfile will be the perchfullfilename. Of course, we use the basic parsing just in case it’s an older version of PowerShell. At the time of this writing, the default PowerShell is 5.1 on windows 10.
Now we start the installation. We start-process. Using the PerchFullFileName as the target. See, using parameters helps. Our argument list is /qn for quiet. The output is going to be the token. Finally our token value, value is our token from perch’s site.
Getting the token
To get the token, you will need to log into your perch system. At the top, select the company you wish to get the token from.
Next, you will need to click on the settings icon on the bottom left-hand corner. Then click the Network icon.
Normally we want to add a -wait flag to the end of the installer. Things like google chrome do great with the -wait flag. However, in this case, we don’t want to do that. The reason we create advanced checks is due to the multiple sub-processes inside of the perch install process. The wait flag only captures the first process.
Confirming Install Perch with Powershell
With all that, it’s time to confirm the installation. The most simple way to do this is by watching the services. Perch installs 2 services. It installs perch-auditbeat and perch-winlogbeat. During the confirmation process, we wait. If a timeout occurs, we get the error. If the application installs, we get the results. At this point, we want to start our time-out timer. That’s why we have a $timeout = 0. We then start a do until. Each time the system loops, we wait for 5 seconds. Then we add 5 to the timer. This effectively creates a timer for us. This process is repeated until the conditions are met. The services with the name perch* are greater than or equal to 2, or the time-out reaches 500.
If the services are installed or if the timeout is reached, we moved to the next step. By default, the auditbeat is set to manual. So we check to see if we have the two services. If we do, we then set the perch-auditbeat to automatic and start the service. If not, we throw an error saying the services did not install. This will alert the deployment engineer to dig deeper into this machine. From my experience, it’s because another application is installed.
This past week I had to install a piece of software that took 30 minutes to install. The software had multiple levels of processes that made the -wait feature completely useless. The best way to know the software was installed is to detect the service names. Thus you have to wait for service to appear. The fun part is depending on the windows 10 version, it would install upwards of 11 services.
Thankfully it followed a set pattern and the first 7 services were the only ones that we needed to watch for. Another wrinkle in this installer’s process is the computer couldn’t go to sleep or the screen couldn’t lock. This wrinkle had me think outside of the box a bit. I came up with two ideas. The first idea was to set the power configuration was set to never sleep and the screen not to lock. This would require exporting the config and importing. This was a lot of code, but doable. The second idea would tell the computer to click the scroll lock button over and over again. Guess which one I took? Yep, the scroll lock. Parsing random strings is fun and all, but can be accident-prone. Just to be fun about it, I decided to make things a little random with get-random. This way the system wouldn’t flag it as a virus.
The Script – Wait for service to appear
$WShell = New-Object -Com "Wscript.Shell"
$A = 0
Do {
$RandomNumber1 = Get-Random -Minimum 1 -Maximum 20
$RandomNumber2 = Get-Random -Minimum $RandomNumber1 -Maximum ($RandomNumber1 + 25)
$WShell.SendKeys("{SCROLLLOCK}")
Start-Sleep -Seconds $RandomNumber2
$A = $A + $RandomNumber2
} until ((Get-Service -Name "frog*").count -ge 7)
write-host "The system took around $A seconds to complete"
The Breakdown
The core of this code is a simple Do Until loop. The loop executes at least one time. Then it evaluates to see if it needs to execute again. We have a while and Until. While basically means while this is happening do this. The until says, keep doing it man until this is met. Here we are using a Do Until. The first step is to create the windows script shell. AKA wscript.shell. This allows us to send key commands and such. Next, we create a 0 variable to keep up with the time. Because I like seeing the time.
We enter the do loop… Dum Dum Do? We start off by making a random number between 1 and 20. We place that into a variable. Then we start another random number. The minimum is the last random number and the maximum is the last random number plus 25. Thus the maximum time is 45 seconds.
Next, we send the scroll lock key. using the Wscript.shell sendkeys. Then we sleep for a random time. We add that information into the variable. Then we come to the Until. We ask to see if the service is there with Get-service. Our services all start with frog. Thus we use the -name “frog*”. We get the count will be greater than 7. If it is greater than 7, then we exit the loop and tell the user how long it took to complete.
The fun part about this is you can set the service to something that will never exist and the unit will keep running until you stop it. This will keep your computer from locking. If your company doesn’t have good monitoring software, like most small businesses, then it will go unnoticed.
Conclusion
And that’s how you Wait for service to appear. It’s not glamorous, but PowerShell does help the process get along. This code’s main goal is to keep the computer awake for at least 30 minutes. Always remember, that great code comes with great ability.
In my previous post, we went over how to Grab user information from a client. Today we will be going over how to Download User Images with Graph API. This piece is very straightforward until you get to the graph link. There is a unique limitation to PowerShell quotes that I found a good workaround.
Ok, we start off with the loop like before. We are using the /Users API. Since this is a user-level item, you have a top loop through each user with the User Principal Name. This means your string will be inside double quotes “” instead of single quotes because you want PowerShell to read the value of the $($UPN). so far simple. The next part is the word photo. Once again, simple. Then the impact. the word $value has to be at the end. This means it’s going to drop whatever is instead value into the string. There are a few ways around this.
Option 1
Declare the variable beforehand. Simple and easy way to fix this problem.
Now we have the link we need to download the image. Once again we are going to use the invoke-restmethod with our custom header like before. This time we are going to give the -outfile. Since not everyone has an image, I am also going to set the error action to silently continue.
In the last blog, We talked about how to create a registered app with Graph API permissions. This app’s main purpose is to become the base for an employee directory through Powershell. If you haven’t read it yet, you can here. Today’s blog is about how to interact with the app with PowerShell. Here are the pieces of information you will need from the Application.
The Tenant’s ID
The Application ID
The Secret Key
If you have those three pieces of information, we can build a script to grab all the users. The app has “User.Read.All” permissions. What this means is that the app can pull all the information inside the azure ad that is directly linked to the user’s Azure AD account. This does not include things like SharePoint, mail, etc, directory, teams, etc. You have to grant permission for those items. But items like name, usernames, images, and much more is accessible as read-only.
The first thing we want to do is put the required information into variables to be used over again and again.
Next, we want to make a variable that will host the clientID inside the Oauth URL string. We use this string to authenticate later we want to grab the access token.
The body of the access token requires a redirect url. You can set this as “http://localhost” if you want. We really don’t care unless the app has a redirected URL assigned to it. That’s for another day. So, the next step is to build the body. We do this with a basic hash table. Inside this table, we need client_id, client_secret, redirect_url, grant_type, and the scope.
Now we have the Token URL, and the body. We need to get the access token. We do this with a post method to the Token URL using the body information. Then we place that token in its own variable to be used in the header.
Up to this point, we have been building the header for the next command. Now we need to switch gears and create the query URL for the graph. You can build out the string inside the graph explorer (Link) and read up on the documentation. The permissions give us access to the users’ information. You can read up on the query statement at this link.
In our example, we want to get a list of all users and these values.
We are using the /users api to gather this information. Hint to the User.Read.All permissions we gave in the last blog post. Now, we grab the first piece of information using Invoke-RestMethod.
BAM! we have information. $PageInfo.Value will give you the first hundred records. Wait, only the first 100? Yep, Graph only presents the first 100 items. So, how do you handle that? You create a loop. how do we determine if we need a loop, we look to see if the value ‘@odata.nextlink’ exists. We do this with a Do While loop and the ‘@odata.nextlink’ information. The ‘@odata.nextlink’ is the next link request that will need to be executed. AKA the next page of the outcome. So each time the loop has a ‘@odata.nextlink’ the final loop will stop because it doesn’t have the link.
Do {
$PageInfo = Invoke-RestMethod -Headers $Header -Uri $PageInfo.'@odata.nextlink' -Method Get
$Userinfo += $PageInfo.Value
} while (($PageInfo | Get-Member).name -contains '@odata.nextlink')
Notice we keep adding $PageInfo.Value to userinfo. This is building the userinfo array. This way we have the data we need. One of the requirements for this script is to have the Assigned user Information. So we need to add the sku part number of each license to the user. The problem is the assigned licenses gives back only the skuID. So what we can do is loop through the $UserInfo and add them accordingly. So we do this by starting a For Loop. Why a for loop? Because we will be adding a member property of the sku part numbers.
for ($I = 0; $I -lt $Userinfo.count; $I++) {
}
Inside this loop, we need to get the users’ licenses. We can do that with graphs as well. It’s still part of the user.read.all permissions as it still uses the /users api. We select the user by giving the UPN name. Then we ask for the license details with a /licenseDetails. I know super complex. Here is what the link will look like
Next we invoke the rest method again and using the link we generated pull in the information. I have never seen a user have more than 20 licenses. So, no need for a loop here.
Each time the loop runs, it pulls that User’s UPN from the UserInfo array. Grabs the details of the license from graph and pulls only the sku part number. Then adds that part number to the license info inside the UserInfo array at that location. Let’s put it all together now.
That’s all it takes to get the information from the azure ad. You can export this data into an XML or JSON and integrate it with any other system that you like. This does work with Powershell universal as well. You can create a table that has the next button or just gather all the information at once and present it. The more times it looks the longer the information will take to populate. Using the User.Read.All, you are also able to pull photos with graph API.
Back in November Microsoft released v1.0 of graph API. Along with it is a large library of documentation. I have been hesitant about making a blog post about Graph for a while because the community seemed to be split on how PowerShell should interact with it. Now the dust is settling, I want to show you how I have worked with Graph API. This method allows for use without any modules. This means it translates to other apps as power automate. My approach is designed for security and separation of duty. However, it’s a long-winded process. In the next few blog posts, I will go over the Employee Directory Graph API I created for another company. The first step is to create a registered app. This post will go through the process of creating the App both manually and PowerShell.
Create an Azure App – Manual
The first step is to log into your Azure tenant. Then click on the Azure Active Directory on the left-hand side.
Then on the left-hand side, Click the App Registrations. You will be greeted by the owned applications. All manually added. If you add an app via PowerShell it will show up under all applications. Now click the New registration button.
Inside the Register An Application window, we will fill in the Name of the application. This is where you will select the supported account type. The way I do it is client by client. This the client owns the application. I don’t want the application to pull data from a different client. So, I radio check the “Account in this organizational directory only **** – single tenant. Then I click register.
After you click register, you will be brought to the application page. Here you want to gather some pieces of information and document them. You will want the Application ID and the Directory ID. Next, we will click the Certificate and Secrets on the left-hand side.
In the certificates and secrets screen, we want to click the New Client Secret. The reason we are doing this is that we want security. This will create that security. Without the key this generates others will not be able to access this application remotely.
What I like to do at this point is create the key with the Application name and the word Key. In this example, we are using Employee Directory Key. The maximum time span you can select is 24 months, aka 2 years. This means in 2 years, you will have to regenerate a key and update your applications accordingly. Once you select the time span you want this key to live, click add.
Now you have the Key created, this is the ONE AND ONLY CHANCE to grab the key value. After this there is no way that I am aware of that you can grab that key. So make sure you click the copy to clipboard button and store it somewhere safe. Best to be in the same location as the application ID and the Tenant ID.
Now you have created an Azure Registered Application manually, let us look at how to do it with PowerShell.
Create an Azure App – PowerShell
The Powershell process for this is much faster and less prone to human errors.
First we connect to Azure AD using the Connect-AzureAD commandlet. Then we grab the name of the application from the user with the read-host commandlet. Then we create the application using the New-azureadapplication command. We give it the name of the application we want. And we say it’s not available to other tenants. Make sure you place the return info into a variable to be used later. This will produce your app ID and object ID.
Next we setup the date and times for a year by creating a start and end time with get-date commands. We will use those two dates to create the secret key. The commandlet is new-azureadapplicationpasswordcredential. The Custom Key Identifier will be the application name plus the word key. We reference the Object ID from the previous azure command for the object ID. We tell it the end date and the start dates. This will produce the secret key. So make sure once again to put that invariable.
Next, we create a custom ps object to display our information. For the App name its the app name. For the AppID we want the first commands appid. For the key name, we use the app name and the word key. Finally, for the key-value, we use the second azure command value output.
Finally, we disconnect from azure AD with the command Disconnect-AzureAd.
Assign Graph API Permissions
Sadly, I have not found a PowerShell method to add graph API permissions. The reason I believe this is the case is because of the nature of these permissions. They must have consent. Basically, you have to click the button manually. So let us add the user.read.all permissions to our employee directory application. Go to the application in your tenant. On the left-hand side, click the API permissions button. Then click Add Permissions
The type of application permissions will appear. You will want to search out Graph API and click on it. Luckily it’s the first item on the list.
Once you click the Microsoft Graph permissions button. You will be greeted with a choice of Delegated Permissions or Application Permissions. Delegated permissions require a user to sign in to the account for the application to run. The Application permissions do not. If you want this to be an automated process, select application. Under select permissions search out the User.Read.All. This will allow the application to read user information like phone numbers, addresses, usernames, etc. It doesn’t give permissions to read emails or anything else like that. Check the box for the permissions you want and click Add permissions.
Once you add the permissions you will notice under the status, “Not Granted for”. This means the application can’t use those permissions yet. You will need to click Grant admin consent for… to add the permissions. Once you click that button, you will be prompted with a confirm, just click the confirm to allow access. Once you allow access, the status will turn green and you will be ready to go.
Now we have granted access, we are free to create with the application. Stay tuned for next week.
