{"id":24202022,"url":"https://github.com/andreygrechin/umbr_api","last_synced_at":"2025-08-27T09:33:09.639Z","repository":{"id":144101950,"uuid":"123465890","full_name":"andreygrechin/umbr_api","owner":"andreygrechin","description":"umbr_api is Cisco Umbrella APIs 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.","archived":false,"fork":false,"pushed_at":"2021-11-09T23:26:09.000Z","size":149,"stargazers_count":7,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-07T21:54:24.771Z","etag":null,"topics":["cisco","opendns","security","umbrella"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andreygrechin.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-03-01T17:05:13.000Z","updated_at":"2023-03-29T15:48:37.000Z","dependencies_parsed_at":"2023-07-15T04:56:46.589Z","dependency_job_id":null,"html_url":"https://github.com/andreygrechin/umbr_api","commit_stats":null,"previous_names":["kolatz/umbr_api"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreygrechin%2Fumbr_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreygrechin%2Fumbr_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreygrechin%2Fumbr_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreygrechin%2Fumbr_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreygrechin","download_url":"https://codeload.github.com/andreygrechin/umbr_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233808551,"owners_count":18733601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cisco","opendns","security","umbrella"],"created_at":"2025-01-13T21:17:40.838Z","updated_at":"2025-01-13T21:17:41.614Z","avatar_url":"https://github.com/andreygrechin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"======\nREADME\n======\n\n.. list-table::\n  :stub-columns: 1\n\n  * - Docs\n    - | |docs|\n  * - Tests\n    - | |travis| |requires|\n      | |appveyor| |coveralls|\n      | |codacy| |codeclimate|\n  * - Package\n    - | |supported-versions| |supported-implementations|\n      | |dev-status| |pypi-version| |license|\n  * - GitHub\n    - | |gh-tag| |gh-issues|\n  * - Guidelines\n    - | |code-style| |editor-config| |linter-pylint|\n\n.. |docs| image:: https://readthedocs.org/projects/umbr-api/badge/?style=flat\n    :target: https://readthedocs.org/projects/umbr_api\n    :alt: Documentation Status\n\n.. |travis| image:: https://travis-ci.org/kolatz/umbr_api.svg?branch=master\n    :target: https://travis-ci.org/kolatz/umbr_api\n    :alt: Travis Build Status\n\n.. |requires| image:: https://requires.io/github/kolatz/umbr_api/requirements.svg?branch=master\n    :target: https://requires.io/github/kolatz/umbr_api/requirements/?branch=master\n    :alt: Requirements Status\n\n.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/hptdwfa7mcsu5tla/branch/master?svg=true\n    :target: https://ci.appveyor.com/project/kolatz/umbr-api/\n    :alt: Appveyor Build Status\n\n.. |coveralls| image:: https://coveralls.io/repos/github/kolatz/umbr_api/badge.svg?branch=master\n    :target: https://coveralls.io/github/kolatz/umbr_api?branch=master\n    :alt: coveralls\n\n.. |codacy| image:: https://api.codacy.com/project/badge/Grade/af8d1fa5bca74a029a3be10afc51b857\n    :target: https://www.codacy.com/app/kolatz/umbr_api?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=kolatz/umbr_api\u0026amp;utm_campaign=Badge_Grade\n    :alt: Codacy Code Quality Status\n\n.. |codeclimate| image:: https://api.codeclimate.com/v1/badges/fc9257657747094f8f5b/maintainability\n    :target: https://codeclimate.com/github/kolatz/umbr_api\n    :alt: Maintainability\n\n.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/umbr_api.svg\n    :target: https://pypi.python.org/pypi/umbr_api\n    :alt: Supported versions\n\n.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/umbr_api.svg\n    :target: https://pypi.python.org/pypi/umbr_api\n    :alt: Supported implementation\n\n.. |dev-status| image:: https://img.shields.io/pypi/status/umbr_api.svg\n    :target: https://pypi.python.org/pypi/umbr_api\n    :alt: Development status\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/umbr_api.svg\n    :target: https://pypi.python.org/pypi/umbr_api\n    :alt: PyPI Package\n\n.. |license| image:: https://img.shields.io/pypi/l/umbr_api.svg\n    :target: https://pypi.python.org/pypi/umbr_api\n    :alt: License\n\n.. |gh-tag| image:: https://img.shields.io/github/tag/kolatz/umbr_api.svg\n    :target: https://GitHub.com/kolatz/umbr_api/tags\n    :alt: GitHub tag\n\n.. |gh-issues| image:: https://img.shields.io/github/issues/kolatz/umbr_api.svg\n    :target: https://GitHub.com/kolatz/umbr_api/issues\n    :alt: GitHub issues\n\n.. |code-style| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/python/black\n    :alt: Code style: black\n\n.. |editor-config| image:: https://img.shields.io/static/v1.svg?label=\u0026message=EditorConfig\u0026color=blue\n    :target: https://editorconfig.org\n    :alt: EditorConfig\n\n.. |linter-pylint| image:: https://img.shields.io/static/v1.svg?label=Linter\u0026message=Pylint\u0026color=blue\n    :target: https://www.pylint.org/\n    :alt: Pylint\n\n**umbr_api** is Cisco Umbrella APIs wrapper and a command-line utility.\n\n`Cisco Umbrella \u003chttps://umbrella.cisco.com/\u003e`__ uses the internet’s\nDNS infrastructure to block malicious destinations before a connection is\never established. By delivering security from the cloud, it also provide\nmore effective security and easy deployment options.\n\n**umbr_api** supports Enforcement API, Reporting API, and Management API\nwith some limitations. With help of **umbr_api** you can add new sites and\nURLs to black lists, remove or show current entries, quickly check\nthe latest security events, or check a status of registered computers\nor networks.\n\nUsing of command line tools, like **umbr_api** can immediately provide\ninformation to administrators of the system without myriads of clicks\nthrough GUI interfaces, two-factor authentications, etc.\n\nReferences:\n    * `Cisco Umbrella Enforcement API \u003chttps://docs.umbrella.com/developer/enforcement-api/domains2/\u003e`__\n    * `Cisco Umbrella Reporting API \u003chttps://docs.umbrella.com/umbrella-api/docs/overview/\u003e`__\n    * `Cisco Umbrella Management API \u003chttps://docs.umbrella.com/umbrella-api/v1.0/reference/\u003e`__\n\nWas created mostly for educational purposes.\n\nInstallation\n------------\n\nTo install from a local folder execute at the ‘umbr_api’ root directory:\n\n.. code:: bash\n\n    pip3 install -e . --no-use-pep517\n\nTo install extra requirements from a local folder execute at the ‘umbr_api’\nroot directory:\n\n.. code:: bash\n\n    pip3 install -e .[dev] --no-use-pep517\n    pip3 install -e .[doc] --no-use-pep517\n    pip3 install -e .[dev_lint] --no-use-pep517\n\nTo install from production The Python Package Index (PyPI) https://pypi.org\nexecute:\n\n.. code:: bash\n\n    pip3 install umbr_api\n\nTo install from GitHub:\n\n.. code:: bash\n\n    pip3 install git+https://github.com/kolatz/umbr_api.git\n\nTo install from a local archive:\n\n.. code:: bash\n\n    pip3 install filename.tar.gz\n\nPlease note, that you still need to register and activate API key from Cisco\nto enable functionality.\n\nUse of command-line utility\n---------------------------\n\n``main()`` in ``umbrella.py`` will be registered as ``umbrella`` executable.\nSo, you can run it directly.\n\nExamples (Enforcement API):\n\n.. code-block:: bash\n\n    umbrella add www.example.com http://www.example.com/images\n    umbrella add example.com example.com --force\n    umbrella del www.example.com\n    umbrella del 555XXXXX --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789\n    umbrella get 100\n    umbrella get --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789\n\nUse API wrapper\n---------------\nYou need to import particular functions or modules from ``umbr_api``. For example:\n\n.. code-block:: python\n\n    from umbr_api import get\n    get.get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')\n\n    from umbr_api.add import add\n    add(domain='example.com', url='example.com', key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')\n\nThere three main functions:\n    - ``umbr_api.get.get_list``\n    - ``umbr_api.add.add``\n    - ``umbr_api.remove.remove``\n\nThe API key should be specified via CLI, or it could be read it from\n``enforcement.json`` within package ``data\\`` folder.\n\nAPI key\n-------\n\nHow to obtain API key\n^^^^^^^^^^^^^^^^^^^^^\n\nYou can sign up for 14 day free trial here: https://signup.umbrella.com/\n\nHow to use API key\n^^^^^^^^^^^^^^^^^^\n\n#. Provide it as an argument for command-line utility\n\n.. code:: bash\n\n    umbrella del www.example.com --key YOUR-CUSTOMER-KEY-IS-HERE-0123456789\n\n#. Provide it as part of a program call\n\n.. code-block:: python\n\n    from umbr_api.get import get_list\n    response = get_list(key='YOUR-CUSTOMER-KEY-IS-HERE-0123456789')\n\n#. Create ``data/enforcement.json`` file in **umbr_api** package directory.\nThis is an unsecured and unsupported way because of storing key in clear text\nformat. To find package directory:\n\n.. code-block:: python\n\n    import os\n    import umbr_api\n    print(os.path.abspath(umbr_api.__file__))\n\n#. API key can be read from a keyring for command-line execution. To save\nAPI key you can use:\n\n.. code-block:: bash\n\n    umbrella keyring --add YOUR-CUSTOMER-KEY-IS-HERE-0123456789\n    umbrella keyring --show\n\n.. note::\n    - Only macOS platform is tested for keyrings\n    - By default all python apps can read the values of the keys from a keyring\n    - ``umbrella`` will try to use ``--key`` firstly, then keychain, and finally ``data/enforcement.json`` file within **umbr_api** package directory.\n\nSupported methods\n-----------------\n\nEnforcement API\n^^^^^^^^^^^^^^^\n#. Add (POST)\n#. Get (GET)\n#. Remove (DELETE)\n\nManagement API\n^^^^^^^^^^^^^^\n#. Networks (GET)\n#. Roaming Computers (GET)\n#. Internal Networks (GET)\n#. Virtual Appliances (GET)\n#. Sites (GET)\n#. Users (GET)\n#. Roles (GET)\n\nReporting API\n^^^^^^^^^^^^^\n#. Security Activity Report (GET)\n#. Destinations: Top Identities (GET)\n#. Destinations: Most recent requests (GET)\n\nLimitations\n-----------\n\n#. Lack of documentation\n#. You heed to have an active subscription or evaluation\n#. Asserts will be removed with compiling to optimized byte code. This caused various protections to be removed.\n#. Other methods for change or delete entities are not supported and no plans to do that\n\nKnown issues\n------------\n\nError while accessing macOS keyring\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nPython's binaries may not be signed and they will fail to get an access to\nmacOS keyring. You should resign them manually to fix it. Error message::\n\n    keyring.backends._OS_X_API.SecAuthFailure: (-25293, 'Security Auth Failure: make sure python is signed with codesign util')\n\n.. code-block:: bash\n\n    $ codesign -v `which python`\n    /Users/user/.virtualenvs/builings/bin/python: invalid Info.plist (plist or signature have been modified)\n    In architecture: x86_64\n    $ codesign -f -s - `which python`\n    /Users/user/.virtualenvs/builings/bin/python: replacing existing signature\n\nDocumentation\n-------------\n\nDocumentation pages based on README.rst file and docstrings.\n\n-  http://umbr-api.readthedocs.io/en/latest/\n\n.. note::\n    - A symbolic link README.rst --\u003e docs/README.rst was used to create ToC in Sphinx, which doesn't support relative paths for ToC.\n\nContribution guidelines\n-----------------------\n\n-  https://github.com/kolatz/umbr_api/blob/master/docs/CONTRIBUTING.md\n\nWho do I talk to\n----------------\n\n-  https://github.com/kolatz/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreygrechin%2Fumbr_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreygrechin%2Fumbr_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreygrechin%2Fumbr_api/lists"}