# Armis Python Library
<p align="center"><strong>armis</strong> <em>- A Python library for interacting with the Armis cloud.</em></p>
<p align="center">
<a href="https://github.com/mmlange/armis-python/actions">
<img src="https://github.com/mmlange/armis-python/actions/workflows/testsuite.yml/badge.svg" alt="Test Suite">
</a>
</p>
**armis** is a Python client library for interacting with the Armis cloud. It connects using **HTTP/2** by default,
falling back to **HTTP/1.1** when necessary. Python 3.8+ is supported.
---
Install **armis** using pip:
```console
$ pip install armis
```
# A Quick Demo of Features
## Getting Started
First, let's create an ArmisCloud object:
```python
from armis import ArmisCloud
a = ArmisCloud(
api_secret_key="your-api-secret-key-here",
tenant_hostname="your-tenant-hostname-here.armis.com"
)
```
## Device Operations
Let's get a list of all devices matching our ASQ and only retrieve a few fields:
```python
devices = a.get_devices(
asq='in:devices timeFrame:"10 Seconds"',
fields=["id", "ipAddress", "name", "firstSeen"]
)
print(devices)
[{"id": 15, "ipAddress": "10.1.2.3", "name": "super-pc", "firstSeen": "2019-05-15T13:00:00+00:00"}]
```
## Boundary Operations
Let's get all of the boundaries known to the system:
```python
boundaries = a.get_boundaries()
print(boundaries)
{1: {'affectedSites': '', 'id': 1, 'name': 'Corporate', 'ruleAql': {'or': ['ipAddress:10.0.0.0/8']}}, 2: {'affectedSites': '', 'id': 2, 'name': 'Guest', 'ruleAql': {'or': ['lastConnectedSsid:Guest']}}}
```
Let's get only one boundary by ID:
```python
boundaryone = a.get_boundary(boundary_id=1)
print(boundaryone)
{"data":{"affectedSites":"","id":1,"name":"Corporate","ruleAql":{"or":["ipAddress:10.0.0.0/8"]}},"success":true}
```
Deleting a boundary is easy:
```python
result = a.delete_boundary(boundary_id=3424234)
print(result)
{"success": True}
```
Creating a boundary is easy, though the syntax is not yet documented well here:
```python
result = a.create_boundary(
name="My New Boundary",
ruleaql={ "or": [
"ipAddress:10.0.0.0/24"
]
}
)
print(result)
{'data': {'id': 392309238}, 'success': True}
```
## Collector Operations
Get a list of collectors:
```python
collectors = a.get_collectors()
print(collectors)
{1234: {'clusterId': 0, 'collectorNumber': 1234, 'defaultGateway': '10.0.0.1', 'httpsProxyRedacted': '', 'ipAddress': '10.0.0.2', 'lastSeen': '2019-05-15T13:00:00+00:00', 'macAddress': '00:12:34:56:78:90', 'name': 'Collector 1234', 'status': 'Offline', 'subnet': '10.0.0.0/24', 'type': 'Physical'}}
```
Get the details for a specific collector:
```python
myimportantcollector = a.get_collector(collector_id=1234)
print(myimportantcollector)
{'clusterId': 0, 'collectorNumber': 1234, 'defaultGateway': '10.0.0.1', 'httpsProxyRedacted': '', 'ipAddress': '10.0.0.2', 'lastSeen': '2019-05-15T13:00:00+00:00', 'macAddress': '00:12:34:56:78:90', 'name': 'Collector 1234', 'status': 'Offline', 'subnet': '10.0.0.0/24', 'type': 'Physical'}
```
## User Operations
Get a list of users:
```python
users = a.get_users()
print(users)
{12: {'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}}
```
Get the details for a specific user, either by userid or email address:
```python
a_user = a.get_user(12)
{'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}
a_user = a.get_user('johndoe@example.com')
{'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}
```
Delete a user by user_id or email address:
```python
a.delete_user('12')
```
## Features
**armis** gives you:
* Easy connection to the Armis cloud using an API secret key.
* A quick way to fetch devices from the cloud.
* Retries in the event the cloud times out. This can happen with large queries that take more than 2 minutes. This is the default for CloudFlare, which front-ends the cloud infrastructure.
* Mostly type annotated.
* Nearly 100% test coverage.
## Installation
Install with pip:
```console
$ pip install armis
```
**armis** requires Python 3.8+.
## Dependencies
**armis** relies on these excellent libraries:
* [furl](https://github.com/gruns/furl) - provides easy-to-use URL parsing and updating
* [httpx](https://github.com/encode/httpx/) - The underlying transport implementation for making HTTP requests
* [msgspec](https://github.com/jcrist/msgspec) - for lightning fast decoding of JSON
* [pendulum](https://github.com/sdispater/pendulum) - for easy date/time management
* [tenacity](https://github.com/jd/tenacity) - retry management when things fail, with great retry/backoff options
## License
`armis` is distributed under the terms of the [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "armis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Matthew Lange <mmlange@gmail.com>",
"keywords": "api, armis, development",
"author": null,
"author_email": "Matthew Lange <mmlange@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/c4/d0987eb70f1ddf33c9029def4784653812609819a0e844a332d8446d30c3/armis-1.0.21.tar.gz",
"platform": null,
"description": "# Armis Python Library\n\n<p align=\"center\"><strong>armis</strong> <em>- A Python library for interacting with the Armis cloud.</em></p>\n\n<p align=\"center\">\n<a href=\"https://github.com/mmlange/armis-python/actions\">\n <img src=\"https://github.com/mmlange/armis-python/actions/workflows/testsuite.yml/badge.svg\" alt=\"Test Suite\">\n</a>\n</p>\n\n**armis** is a Python client library for interacting with the Armis cloud. It connects using **HTTP/2** by default,\nfalling back to **HTTP/1.1** when necessary. Python 3.8+ is supported.\n\n---\n\nInstall **armis** using pip:\n\n```console\n$ pip install armis\n```\n\n# A Quick Demo of Features\n\n## Getting Started\nFirst, let's create an ArmisCloud object:\n```python\nfrom armis import ArmisCloud\n\na = ArmisCloud(\n api_secret_key=\"your-api-secret-key-here\",\n tenant_hostname=\"your-tenant-hostname-here.armis.com\"\n)\n```\n\n## Device Operations\nLet's get a list of all devices matching our ASQ and only retrieve a few fields:\n\n```python\ndevices = a.get_devices(\n asq='in:devices timeFrame:\"10 Seconds\"',\n fields=[\"id\", \"ipAddress\", \"name\", \"firstSeen\"]\n)\nprint(devices)\n\n[{\"id\": 15, \"ipAddress\": \"10.1.2.3\", \"name\": \"super-pc\", \"firstSeen\": \"2019-05-15T13:00:00+00:00\"}]\n```\n\n## Boundary Operations\n\nLet's get all of the boundaries known to the system:\n```python\nboundaries = a.get_boundaries()\nprint(boundaries)\n\n{1: {'affectedSites': '', 'id': 1, 'name': 'Corporate', 'ruleAql': {'or': ['ipAddress:10.0.0.0/8']}}, 2: {'affectedSites': '', 'id': 2, 'name': 'Guest', 'ruleAql': {'or': ['lastConnectedSsid:Guest']}}}\n```\n\nLet's get only one boundary by ID:\n```python\nboundaryone = a.get_boundary(boundary_id=1)\nprint(boundaryone)\n\n{\"data\":{\"affectedSites\":\"\",\"id\":1,\"name\":\"Corporate\",\"ruleAql\":{\"or\":[\"ipAddress:10.0.0.0/8\"]}},\"success\":true}\n```\n\nDeleting a boundary is easy:\n\n```python\nresult = a.delete_boundary(boundary_id=3424234)\nprint(result)\n{\"success\": True}\n```\n\nCreating a boundary is easy, though the syntax is not yet documented well here:\n```python\nresult = a.create_boundary(\n name=\"My New Boundary\",\n ruleaql={ \"or\": [\n \"ipAddress:10.0.0.0/24\"\n ]\n }\n)\nprint(result)\n{'data': {'id': 392309238}, 'success': True}\n```\n\n## Collector Operations\nGet a list of collectors:\n\n```python\ncollectors = a.get_collectors()\nprint(collectors)\n\n{1234: {'clusterId': 0, 'collectorNumber': 1234, 'defaultGateway': '10.0.0.1', 'httpsProxyRedacted': '', 'ipAddress': '10.0.0.2', 'lastSeen': '2019-05-15T13:00:00+00:00', 'macAddress': '00:12:34:56:78:90', 'name': 'Collector 1234', 'status': 'Offline', 'subnet': '10.0.0.0/24', 'type': 'Physical'}}\n```\n\nGet the details for a specific collector:\n\n```python\nmyimportantcollector = a.get_collector(collector_id=1234)\nprint(myimportantcollector)\n\n{'clusterId': 0, 'collectorNumber': 1234, 'defaultGateway': '10.0.0.1', 'httpsProxyRedacted': '', 'ipAddress': '10.0.0.2', 'lastSeen': '2019-05-15T13:00:00+00:00', 'macAddress': '00:12:34:56:78:90', 'name': 'Collector 1234', 'status': 'Offline', 'subnet': '10.0.0.0/24', 'type': 'Physical'}\n```\n\n## User Operations\nGet a list of users:\n```python\nusers = a.get_users()\nprint(users)\n\n{12: {'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}}\n```\n\nGet the details for a specific user, either by userid or email address:\n```python\na_user = a.get_user(12)\n{'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}\n\na_user = a.get_user('johndoe@example.com')\n{'email': 'johndoe@example.com', 'id': 12, 'isActive': True, 'lastLoginTime': '2019-05-15T13:01:23.456789', 'location': '', 'name': 'John Doe', 'phone': '', 'povEulaSigningDate': None, 'prodEulaSigningDate': None, 'reportPermissions': None, 'role': None, 'roleAssignment': [{'name': ['Admin']}], 'title': '', 'twoFactorAuthentication': False, 'username': 'johndoe'}\n```\n\nDelete a user by user_id or email address:\n```python\na.delete_user('12')\n```\n\n## Features\n\n**armis** gives you:\n\n* Easy connection to the Armis cloud using an API secret key.\n* A quick way to fetch devices from the cloud.\n* Retries in the event the cloud times out. This can happen with large queries that take more than 2 minutes. This is the default for CloudFlare, which front-ends the cloud infrastructure.\n* Mostly type annotated.\n* Nearly 100% test coverage.\n\n\n## Installation\n\nInstall with pip:\n\n```console\n$ pip install armis\n```\n\n**armis** requires Python 3.8+.\n\n## Dependencies\n**armis** relies on these excellent libraries:\n* [furl](https://github.com/gruns/furl) - provides easy-to-use URL parsing and updating\n* [httpx](https://github.com/encode/httpx/) - The underlying transport implementation for making HTTP requests\n* [msgspec](https://github.com/jcrist/msgspec) - for lightning fast decoding of JSON\n* [pendulum](https://github.com/sdispater/pendulum) - for easy date/time management\n* [tenacity](https://github.com/jd/tenacity) - retry management when things fail, with great retry/backoff options\n\n## License\n`armis` is distributed under the terms of the [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Connect and perform actions with the Armis cloud",
"version": "1.0.21",
"project_urls": {
"Homepage": "https://github.com/mmlange/armis-python/",
"Issues": "https://github.com/mmlange/armis-python/issues",
"Source": "https://github.com/mmlange/armis-python/"
},
"split_keywords": [
"api",
" armis",
" development"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6abac1c6a45001b3f9f5dcd5abea62503c3c18a202682690a3ce4819de2ef00d",
"md5": "6e1718f9307621825fbfb101fe785912",
"sha256": "998d7442c1aef853c6cb9d876388a0e516b34587f3cfb040e93fe054e1f399eb"
},
"downloads": -1,
"filename": "armis-1.0.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e1718f9307621825fbfb101fe785912",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13722,
"upload_time": "2024-04-26T02:41:48",
"upload_time_iso_8601": "2024-04-26T02:41:48.521196Z",
"url": "https://files.pythonhosted.org/packages/6a/ba/c1c6a45001b3f9f5dcd5abea62503c3c18a202682690a3ce4819de2ef00d/armis-1.0.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17c4d0987eb70f1ddf33c9029def4784653812609819a0e844a332d8446d30c3",
"md5": "bf0b7d5a851f07e17a422194bff47da7",
"sha256": "06ba380686fba1f32dbed3e54dcd79d2f0652cb6870e4bdae7244ed17eae4def"
},
"downloads": -1,
"filename": "armis-1.0.21.tar.gz",
"has_sig": false,
"md5_digest": "bf0b7d5a851f07e17a422194bff47da7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17918,
"upload_time": "2024-04-26T02:41:46",
"upload_time_iso_8601": "2024-04-26T02:41:46.979913Z",
"url": "https://files.pythonhosted.org/packages/17/c4/d0987eb70f1ddf33c9029def4784653812609819a0e844a332d8446d30c3/armis-1.0.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 02:41:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mmlange",
"github_project": "armis-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "furl",
"specs": [
[
"==",
"2.1.3"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.27.0"
]
]
},
{
"name": "msgspec",
"specs": [
[
"==",
"0.18.6"
]
]
},
{
"name": "pendulum",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
"==",
"8.2.3"
]
]
}
],
"lcname": "armis"
}
JSON
