Table of Contents

• Getting Started
  • Helpful Background Information
  • Prerequisites
  • External Dependencies
  • Adapters
  • How to Install
  • Testing
• Using this Example Project
  • AWS Blocked Traffic - Kentik - Example
  • AWS Blocked Traffic - Reset - Kentik - Example
  • Device Onboarding - Kentik - Example
  • Device Onboarding - Reset - Kentik - Example
• Additional Information
  • Support

Getting Started

This section is helpful for deployments as it provides you with pertinent information on prerequisites and properties.

Helpful Background Information

Workflows and processes often include logic that varies from business to business. Our Example Projects are more complex processes that include several of our modular components to build a more complete process.

While these can be utilized, you may find more value in using them as a starting point to build around.

Prerequisites

Itential Example Projects are built and tested on particular versions of IAP. In addition, Example Projects are often dependent on external systems and as such, these Example Projects will have dependencies on these other systems. This version of Kentik - REST - Example has been tested with:

• IAP 2023.1

External Dependencies

Adapters

How to Install

To install the Example Project:

• Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Supported IAP Versions section in order to install the Example Project.
• Import the Example Project in Admin Essentials.

Testing

Cypress is generally used to test all Itential Example Projects. While Cypress is an opensource tool, at Itential we have internal libraries that have been built around Cypress to allow us to test with a deployed IAP.

When certifying our Example Projects for a release of IAP we run these tests against the particular version of IAP and create a release branch in GitLab. If you do not see the Example Project available in your version of IAP please contact Itential.

While Itential tests this Example Project and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this Example Project into a development/testing environment in which you can test the Example Project.

Using this Example Project

Example Projects contain 1 or more workflows. Each of these workflows have different inputs and outputs.

AWS Blocked Traffic - Kentik - Example

This is an end-to-end automation example where an alert is triggered within a Kentik policy due to a threshold being exceeded. In this example Kentik uses an integration to call IAP's northbound API trigger. Once the trigger is executed it invokes an automation that then validates the traffic can be accepted and interacts with change management (ServiceNow), AWS EC2, and a notification platform (MS Teams).

This automation example can be installed and reviewed for ideas on how to incorporate Kentik into a closed loop alert remediation scenario with IAP.

Capabilities include:

• Checks if source IP is in allowed IP list
• Sends MS Teams message indicating alarm triggered
• Adds source IP to AWS security group if source IP is in allowed IP list
• Sends MS Teams notification if unable to add source IP to AWS security group
• Creates ServiceNow Change Request if alarm triggered

Configuring Dependencies

AWS

A Security Group in AWS grants access of a hosted server to given source IP. This automation is able to update a given Security Group to have source IP after alert is sent by Kentik to IAP in the Kentik AWS Dimension field kt_aws_dst_sg.

Microsoft Teams

This IAP automation sends formatted messages over Microsoft Teams with links to the IAP job run, a ServiceNow Change Request created for an alarm event, and the Kentik flow data. Three channels are used in this automation that each require creating an Incoming Webhook and are used for the following events:

1. Policy All Events: receives messages any time an alert is sent from Kentik to IAP and starts a job in IAP.
2. Policy Automated Authorizations: receives messages when a source IP detected by Kentik sending web traffic to a given server is added to Security Group in AWS to grant access to that server since the source IP is found in a white-list.
3. Policy Automated Failures: received messages when a source IP fails to be added to Security Group in AWS. This can occur if a failure happens when performing that operation or the source IP is already found in the Security Group.

Follow the Microsoft Teams documentation linked for creating Incoming Webhooks for each of the three channels described above.

Kentik

The AWS Blocked Traffic Event automation is started by Kentik sending a request to IAP upon a critical threshold met in traffic to a web server observed by Kentik. In order to use this automation a Notification Channel of type Custom Webhook must be set up in Kentik. The IAP URL and API endpoint for the AWS Blocked Traffic Event automation is provided in the configuration of the Custom Webhook in Kentik. A Go template as seen below is used to map the data sent from Kentik to a format the IAP automation can parse to perform a closed loop remediation of either enabling access to client sending traffic to web server observed by Kentik or continuing to block access if the IP is not white-listed.

