Source code

umbrella.py

Command-line utility to access Umbrella APIs.

Examples

umbrella add www.example.com http://www.example.com/images
umbrella del www.example.com
umbrella del 297XXXXX --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789
umbrella -vv get 50
umbrella get --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789
umbrella networks
umbrella recent github.com
umbrella keyring --add-enforcement YOUR-CUSTOMER-KEY-IS-HERE-0123456789

APIs references:

https://docs.umbrella.com/developer/enforcement-api/ https://docs.umbrella.com/umbrella-api/reference https://docs.umbrella.com/umbrella-api/docs/overview

umbr_api.umbrella.create_parser()

Create argparse parser, return args.

umbr_api.umbrella.save_key(key, name)

Save API credentials to the system keyring.

umbr_api.umbrella.show_key(name)

Read and show API credentials from the keyring.

umbr_api.umbrella.setup_logging_level(verbose_level)

Define logging level.

By default logging.WARNING level is enabled. -v arguments can be used to increase logging level. Two levels are supported: logging.INFO and logging.DEBUG.

umbr_api.umbrella.main(args=None)

Execute main body, console_script entry point.

get.py

API call to Umbrella Enforcement API to get blocked domain list.

Example

Examples can be given using either the Example or Examples sections. Sections support any reStructuredText formatting, including literal blocks:

>>> from umbr_api.get import get_list
>>> response = get_list(key="KEY")
>>> print(response.status_code)
200

PEP 484 type annotations are supported. If attribute, parameter, and return types are annotated according to PEP 484, they do not need to be included in the docstring:

Todo

• Add args to show all existing records without pagination.

References

https://docs.umbrella.com/developer/enforcement-api/domains2/

umbr_api.get.get_list(page=1, limit=10, key=None)

Return response tuple as response to API call.

Note

Up to 200 records can be returned by API.

Parameters:

• page (int) – Page # to request.
• limit (int) – Limit number of records to request.
• key (str) – API key, if not specify obtain via key module.

Returns:

Return requests.Response object. http://docs.python-requests.org/en/master/api/#requests.Response

umbr_api.get.format_response(code, json_response)

Format results.

umbr_api.get.main(test_key=None)

Test if executed directly.

add.py

API call to add a record via Umbrella Enforcement API.

Note

When posting data to the Security Platform API, the following steps are taken before the domain appears in a customer’s block list. The optional parameter “disableDstSafeguards” can be used to bypass parts of this process as outlined in the Generic Event Format Field Descriptions. The domain acceptance process is outlined from start to finish here:

1. An external source identifies malicious activity occurring when a user visits a particular URL. This source could be a third party vendor’s data feed, an entry in one of your security logs or something identified as malicious on a security related website.

2. The event is sent to the Umbrella Security Platform API via a POST request, following the steps and syntax outlined earlier in this documentation.

3. Before the domain included API POST event is added to the specified Umbrella customer’s block list, the following checks are performed:

1. Does the domain already exist in the Umbrella Security global block list under one of the Security Categories?
2. Is the domain considered benign, or safe, under the Cisco Umbrella Investigate?
3. Is the status of the domain uncategorized?
4. Is the domain already present on the customer’s allow list within the organization?

4. If the domain is then added to the customer’s domain list, then any domains in that list will be blocked in accordance with that customer’s Umbrella policy security settings.

References

https://docs.umbrella.com/developer/enforcement-api/events2/ https://docs.umbrella.com/developer/enforcement-api/domain-acceptance-process2/

umbr_api.add.add(domain=None, url=None, key=None, bypass=False)

Add domain name to block list.

umbr_api.add.format_response(response)

Format results.

umbr_api.add.main(test_key=None)

Test if executed directly.

remove.py

API call to Umbrella Enforcement API to remove a policy record.

References

https://docs.umbrella.com/developer/enforcement-api/domain2/

umbr_api.remove.remove(record_id=None, key=None)

Remove a record from the policy.

umbr_api.remove.format_response(response)

