Source code

umbrella.py

Command-line utility to access Umbrella Enforcement API.

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 keyring --add YOUR-CUSTOMER-KEY-IS-HERE-0123456789

References

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

umbr_api.umbrella.create_parser()[source]

Create argparse parser, return args.

umbr_api.umbrella.save_key(key)[source]

Save API key to the keychain.

umbr_api.umbrella.show_key()[source]

Read and show API key from the keyring.

umbr_api.umbrella.setup_logging_level(verbose_level)[source]

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)[source]

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)[source]

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)[source]

Format results.

umbr_api.get.main(test_key=None)[source]

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)[source]

Add domain name to block list.

umbr_api.add.format_response(response)[source]

Format results.

umbr_api.add.main(test_key=None)[source]

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)[source]

Remove a record from the policy.

umbr_api.remove.format_response(response)[source]

Format results.

umbr_api.remove.main(test_key=None)[source]

Test if executed directly.

_http_requests.py

Wrapper for request module calls.

umbr_api._http_requests.send_get(url)[source]

Send HTTP GET request via ‘requests’ module.

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

Send HTTP request via ‘requests’ module.

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

Send HTTP POST request via ‘requests’ module.

umbr_api._http_requests.send_delete(url, headers=None)[source]

Send HTTP DELETE request via ‘requests’ module.

umbr_api._http_requests.response_logging(response)[source]

Log responses.

_key.py

Return Umbrella Enforcement API key.

umbr_api._key.get_key(key=None, filename='customer_key.json')[source]

Check API key if provided or read it from the file.

umbr_api._key.main()[source]

Test if executed directly.

__about__.py

Configure package wide attributes.