README¶
Docs | |
---|---|
Tests | |
Package | |
GitHub |
umbr_api is Cisco Umbrella Enforcement API wrapper and command-line utility. With help of umbr_api you can add new sites and URL to the customer’s blocked site list, remove or show current entries from cli in seconds.
Cisco Umbrella uses the internet’s 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.
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_api
To install from GitHub:
pip3 install git+https://github.com/kolatz/umbr_api.git
To install from local archive:
pip3 install filename.tar.gz
Please note, that you still need registered and active 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-0123456789
Use 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 customer_key.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-0123456789
- 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')
3. Create data/customer_key.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 --show
Note
- Only MacOS platform is tested for keyrings
- By default all python apps can read the value of the key from a keyring
umbrella
will try to use--key
firstly, then keychain, and finallydata/customer_key.json
file within umbr_api package directory.
Limitations¶
- Lack of documentation
- You heed to have an Umbrella subscription or active evaluation
- Storing API key within json file is not secure, better to provide it to the script directly
- Asserts will be removed with compiling to optimized byte code. This caused various protections to be removed.
Documentation¶
Documentation pages based on README.rst file and docstrings. Created for educational purposes.
Note
A symbolic link README.rst –> docs/README.rst was used to create ToC in Sphinx, which doesn’t support relative paths for ToC.