Format results.

umbr_api.remove.main(test_key=None)

Test if executed directly.

management.py

API calls to Umbrella Management API.

References

https://docs.umbrella.com/umbrella-api/v1.0/reference

umbr_api.management.management_api(command, orgid=None, cred=None, limit=10, page=1, **kwargs)

Send a command to Umbrella Management API.

umbr_api.management.json_to_table(_json)

Convert json object to table.

umbr_api.management.networks(**kwargs)

Request networks info.

umbr_api.management.roamingcomputers(**kwargs)

Request roaming computers info.

umbr_api.management.internalnetworks(**kwargs)

Request internal networks info.

umbr_api.management.virtualappliances(**kwargs)

Request virtual appliances info.

umbr_api.management.sites(**kwargs)

Request sites info.

umbr_api.management.users(**kwargs)

Request users info.

umbr_api.management.roles(**kwargs)

Request roles info.

umbr_api.management.main()

Test if executed directly.

reporting.py

API calls to Umbrella Reporting API.

References

https://docs.umbrella.com/umbrella-api/docs/overview

umbr_api.reporting.get_headers(cred=None, filename=None)

Return headers for basic HTTP authentication.

Returns:

Basic authorization header, including Base64 encoded

username and password.

Return type:str

umbr_api.reporting.activity(cred=None, orgid=None, **kwargs)

Request the last security activities.

Parameters:

• orgid (str) – Cisco Umbrella organization ID
• limit (int) – the number of results to return, from 1 to 500
• start (int) – the start of the time window for which results are shown, specified as Unix (epoch) timestamp in seconds.
• stop (int) – the stop of the time window for which results are shown, specified as Unix (epoch) timestamp in seconds
• _stop_timest (int) – used for pagination and gathered from the output of the previous query, specified as Unix (epoch) timestamp in milliseconds. (not implemented)

Returns:

Return requests.Response class object

Return type:

requests.Response

umbr_api.reporting.top_identities(destination, cred=None, orgid=None, **kwargs)

Request top10 identities which send DNS requests to destination.

Parameters:

• destination (str) – a domain name specified without any protocol or delimiters
• orgid (str) – Cisco Umbrella organization ID

Returns:

Return requests.Response class object

Return type:

requests.Response

umbr_api.reporting.recent(destination, cred=None, orgid=None, offset=0, **kwargs)

Request the most recent DNS requests for a particular destination.

Parameters:

• destination (str) – a domain name specified without any
• orgid (str) – Cisco Umbrella organization ID protocol or delimiters
• limit (int) – number of requests for the specified destination returned
• offset (int) – changes which index the list of returned orgs starts at. Default is 0, and orgs are listed in reverse alphabetical order. Offset essentially allows for pagination. If the first set of results shows 50, then offset=50 shows the next fifty and offset=100 shows the next fifty after that.

Returns:

Return requests.Response class object

Return type:

requests.Response

umbr_api.reporting.main()

Test if executed directly.

_http_requests.py

Wrapper for request module calls.

umbr_api._http_requests.send_get(url, headers=None)

Send HTTP GET request via requests module.

umbr_api._http_requests.send_any(method, url, headers=None, data=None)

Send HTTP request via requests module.

umbr_api._http_requests.send_post(url, data=None, headers=None)

Send HTTP POST request via requests module.

umbr_api._http_requests.send_delete(url, headers=None)

Send HTTP DELETE request via requests module.

umbr_api._http_requests.response_logging(response)

Log responses.

credentials.py

Check provided credentails or read them from file.

umbr_api.credentials.get_key(key=None, filename='umbrella.json')

Return Umbrella Enforcement API customer key.

umbr_api.credentials.get_orgid(orgid=None, filename='umbrella.json')

Return orgid string.

umbr_api.credentials.get_base64(cred=None, filename='umbrella.json', api=None)

Return base64 encoded string.

umbr_api.credentials.main()

Test if executed directly.

__about__.py

Configure package wide attributes.

__init__.py

Init.