Objective
- How to use vManage REST APIs to configure and monitor DNS Security (Umbrella) policy on SDWAN edge router.
- How to use Umbrella reporting APIs
Introduction
- DNS/web-layer security policies can be centrally managed and monitored using Cisco vManage and Umbrella Dashboards, this enables branch offices with Direct Internet Access (DIA) or Direct Cloud Access(DCA) without undermining security strategies.
- DNS/web-layer security polices can be created per-VPN basics and local-domain bypass rules can be used to achieve granularity.
- By leveraging Cisco’s SD-WAN and Umbrella integration we can deploy DNS/Web-layer Security(Umbrella) policy across the SD-WAN fabric to protect the users against threats such as phishing, malware, ransomware and command & control (c2) callbacks.
- SDWAN edge router redirects the user DNS request packets towards Umbrella resolvers and based on Umbrella policy the DNS response is returned to SDWAN edge router, which is then forwarded to end client. For example, Umbrella policy can be defined to block the Social Networking and Religious category sites and below would be the sample screenshot of browser when client tries to access the site which is blocked by network administrator.
If client tries to access any malware sites, umbrella prevents the access to it and here is the sample screenshot for the same.
Requirements
To use this code you will need:
- Python 3.7+
- SDWAN edge router with device template attached.
- Configure Umbrella API Token on vManage.
Install and Setup
Clone the code to local machine.
git clone https://github.com/suchandanreddy/sdwan-umbrella-policy.git
cd sdwan-umbrella-policy
Setup Python Virtual Environment (requires Python 3.7+)
python3.7 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
Setup local environment variables to provide vManage login details and Device Template Name which is currently attached to the SDWAN Edge router.
Examples:
For MAC OSX and Ubuntu Environment:
export vmanage_host=10.10.10.10
export vmanage_port=443
export username=admin
export password=admin
export device_template_name=BR2-CSR-1000v
For Windows Environment:
set vmanage_host=10.10.10.10
set vmanage_port=443
set username=admin
set password=admin
set device_template_name=BR2-CSR-1000v
After setting the env variables, run the python script configure-umbrella-policy.py
configure-umbrella-policy.py script does the below steps in sequence.
- Fetch uuid of Device Template provided.
- Fetch Feature Templates associated with this Device Template.
- Fetch Umbrella token list-id
- Create a DNS Security Policy using below POST request payload.
{"name":dnssecurity_policy_name,
"type":"DNSSecurity",
"description":dnssecurity_policy_name,
"definition":{"localDomainBypassList":{},
"matchAllVpn":True,
"umbrellaDefault":True,
"localDomainBypassEnabled":False,
"dnsCrypt":True,
"umbrellaData":
{"ref":<b>your-umbrella-listId</b>}}}
Note Above POST request payload can be modified based on your DNS Security policy config requirements.
- Create a Security Policy and attach the DNS Security policy to it.
- Edit Device Template to attach the security policy and push it to the SDWAN edge router.
Sample Response
$ python3 configure-umbrella-policy.py
Fetching Template uuid of BR2-CSR-1000v
Fetching feature templates associated with BR2-CSR-1000v device template
Fetching Umbrella Token list-id
Creating DNS Security policy
Creating Security Policy
security policy uuid: c61d70e9-036c-43ef-8d4c-f733305d34c6
Device uuid: CSR-0e6b5cd8-e811-4d8b-afe9-4c397c87b19b
Fetching device csv values
Attaching new device template
Template push status is done
Device configuration logs
<b>BR-CSR1000v-2#!before config</b>
BR-CSR1000v-2#show sdwan run | sec umbrella
<b>BR-CSR1000v-2#!after config</b>
BR-CSR1000v-2#show sdwan run | sec umbrella
parameter-map type umbrella global
token <b>your-umbrella-token</b>
dnscrypt
vrf 10
dns-resolver umbrella
no match-local-domain-to-bypass
!
BR-CSR1000v-2#
Verify the umbrella device registration status using the command show sdwan umbrella device-registration
Sample Response
BR-CSR1000v-2#show sdwan umbrella device-registration
NAME STATUS TAG DEVICE ID DESCRIPTION
-----------------------------------------------------------------------------
10 200 SUCCESS vpn10 <b>your-device-id</b> Device Id recieved successfully
Monitoring stats for DNS Security(Umbrella) Policy
vManage REST APIs
- Fetch number of DNS redirect packets using REST API resource URL : "statistics/umbrella/aggregation"
Sample Query (To retrieve DNS redirect packets count for last 10 hours with 1 hour interval)
{"query":{
"condition":"AND","rules":
[{"value":["10"],
"field":"entry_time",
"type":"date",
"operator":"last_n_hours"},
{"value":[device_id],
"field":"vdevice_name",
"type":"string",
"operator":"in"},
{"value":["umbrella"],
"field":"type",
"type":"string",
"operator":"in"}]},
"aggregation":
{"metrics":[
{"property":"redirect_pkts","type":"sum"}],
"histogram":{"property":"entry_time",
"type":"minute",
"interval":60,
"order":"asc"}}}
Umbrella Reporting APIs
Step-1:
- Create Umbrella Reporting API keys.
In Umbrella dashboard(https://dashboard.umbrella.com/o/**your-org-id**/#/overview),
to create Umbrella Reporting API keys follow the path, Admin -> API Keys -> "+"
(Create button icon at the top right corner of the screen) -> Select "Umbrella Reporting"
-> Create.
- Copy the API key and secret to your code environment. (Please note for security reasons, Umbrella API secret would be shown only once right after creating the API keys)
Step-2:
-
Use Umbrella APIs to fetch reports to verify if specific destination site is being allowed or blocked.
-
Below URL needs org_id (org_id can be found in umbrella dashboard URL i.e. https://dashboard.umbrella.com/o/your-org-id) and destination site
URL:
- Optional query parameter limit can be used to limit the number of DNS requests details returned for provided destination site.
Step-3:
- Export the SDWAN Edge router system-ip address(for vManage REST APIs), Umbrella API key, secret and Org-id details using below commands based on workstation environment.
For MAC OSX and Ubuntu Environment:
export device_id=<SDWAN edge router system-ip>
export umbrella_key=<your-umbrella-key>
export umbrella_secret=<your-umbrella-secret>
export org_id=<your-org-id>
For Windows Environment:
set device_id=<SDWAN edge router system-ip>
set umbrella_key=<your-umbrella-key>
set umbrella_secret=<your-umbrella-secret>
set org_id=<your-org-id>
Run the python script – python3 monitor-umbrella-policy.py
Note: base64 encode of umbrella_api_key:umbrella_api_secret is used for Authorization in Umbrella APIs
Sample Response
╒═════════════════════════╤════════════════════╕
│ Time │ Redirect packets │
╞═════════════════════════╪════════════════════╡
│ 07/02/2019 20:00:00 UTC │ 0 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 19:00:00 UTC │ 12 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 18:00:00 UTC │ 11 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 17:00:00 UTC │ 8 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 16:00:00 UTC │ 9 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 15:00:00 UTC │ 11 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 14:00:00 UTC │ 59 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 13:00:00 UTC │ 17 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 12:00:00 UTC │ 14 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 11:00:00 UTC │ 101692 │
├─────────────────────────┼────────────────────┤
│ 07/02/2019 10:00:00 UTC │ 204520 │
╘═════════════════════════╧════════════════════╛
Umbrella dashboard statistics for website toknowall.com
{
"requests": [
{
"actionTaken": "BLOCKED",
"categories": [
"Malware"
],
"datetime": "2019-07-02T18:43:20.000Z",
"destination": "toknowall.com",
"externalIp": <b>your-external-ip</b>,
"internalIp": <b>your-internal-ip</b>,
"originId": <b>your-org-id</b>,
"originLabel": "BR-CSR1000v-2-vpn10",
"originType": "Network Devices",
"tags": []
}
]
}
Umbrella dashboard statistics for website facebook.com
{
"requests": [
{
"actionTaken": "BLOCKED",
"categories": [
"Social Networking",
"Application"
],
"datetime": "2019-07-02T18:41:21.202Z",
"destination": "facebook.com",
"externalIp": <b>your-external-ip</b>,
"internalIp": <b>your-internal-ip</b>,
"originId": <b>your-org-id</b>,
"originLabel": "BR-CSR1000v-2-vpn10",
"originType": "Network Devices",
"tags": []
}
]
}
Umbrella dashboard statistics for website ntp.ubuntu.com
{
"requests": [
{
"actionTaken": "ALLOWED",
"categories": [
"Software/Technology",
"Non-Profits"
],
"datetime": "2019-07-03T03:17:49.433Z",
"destination": "ntp.ubuntu.com",
"externalIp": <b>your-external-ip</b>,
"internalIp": <b>your-internal-ip</b>,
"originId": <b>your-org-id</b>,
"originLabel": "BR-CSR1000v-2-vpn10",
"originType": "Network Devices",
"tags": []
}
]
}
Suchandan's blog 
Hey there, You’ve done a fantastic job. I will definitely digg it and
personally suggest to my friends. I am confident they’ll be
benefited from this website.
LikeLiked by 1 person
Thanks for comment! I am glad the content was helpful.
LikeLike