Microsoft Azure NSG

Overview

This integration allows for IP addresses to be dynamically managed within Azure Network Security Groups (NSGs), which are used by default as the inner firewalls protecting virtual machines. Other Azure assets (PaaS etc) are managed using separate Knocs.

Prerequisites

Nothing to install on the agent. The agent talks to Azure Resource Manager directly. The agent host needs outbound HTTPS to:

• login.microsoftonline.com (token endpoint)
• management.azure.com (Resource Manager API)

Permissions in Azure

To interact with the Azure NSG - via the API - you need to first create a service principal and assign the limited permissions, as shown below:

Create a custom role (for limited NSG edit access)

1. Go to Azure Portal: https://portal.azure.com

2. Search for “Subscriptions” and select your subscription.

3. In the left menu, click “Access control (IAM)”.

4. Go to the “Roles” tab and click + Add > Add custom role.

5. Basics tab:

   • Name: Knocknoc NSG Edit

   • Description: Can read and edit rules in a Network Security Group.

6. Permissions tab:

   • Click + Add permissions

   • In the search box, type: networkSecurityGroups

   • Click on the "Microsoft Network" card

     

   • Add these permissions:

     • Microsoft.Network/networkSecurityGroups/read

     • Microsoft.Network/networkSecurityGroups/securityRules/read

     • Microsoft.Network/networkSecurityGroups/securityRules/write

     • Microsoft.Network/networkSecurityGroups/securityRules/delete

   • Click Add

7. Assignable scopes tab:

   • Click + Add assignable scope

   • Select your resource group, or subscription if broader access is fine.

8. Review + create the custom role.

  

Create a Service Principal in Azure Portal

1. Go to the Azure Portal

• Visit: https://portal.azure.com

2. Search for “App registrations”

• In the top search bar, type App registrations and select it.

3. Click “+ New registration”

• Name: Knocknoc-NSG-Editor (or anything you prefer)
• Supported account types: Leave as "Single tenant" (default)
• Redirect URI: Leave blank (not needed for non-interactive apps)

Click Register

  4. Go to “Certificates & secrets”

• Click + New client secret
• Give it a name like NSG-Edit-Automation
• Set expiration (e.g., 24  months)
• Click Add

Copy the generated secret value immediately. You won’t be able to retrieve it later.

5. Find Application (client) ID

• In the Overview tab of your app registration:

  • Copy the Application (client) ID

  • Also copy the Directory (tenant) ID

 

6. Assign the Custom Role (Knocknoc NSG Edit)

1. Go to your Resource Group (or subscription) where the NSG lives.

2. Click Access control (IAM).

3. Click + Add > Add role assignment

4. Choose:

   • Role: Knocknoc NSG Edit (or your custom role name)

   • Assign access to: User, group, or service principal

   • Select: Find and select your registered app (Knocknoc-NSG-Editor)

Click Save

Configuring the Knoc

In the Knocknoc admin portal, go to Knocs, choose Create new knoc, then Microsoft and Azure NSG.

The integration holds the credentials and can be reused by other Azure NSG knocs. You need these values:

• Client-ID (Username/service principal account, which we configured earlier)
• Client Secret (Password for the service principal above)
• Tenant ID (copied from the App Registration "Directory (tenant) ID", also found as the "Parent management group" on the Subscription page)

The knoc holds what gets written. For the relevant NSG, you need these values:

• Resource group and existing NSG name
• Port. The rule is always TCP.
• Direction (Inbound or Outbound)
• Subscription ID, which is optional when the credentials can see only one subscription

First, the integration. Pick the agent that talks to Azure, then enter the credentials:

Then the knoc itself, naming the NSG this knoc writes to:

No cache stops the agent reusing what it has worked out for these credentials: the API client it built and, where you left Subscription ID blank, the subscription it discovered. Each grant and revoke then gets its own token and looks the subscription up again, which is slower. Nothing is written to the agent's disk either way.

Viewing the results

Log in to the Azure Portal and visit the related NSG. 

Rules will be created starting with priority 500, up to the built-in maximum of 4096. If you have rules >=500 it will automatically work around these, however your effective usable space for rules will naturally be reduced.

An example of the captured data is shown below. This includes adding the user to the rule-name along with the port ("demo" and "p22"). 

Deduplication 

For this integration, de-duplication is disabled - meaning any additional/subsequent users logging in from the same source IP address will also be added and gracefully removed from the NSG, allowing for username-level attribution.

JSON if you prefer

{
    "properties": {
        "roleName": "Knocknoc NSG edit",
        "description": "",
        "permissions": [
            {
                "actions": [
                    "Microsoft.Network/networkSecurityGroups/read",
                    "Microsoft.Network/networkSecurityGroups/securityRules/read",
                    "Microsoft.Network/networkSecurityGroups/securityRules/write",
                    "Microsoft.Network/networkSecurityGroups/securityRules/delete"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}