Cisco Umbrella APIs wrapper and command-line utility
Project description
Docs |
 |
|---|---|
Tests |
      |
Package |
     |
GitHub |
  |
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, not only do you save money, but we also provide more effective security.
umbr_api supports Enforcement API, Reporting API, and Management API with limitations. With help of umbr_api you can add new sites and URLs to the black list, remove or show current entries, quickly check the latest security events, or check the 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.
- References:
Created mostly for educational purposes.
Installation
To install from a local folder execute at the ‘umbr_api’ root directory:
pip3 install -e .To install extra requirements from a local folder execute at the ‘umbr_api’ root directory:
pip3 install -e .[dev]
pip3 install -e .[doc]
pip3 install -e .[dev_lint]To install from production https://pypi.org execute:
pip3 install umbr_apiTo install from GitHub:
pip3 install git+https://github.com/kolatz/umbr_api.gitTo install from local archive:
pip3 install filename.tar.gzPlease note, that you still need register and activate API key from Cisco to enable functionality.
Use of command-line utility
main() in umbrella.py registered as umbrella executable. So, you can run it directly.
Examples:
umbrella add www.example.com http://www.example.com/images
umbrella add example.com example.com --force
umbrella del www.example.com
umbrella del 555XXXXX --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789
umbrella get 100
umbrella get --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789Use API wrapper
You need to import particular functions or modules from umbr_api. For example:
from umbr_api import get
get.get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')
from umbr_api.add import add
add(domain='example.com', url='example.com', 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, if not functions try to 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: https://signup.umbrella.com/
How to use API key
Provide as an argument for command-line utility
umbrella del www.example.com --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789Provide it as part of a program call
from umbr_api.get import get_list
response = get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')3. Create data/enforcement.json file within umbr_api package directory. This is an unsecured and unsupported way because of keeping key in clear text format. To find package directory:
import os
import umbr_api
print(os.path.abspath(umbr_api.__file__))4. 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 --showSupported methods
Enforcement API
Add (POST)
Get (GET)
Remove (DELETE)
Management API
Networks (GET)
Roaming Computers (GET)
Internal Networks (GET)
Virtual Appliances (GET)
Sites (GET)
Users (GET)
Roles (GET)
Reporting API
Security Activity Report (GET)
Destinations: Top Identities (GET)
Destinations: Most recent requests (GET)
Limitations
Lack of documentation
You heed to have an Umbrella subscription or active evaluation
Storing API key within json file is not secure
Asserts will be removed with compiling to optimized byte code. This caused various protections to be removed.
Other methods for change or delete entities are not supported and no plans to do that
Documentation
Documentation pages based on README.rst file and docstrings. Created for educational purposes.
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.