{
  {{- . | toJSON | explodeJSONKeys -}},
  {{- if .IsSingleEvent  -}}
    {{- with .Event -}}
      {{- . | toJSON | explodeJSONKeys -}},
      {{- .Details.General.ToMap | toJSON | explodeJSONKeys -}},
      "iapUrl": "<iap_url>",
      "serviceNowUrl": "<service_now_url>",
      "allPolicyEventsWebhookUrl": "<webhook_url_1>",
      "policyAutomatedFailureWebhookUrl": "<webhook_url_2>",
      "policyAutomatedAuthorizationWebhookUrl": "<webhook_url_3>",
      "serviceNowAdapter": "<service_now_adapter>",
      "awsEC2Adapter": "<aws_ec2_adapter>",
      "msTeamsAdapter": "<ms_teams_adapter>",
      "Dimensions": {{- (.Details.WithTag "dimension").ToMap | toJSON -}},
      "Links": {{- (.Details.WithTag "url") | toJSON -}}
    {{- end -}}
  {{- else -}}
    {{- with index .Events 0 -}}
      {{- . | toJSON | explodeJSONKeys -}},
      {{- .Details.General.ToMap | toJSON | explodeJSONKeys -}},
      "iapUrl": "<iap_url>",
      "serviceNowUrl": "<service_now_url>",
      "allPolicyEventsWebhookUrl": "<webhook_url_1>",
      "policyAutomatedFailureWebhookUrl": "<webhook_url_2>",
      "policyAutomatedAuthorizationWebhookUrl": "<webhook_url_3>",
      "serviceNowAdapter": "<service_now_adapter>",
      "awsEC2Adapter": "<aws_ec2_adapter>",
      "msTeamsAdapter": "<ms_teams_adapter>",
      "Dimensions": {{- (.Details.WithTag "dimension").ToMap | toJSON -}},
      "Links": {{- (.Details.WithTag "url") | toJSON -}}
    {{- end -}}
  {{- end -}}
}

Once the Custom Webhook is created with the above Go template as well as URL of the IAP API endpoint, a Kentik Alert Policy must be configured to send a request to IAP upon a threshold being reached using Custom Webhook created above. This automation was tested using a Critical threshold in the Alert Policy, but other threshold levels could be used.

IP Whitelist

A newVariable task at the start of the workflow AWS Blocked Traffic Event - Kentik - Example is used to create an IP whitelist for allowed source IPs to reach the server in AWS that Kentik is observing.

Running Automation and Resetting State

In order for Kentik to send a request to IAP the client source IP must not exist in the corresponding security group for the server in AWS. The AWS Blocked Traffic - Reset - Kentik - Example Operations Manager automation can delete a given source IP from a given security group.

There is a delay between when a source IP not in the AWS security group attempts to reach the server on AWS and when the Kentik request due to alarm threshold met is sent to IAP. Look for messages in Microsoft Teams when the request is sent to IAP from Kentik.

Entry Point IAP Component

The primary IAP component to run AWS Blocked Traffic - Kentik - Example is listed below:

Inputs

The following table lists the inputs for AWS Blocked Traffic - Kentik - Example:

servicenow

msteams

aws_ec2

https://iap_dev:443

https://servicenow_dev.com

webhookURL

webhookURL

webhookURL

webhookURL

180173

ackReq

{}

198465

US

13.13.13.13

45.129.14.30

REJECT

security-group

vpc-0bf364141dd4f9120

[]

DashboardAlarmURL

Open Dashboard

https://portal.kentik.com/v4/library/dashboards/18392

Alarm for Web Server Traffic Rejections Requires Ack

US Policy Rejected Web Server Traffic

266940386

Custom

critical

446709

Outputs

There are no outputs for AWS Blocked Traffic - Kentik - Example.

Query Output

There are no query output examples for AWS Blocked Traffic - Kentik - Example.

Example Inputs and Outputs

Example 1

Input:

{
  "iapUrl": "https://iap-dev:443",
  "serviceNowUrl": "https://service-now.com",
  "allPolicyEventsWebhookUrl": "webhookurl1",
  "policyAutomatedFailureWebhookUrl": "webhookurl2",
  "policyAutomatedAuthorizationWebhookUrl": "webhookurl3",
  "serviceNowAdapter": "ServiceNow",
  "awsEC2Adapter": "AWS",
  "msTeamsAdapter": "MS Teams",
  "AlarmPolicyName": "US Policy Rejected Web Server Traffic",
  "Dimensions": {
    "AS_src": "1000",
    "IP_dst": "11.11.11.11",
    "IP_src": "10.10.10.10",
    "kt_aws_dst_sg": "aws_security_group"
  },
  "Links": [
    {
      "Name": "DashboardAlarmURL",
      "Label": "Open Dashboard",
      "Value": "https://portal.kentik.com/v4/library/dashboards/10000"
    },
    {
      "Name": "DetailsAlarmURL",
      "Label": "Open Details",
      "Value": "https://portal.kentik.com/v4/alerting/a215729224"
    }
  ]
} 

Output:

{} 

API Links

AWS Blocked Traffic - Reset - Kentik - Example

Workflow that is used to remove source IP from security group in AWS to reset data for AWS Blocked Traffic - Kentik - Example automation

Capabilities include:

• Removes IP from security group in AWS

Entry Point IAP Component

The primary IAP component to run AWS Blocked Traffic - Reset - Kentik - Example is listed below:

Inputs

The following table lists the inputs for AWS Blocked Traffic - Reset - Kentik - Example:

10.10.10.10

AWS

security-group-east

Outputs

There are no outputs for AWS Blocked Traffic - Reset - Kentik - Example.

