Using Amazon SNS with PowerShell

• Author
• Recent Posts

Josh Rickard

Josh's primary focus is in Windows security and PowerShell automation. He is a GIAC Certified Windows Security Administrator (GCWN) and GIAC Certified Forensic Analyst (GCFA). You can reach Josh at MSAdministrator.com or on Twitter at @MS_dministrator.

Latest posts by Josh Rickard (see all)

• Search Event Logs and error codes with Netikus.net System32 - Thu, Jan 10 2019
• Netikus.net IPMon+ – GUI for ipmon.exe - Tue, Nov 20 2018
• Understanding PowerShell Begin, Process, and End blocks - Mon, Oct 15 2018

Amazon SNS lets your application deliver notifications to additional services or applications, depending on your use case. SNS is becoming more and more common in microservice architecture designs around the globe. If your application needs to communicate with multiple endpoints or you need multiple applications to communicate to a central service, you should consider AWS SNS.

Whether you are using PowerShell on Windows or PowerShell Core, you can use Amazon SNS within your application service. Hypothetically, if you want  notifications when users start their computers (workstations or servers) or when certain Windows Events happens, you could create a powerful alert system for your organization. With this example, a notification service like AWS SNS is a perfect use case. Let's break this down further:

1. An IT professional creates a new SNS topic.
2. The machine starts and notifies the SNS endpoint.
3. The IT professional receives a notification when a system starts up.

Client machines publishing notifications to an SNS topic

Amazon SNS can notify you immediately or act upon a notification you receive from a system. By using SNS, we can receive messages through the following methods (via Connect-SNSNotification):

• http: delivery of a JSON-encoded message via HTTP POST
• https: delivery of a JSON-encoded message via HTTPS POST
• email: delivery of a message via SMTP
• email-json: delivery of a JSON-encoded message via SMTP
• sms: delivery of a message via SMS
• sqs: delivery of a JSON-encoded message to an Amazon SQS queue
• application: delivery of a JSON-encoded message to an EndpointArn for a mobile app and device
• lambda: delivery of a JSON-encoded message to an AWS Lambda function

With PowerShell, you are able to create, subscribe, and publish notifications using the AWS Tools for PowerShell or PowerShell Core:

1. PowerShell on Windows:

   Install-Package -Name AWSPowerShell

2. PowerShell Core:

   Install-Module -Name AWSPowerShell.NetCore

After you have install AWSPowerShell, you will have access to all the available AWS functions, including the following list of SNS functions:

Get-Help *SNS | select -Property Name

AWS SNS functions

Before continuing, you will need to know a few concepts before working with AWS SNS. The first is that SNS uses the concept of topics. Topics are categories or segmented endpoints subscribers can "subscribe" to.

Another way to think of it is that topics are like 4sysops.com. 4sysops creates content, and a visitor can subscribe to or follow certain authors or content types. Additionally, bloggers can post or publish topics to 4sysops, which then the subscribers will receive notifications about.

To continue, you will need all the necessary tokens from your AWS account. Accessing and creating these tokens and keys is out of the scope of this post.

Let's first create a new SNS topic. As you might guess, we will be using the New-SNSTopic cmdlet to create our new topic. This is how you create a new topic using PowerShell:

New-SNSTopic -Name 'my-new-powershell-topic' -AccessKey $AccessKey -SecretKey $SecretKey -Region 'us-east-1'

Now that we've created our new SNS topic, we should receive our topic ARN (Amazon Resource Name). This value serves to create a subscriber to notifications as well as allow our workstations to publish notifications to our SNS topic.

You can set up multiple ways to subscribe to an SNS topic (as mentioned above), but for our example, we will be receiving notifications via email. If you wanted to, you could connect this to an SQS queue, a Lambda function, an API on your website, or an SMS text message. Additionally, you can have multiple subscribers subscribed to an SNS topic, and they each can have a different method of receiving notifications. Whichever you choose, you will need to define how your specific subscriber receives notifications.

To subscribe to an SNS topic, we will need to use Connect-SNSNotification and specify a few attributes:

Connect-SNSNotification -TopicArn $TopicARN -Protocol email -Endpoint 'first.last@company.com' -AccessKey $AccessKey -SecretKey $SecretKey -Region 'us-east-1'

Here we are specifying the TopicArn we received when creating our new SNS topic. Additionally, we are specifying we want to use the email protocol, and our endpoint (location to receive the email) is our email address. Additionally, we will supply our credentials as needed.

After subscribing to our SNS topic, we should receive a short-lived authorization token. This token lasts three days, and you must use it before then, or you will start all over. To confirm our application wants to subscribe to this topic, we will call the following:

Confirm-SNSSubscription-TopicArn $TopicArn -Token 'short-lived-token' ‑AccessKey $AccessKey -SecretKey $SecretKey -Region 'us-east-1'

Now that we have confirmed our SNS subscriber (our email address for this example), we can now write a PowerShell startup script to publish an SNS message to our topic.

To do this, we need to make sure your machine has the AWS PowerShell Tools installed:

If (-not(Get-Module -Name AWSPowerShell)){
		Install-Module -Name AWSPowerShell
		Import-Module -Name AWSPowerShell -Force
	}
	Else {
		Import-Module -Name AWSPowerShell -Force
	}

Now we will need to set our AWS credentials so we do not have to reference them every time we want to call this startup script:

Set-AWSCredentials -StoreAs default -AccessKey $AccessKey -SecretKey $SecretKey

We now just need to call the Publish-SNSMessage cmdlet and provide some details based on what we want to notify our subscriber of. In our case, we will keep it simple and just send a subject and some base information.

$Subject = "$($env:COMPUTERNAME) Started"      $Message = "$($env:COMPUTERNAME) Started at $(Get-Date)"Publish-SNSMessage -TopicArn $TopicArn -Subject $Subject -Message $Message ‑Region us-east-1

That's it! If you place the entire script on your workstations (a Group Policy Startup script, run folder, scheduled task, etc.), you should start receiving email notifications when your workstations are online.

Again, this is just one simple example, but you could expand this approach and raise alerts when certain Windows Events happen or when certain applications run or when a user opens an unpermitted URL. Whatever your need is, combining Amazon SNS and PowerShell is powerful for IT professionals.

Here is the entire script:

If (-not(Get-Module -Name AWSPowerShell)){
		Install-Module -Name AWSPowerShell
		Import-Module -Name AWSPowerShell -Force
	}
	Else {
		Import-Module -Name AWSPowerShell -Force
	}

	If (-not(Get-AWSCredentials -ProfileName default)){
		Set-AWSCredentials -StoreAs default -AccessKey $AccessKey -SecretKey $SecretKey
	}
	$Subject = "$($env:COMPUTERNAME) Started"
	$Message = "$($env:COMPUTERNAME) Started at $(Get-Date)"
Publish-SNSMessage -TopicArn $TopicArn -Subject $Subject -Message $Message  Region us-east-1