Skip to main content

Cisco Umbrella APIs wrapper and command-line utility

Project description


Documentation Status


Travis Build Status Requirements Status
Appveyor Build Status coveralls
Codacy Code Quality Status Maintainability


Supported versions Supported implementation
Development status PyPI Package License


GitHub tag GitHub issues


Code style: black EditorConfig Pylint

umbr_api is Cisco Umbrella APIs wrapper and a command-line utility.

Cisco Umbrella uses the internet’s DNS infrastructure to block malicious destinations before a connection is ever established. By delivering security from the cloud, it also provide more effective security and easy deployment options.

umbr_api supports Enforcement API, Reporting API, and Management API with some limitations. With help of umbr_api you can add new sites and URLs to black lists, remove or show current entries, quickly check the latest security events, or check a status of registered computers or networks.

Using of command line tools, like umbr_api can immediately provide information to administrators of the system without myriads of clicks through GUI interfaces, two-factor authentications, etc.


Was created mostly for educational purposes.


To install from a local folder execute at the ‘umbr_api’ root directory:

pip3 install -e . --no-use-pep517

To install extra requirements from a local folder execute at the ‘umbr_api’ root directory:

pip3 install -e .[dev] --no-use-pep517
pip3 install -e .[doc] --no-use-pep517
pip3 install -e .[dev_lint] --no-use-pep517

To install from production The Python Package Index (PyPI) execute:

pip3 install umbr_api

To install from GitHub:

pip3 install git+

To install from a local archive:

pip3 install filename.tar.gz

Please note, that you still need to register and activate API key from Cisco to enable functionality.

Use of command-line utility

main() in will be registered as umbrella executable. So, you can run it directly.

Examples (Enforcement API):

umbrella add
umbrella add --force
umbrella del
umbrella del 555XXXXX --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789
umbrella get 100
umbrella get --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789

Use API wrapper

You need to import particular functions or modules from umbr_api. For example:

from umbr_api import get

from umbr_api.add import add
add(domain='', url='', key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')
There three main functions:
  • umbr_api.get.get_list

  • umbr_api.add.add

  • umbr_api.remove.remove

The API key should be specified via CLI, or it could be read it from enforcement.json within package data\ folder.

API key

How to obtain API key

You can sign up for 14 day free trial here:

How to use API key

  1. Provide it as an argument for command-line utility

umbrella del --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789
  1. Provide it as part of a program call

from umbr_api.get import get_list
response = get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')

#. Create data/enforcement.json file in umbr_api package directory. This is an unsecured and unsupported way because of storing key in clear text format. To find package directory:

import os
import umbr_api

#. API key can be read from a keyring for command-line execution. To save API key you can use:

umbrella keyring --add YOUR-CUSTOMER-KEY-IS-HERE-0123456789
umbrella keyring --show

Supported methods

Enforcement API

  1. Add (POST)

  2. Get (GET)

  3. Remove (DELETE)

Management API

  1. Networks (GET)

  2. Roaming Computers (GET)

  3. Internal Networks (GET)

  4. Virtual Appliances (GET)

  5. Sites (GET)

  6. Users (GET)

  7. Roles (GET)

Reporting API

  1. Security Activity Report (GET)

  2. Destinations: Top Identities (GET)

  3. Destinations: Most recent requests (GET)


  1. Lack of documentation

  2. You heed to have an active subscription or evaluation

  3. Asserts will be removed with compiling to optimized byte code. This caused various protections to be removed.

  4. Other methods for change or delete entities are not supported and no plans to do that

Known issues

Error while accessing macOS keyring

Python’s binaries may not be signed and they will fail to get an access to macOS keyring. You should resign them manually to fix it. Error message:

keyring.backends._OS_X_API.SecAuthFailure: (-25293, 'Security Auth Failure: make sure python is signed with codesign util')
$ codesign -v `which python`
/Users/user/.virtualenvs/builings/bin/python: invalid Info.plist (plist or signature have been modified)
In architecture: x86_64
$ codesign -f -s - `which python`
/Users/user/.virtualenvs/builings/bin/python: replacing existing signature


Documentation pages based on README.rst file and docstrings.

Contribution guidelines

Who do I talk to

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

umbr_api-1.0.3.tar.gz (56.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page