Package: umbr-api
DocsTestsPackageGitHubGuidelinesumbr_apiis Cisco Umbrella APIs wrapper and a command-line utility.Cisco Umbrellauses 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_apisupports Enforcement API, Reporting API, and Management API
with some limitations. With help ofumbr_apiyou 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, likeumbr_apican immediately provide
information to administrators of the system without myriads of clicks
through GUI interfaces, two-factor authentications, etc.References:Cisco Umbrella Enforcement APICisco Umbrella Reporting APICisco Umbrella Management APIWas created mostly for educational purposes.InstallationTo install from a local folder execute at the ‘umbr_api’ root directory:pip3install-e.--no-use-pep517To install extra requirements from a local folder execute at the ‘umbr_api’
root directory:pip3install-e.[dev]--no-use-pep517pip3install-e.[doc]--no-use-pep517pip3install-e.[dev_lint]--no-use-pep517To install from production The Python Package Index (PyPI)https://pypi.orgexecute:pip3installumbr_apiTo install from GitHub:pip3installgit+https://github.com/kolatz/umbr_api.gitTo install from a local archive:pip3installfilename.tar.gzPlease note, that you still need to register and activate API key from Cisco
to enable functionality.Use of command-line utilitymain()inumbrella.pywill be registered asumbrellaexecutable.
So, you can run it directly.Examples (Enforcement API):umbrellaaddwww.example.comhttp://www.example.com/imagesumbrellaaddexample.comexample.com--forceumbrelladelwww.example.comumbrelladel555XXXXX--keyYOUR-CUSTOMER-KEY-IS-HERE-0123456789umbrellaget100umbrellaget--keyYOUR-CUSTOMER-KEY-IS-HERE-0123456789Use API wrapperYou need to import particular functions or modules fromumbr_api. For example:fromumbr_apiimportgetget.get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')fromumbr_api.addimportaddadd(domain='example.com',url='example.com',key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')There three main functions:umbr_api.get.get_listumbr_api.add.addumbr_api.remove.removeThe API key should be specified via CLI, or it could be read it fromenforcement.jsonwithin packagedata\folder.API keyHow to obtain API keyYou can sign up for 14 day free trial here:https://signup.umbrella.com/How to use API keyProvide it as an argument for command-line utilityumbrelladelwww.example.com--keyYOUR-CUSTOMER-KEY-IS-HERE-0123456789Provide it as part of a program callfromumbr_api.getimportget_listresponse=get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')#. Createdata/enforcement.jsonfile inumbr_apipackage directory.
This is an unsecured and unsupported way because of storing key in clear text
format. To find package directory:importosimportumbr_apiprint(os.path.abspath(umbr_api.__file__))#. API key can be read from a keyring for command-line execution. To save
API key you can use:umbrellakeyring--addYOUR-CUSTOMER-KEY-IS-HERE-0123456789umbrellakeyring--showNoteOnly macOS platform is tested for keyringsBy default all python apps can read the values of the keys from a keyringumbrellawill try to use--keyfirstly, then keychain, and finallydata/enforcement.jsonfile withinumbr_apipackage directory.Supported methodsEnforcement APIAdd (POST)Get (GET)Remove (DELETE)Management APINetworks (GET)Roaming Computers (GET)Internal Networks (GET)Virtual Appliances (GET)Sites (GET)Users (GET)Roles (GET)Reporting APISecurity Activity Report (GET)Destinations: Top Identities (GET)Destinations: Most recent requests (GET)LimitationsLack of documentationYou heed to have an active subscription or evaluationAsserts 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 thatKnown issuesError while accessing macOS keyringPython’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`whichpython`/Users/user/.virtualenvs/builings/bin/python:invalidInfo.plist(plistorsignaturehavebeenmodified)Inarchitecture:x86_64$codesign-f-s-`whichpython`/Users/user/.virtualenvs/builings/bin/python:replacingexistingsignatureDocumentationDocumentation pages based on README.rst file and docstrings.http://umbr-api.readthedocs.io/en/latest/NoteA symbolic link README.rst –> docs/README.rst was used to create ToC in Sphinx, which doesn’t support relative paths for ToC.Contribution guidelineshttps://github.com/kolatz/umbr_api/blob/master/docs/CONTRIBUTING.mdWho do I talk tohttps://github.com/kolatz/