Query Output

There are no query output examples for AWS Blocked Traffic - Reset - Kentik - Example.

Example Inputs and Outputs

Example 1

Input:

{
    "sourceIP": "10.10.10.10",
    "awsEC2Adapter": "AWS",
    "awsSecurityGroup": "security_group"
  } 

Output:

{} 

API Links

No API Links provided.

Device Onboarding - Kentik - Example

This automation example can be installed and reviewed for ideas on how to query a Cisco IOS device from NetBox that has already been onboarded to Itential Automation Gateway (IAG) and then onboards the device into Kentik. Once onboarded into Kentik, the device is configured via IAG to send flow data to Kentik. Finally, the automation validates that Kentik has received flow data from the device.

IAP updates NetBox with the Kentik device ID and keeps Change Management up to date integrating with ServiceNow and MS Teams for notifications throughout the automation.

Capabilities include:

• Creates ServiceNow Change Request
• Retrieves device details from NetBox
• Sends Microsoft Teams notification before device creation attempt
• Creates device in Kentik
• Updates NetBox device details with Kentik ID
• Gets Kentik company settings for flow test
• Configures Cisco IOS device over Itential Automation Gateway for flow test
• Runs traffic flow test in Kentik
• Sends Microsoft Teams notification after device creation and flow test with links to Kentik, SerivceNow Change Request, and Itential job

Configuring Dependencies

NetBox

A single Cisco IOS device needs to be set in NetBox that has a name, a site name, and local config context data. See example object with these fields provided below.

{
  "name": "ATLSWITCH01",
  "site": {
    "name": "ATL HQ"
  },
  "config_context": {
    "ipAddress": "1.2.3.4",
    "sampleRate": 1,
    "snmpV3Conf": {
      "userName": "username",
      "privacyProtocol": "AES",
      "privacyPassphrase": "passphrase",
      "authenticationProtocol": "SHA",
      "authenticationPassphrase": "password"
    },
    "description": "IOS Device"
  }
}

Microsoft Teams

This IAP automation sends formatted messages over Microsoft Teams with links to the IAP job run, a ServiceNow Change Request created for the device onboarding event, and the Kentik flow data. One Microsoft Teams channel called Device Onboarding is used in this automation that requires creating an Incoming Webhook.

Follow the Microsoft Teams documentation linked for creating Incoming Webhooks for setting up the webhook for that channel.

Itential Automation Gateway

A Cisco IOS device must be onboarded to Itential Automation Gateway (IAG) as an Ansible inventory device. See example properties in JSON object below for this:

{
  "ansible_network_os": "ios",
  "host_key_checking": 0,
  "ansible_port": 22,
  "ansible_user": "username",
  "ansible_password": "password",
  "ansible_host": "10.10.10.10",
  "ansible_connection": "network_cli"
}

Entry Point IAP Component

The primary IAP component to run Device Onboarding - Kentik - Example is listed below:

Inputs

The following table lists the inputs for Device Onboarding - Kentik - Example:

IOS_Device_Name

https://iap_dev:443

https://servicenow_dev.com

webhookURL

servicenow

netboxv3

msteams

kentik

Outputs

There are no outputs for Device Onboarding - Kentik - Example.

Query Output

There are no query output examples for Device Onboarding - Kentik - Example.

Example Inputs and Outputs

Example 1

Input:

{
  "formData": {
    "iapUrl": "https://iap-dev:443",
    "deviceOnboardingWebhookUrl": "webhookURL1",
    "serviceNowUrl": "https://service-now-dev.com",
    "deviceName": "ios_device",
    "serviceNowAdapter": "ServiceNow",
    "netBoxAdapter": "NetboxV3",
    "msTeamsAdapter": "MS Teams",
    "kentikAdapter": "Kentik v5"
  }
} 

Output:

{} 

API Links

Device Onboarding - Reset - Kentik - Example

Automation removes flow test Cisco IOS device configuration and deletes device from Kentik to reset data for Device Onboarding - Kentik - Example automation

Capabilities include:

• Removes flow test configuration on Cisco IOS device over Itential Automation Gateway
• Archives and then deletes device from Kentik

Entry Point IAP Component

The primary IAP component to run Device Onboarding - Reset - Kentik - Example is listed below:

Inputs

The following table lists the inputs for Device Onboarding - Reset - Kentik - Example:

ios_device

kentik

Outputs

There are no outputs for Device Onboarding - Reset - Kentik - Example.

Query Output

There are no query output examples for Device Onboarding - Reset - Kentik - Example.

Example Inputs and Outputs

Example 1

Input:

{
  "formData":  {
    "deviceName": "ios_device",
    "kentikAdapter": "Kentik v5"
  }
} 

Output:

{} 

API Links

No API Links provided.

Additional Information

Support

Please use your Itential Customer Success account if you need support when using this Workflow Project.

Itential Documents:

Related Items:

Adapters