# InsightIDR4Py
A Python client allowing simplified interaction with Rapid7's InsightIDR REST API.
InsightIDR4Py allows users to perform numerous actions within Rapid7 [InsightIDR](https://docs.rapid7.com/insightidr/). This tool handles some of the challenges and complexities of using the InsightIDR REST API, including polling queries in progress, paginated responses, handling the JSON output, and time range queries.
These capabilities can be particularly useful for automating processes, integrating log data with other APIs (like VirusTotal), managing content in the InsightIDR platform, and performing multi-tenant workflows (for instance, updating content across tenants for consistency, or copying content from one InsightIDR tenant to another). For some ideas on how InsightIDR4Py can be used, check out this [blog post](https://micahbabinski.medium.com/button-pusher-to-masterbuilder-automating-siem-workflows-3f51874a80e) where I cover some use cases.
The API capabilities provided by InsightIDR4Py include:
## Logsearch
* Query Events
* Query Groups
## Saved Queries
* List Saved Queries
* Get a Saved Query
* Create Saved Query
* Replace a Saved Query
* Update a Saved Query
* Delete a Saved Query
## Custom Alerts*
* List Custom Alerts
* Get a Custom Alert
* Create Custom Alert
* Replace a Custom Alert
* Update a Custom Alert
* Delete a Custom Alert
*Only pattern detection alerts are supported currently.
## Investigations
* List Investigations
* Get an Investigation
* Create Investigation
* Close Investigations in Bulk
* List Alerts by Investigation
* List Rapid7 Product Alerts by Investigation
* Update Investigation
* List Comments on an Investigation
* Create Comment
* Delete Comment
## Threats
* Create Threat
* Add Indicators to Threat
* Replace Threat Indicators
* Delete Threat
Happy analyzing :monocle_face: and happy administering! :hammer:
# Installation
InsightIDR4Py is available on [PyPI](https://pypi.org/project/InsightIDR4Py/) and can be installed using:
```
pip install InsightIDR4Py
```
# Prerequisites
You will need obtain an API key from the InsightIDR system. The documentation for this can be found [here](https://docs.rapid7.com/insight/managing-platform-api-keys/). From there, you'll use this API key value to create the InsightIDR API object as shown below:
```python
import InsightIDR4Py as idr
# define API key (store this value securely)
api_key = "API_Key_Here"
# create the InsightIDR object
api = idr.InsightIDR(api_key)
```
Remember to store the API key securely! There are several ways to do this, and you should make sure that the way you choose aligns with your organization's security policy. Python's [keyring](https://pypi.org/project/keyring/) library is one possibility.
# Examples
## Example 1: Query DNS Logs for Suspicious TLDs
```python
import InsightIDR4Py as idr
# create the InsightIDR object
api = idr.InsightIDR(api_key)
# define the query parameters
logset_name = "DNS Query"
query = "where(public_suffix IN [buzz, top, club, work, surf, tw, gq, ml, cf, biz, tk, cam, xyz, bond])"
time_range = "Last 36 Hours"
# query the logs
events = api.QueryEvents(logset_name, query, time_range)
# print out an event
print(event[0])
```
Result:
```python
{'timestamp': '2021-09-28T15:11:45.000Z', 'asset': 'windesk05.organization.com', 'source_address': '192.168.4.10', 'query': 'regulationprivilegescan.top', 'public_suffix': 'top', 'top_private_domain': 'regulationprivilegescan.top', 'query_type': 'A', 'source_data': '09/28/2021 8:11:45 AM 1480 PACKET 00000076ED1A0140 UDP Rcv 192.168.4.121 c3b3 Q [0001 D NOERROR] A (3)regulationprivilegescan(3)top(0)'}
```
## Example 2: Query Authentication Logs for top Five Failed Logins, Grouped by Count
```python
import InsightIDR4Py as idr
# create the InsightIDR object
api = idr.InsightIDR(api_key)
# define the query parameters
logset_name = "Asset Authentication"
query = "where(source_json.eventCode = 4625) groupby(destination_account) limit(5)"
time_range = "Last 24 Hours"
# query the logs
groups = api.QueryGroups(logset_name, query, time_range)
# print out the groups
for group in groups.items():
print(group)
```
Result:
```
('Mark.Corrigan', 132)
('Jeremy.Usborne', 102)
('Sophie.Chapman', 88)
('Alan.Johnson', 64)
('Super.Hans', 24)
```
## Example 3: Query VPN Logins from a Certain IP Range and Check the Results Using [AbuseIPDB](https://www.abuseipdb.com/)
This example uses [python-abuseipdb](https://github.com/meatyite/python-abuseipdb), a Python object oriented wrapper for AbuseIPDB v2 API.
It requires an API key, which you can get by creating a free account. From there, go to User Account > API, choose Create Key, and enter this string into the abuse_ip_db_api_key variable in the example below.
The same API key security principles mentioned above apply here. Guard your API keys to prevent rogue usage!
```python
import InsightIDR4Py as idr
import abuseipdb import *
# create the InsightIDR object
api = idr.InsightIDR(api_key)
# define the AbuseIPDB API key
abuse_ip_db_api_key = "YOUR_KEY_HERE"
# define the query parameters
logset_name = "Ingress Authentication"
query = "where(service = vpn AND source_ip = IP(64.62.128.0/17))"
time_range = "Last 24 Hours"
# query the logs
events = api.QueryEvents(logset_name, query, time_range)
# check the source IP addresses in AbuseIPDB and display results
if len(events) > 0:
ipdb = AbuseIPDB(abuse_ip_db_api_key)
for event in events:
check = ipdb.check(event["source_ip"])
print("----------")
print("IP Address: " + ip_check.ipAddress)
print("Last reported at: " + ip_check.lastReportedAt)
print("Abuse confidence score: " + str(ip_check.abuseConfidenceScore))
print("Abuser country: " + ip_check.countryName)
print("Abuser ISP: " + ip_check.isp)
print("Total reports of abuser: " + str(ip_check.totalReports))
print("----------")
```
# License
This repository is licensed under an [MIT license](https://github.com/mbabinski/InsightIDR4Py/blob/main/LICENSE), which grants extensive permission to use this material however you wish.
# Contributing
You are welcome to contribute however you wish! I appreciate feedback in any format.
Raw data
{
"_id": null,
"home_page": "https://github.com/mbabinski/InsightIDR4Py",
"name": "InsightIDR4Py",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Rapid7,InsightIDR,SIEM,Logsearch,Investigations,Threats,Alerts",
"author": "Micah Babinski",
"author_email": "m.babinski.88@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/79/ca/aa3dd306eb0965fe8f2b1326bae85d78f0bf7761e02a9007383a513d8301/InsightIDR4Py-0.3.1.tar.gz",
"platform": null,
"description": "# InsightIDR4Py\r\nA Python client allowing simplified interaction with Rapid7's InsightIDR REST API.\r\n\r\nInsightIDR4Py allows users to perform numerous actions within Rapid7 [InsightIDR](https://docs.rapid7.com/insightidr/). This tool handles some of the challenges and complexities of using the InsightIDR REST API, including polling queries in progress, paginated responses, handling the JSON output, and time range queries.\r\n\r\nThese capabilities can be particularly useful for automating processes, integrating log data with other APIs (like VirusTotal), managing content in the InsightIDR platform, and performing multi-tenant workflows (for instance, updating content across tenants for consistency, or copying content from one InsightIDR tenant to another). For some ideas on how InsightIDR4Py can be used, check out this [blog post](https://micahbabinski.medium.com/button-pusher-to-masterbuilder-automating-siem-workflows-3f51874a80e) where I cover some use cases.\r\n\r\nThe API capabilities provided by InsightIDR4Py include:\r\n## Logsearch\r\n* Query Events\r\n* Query Groups\r\n\r\n## Saved Queries\r\n* List Saved Queries\r\n* Get a Saved Query\r\n* Create Saved Query\r\n* Replace a Saved Query\r\n* Update a Saved Query\r\n* Delete a Saved Query\r\n\r\n## Custom Alerts*\r\n* List Custom Alerts\r\n* Get a Custom Alert\r\n* Create Custom Alert\r\n* Replace a Custom Alert\r\n* Update a Custom Alert\r\n* Delete a Custom Alert\r\n\r\n*Only pattern detection alerts are supported currently.\r\n\r\n## Investigations\r\n* List Investigations\r\n* Get an Investigation\r\n* Create Investigation\r\n* Close Investigations in Bulk\r\n* List Alerts by Investigation\r\n* List Rapid7 Product Alerts by Investigation\r\n* Update Investigation\r\n* List Comments on an Investigation\r\n* Create Comment\r\n* Delete Comment\r\n\r\n## Threats\r\n* Create Threat\r\n* Add Indicators to Threat\r\n* Replace Threat Indicators\r\n* Delete Threat\r\n\r\nHappy analyzing :monocle_face: and happy administering! :hammer:\r\n\r\n# Installation\r\nInsightIDR4Py is available on [PyPI](https://pypi.org/project/InsightIDR4Py/) and can be installed using:\r\n```\r\npip install InsightIDR4Py\r\n```\r\n\r\n# Prerequisites\r\nYou will need obtain an API key from the InsightIDR system. The documentation for this can be found [here](https://docs.rapid7.com/insight/managing-platform-api-keys/). From there, you'll use this API key value to create the InsightIDR API object as shown below:\r\n```python\r\nimport InsightIDR4Py as idr\r\n\r\n# define API key (store this value securely)\r\napi_key = \"API_Key_Here\"\r\n\r\n# create the InsightIDR object\r\napi = idr.InsightIDR(api_key)\r\n```\r\nRemember to store the API key securely! There are several ways to do this, and you should make sure that the way you choose aligns with your organization's security policy. Python's [keyring](https://pypi.org/project/keyring/) library is one possibility.\r\n\r\n# Examples\r\n## Example 1: Query DNS Logs for Suspicious TLDs\r\n```python\r\nimport InsightIDR4Py as idr\r\n\r\n# create the InsightIDR object\r\napi = idr.InsightIDR(api_key)\r\n\r\n# define the query parameters\r\nlogset_name = \"DNS Query\"\r\nquery = \"where(public_suffix IN [buzz, top, club, work, surf, tw, gq, ml, cf, biz, tk, cam, xyz, bond])\"\r\ntime_range = \"Last 36 Hours\"\r\n\r\n# query the logs\r\nevents = api.QueryEvents(logset_name, query, time_range)\r\n\r\n# print out an event\r\nprint(event[0])\r\n```\r\nResult:\r\n```python\r\n{'timestamp': '2021-09-28T15:11:45.000Z', 'asset': 'windesk05.organization.com', 'source_address': '192.168.4.10', 'query': 'regulationprivilegescan.top', 'public_suffix': 'top', 'top_private_domain': 'regulationprivilegescan.top', 'query_type': 'A', 'source_data': '09/28/2021 8:11:45 AM 1480 PACKET 00000076ED1A0140 UDP Rcv 192.168.4.121 c3b3 Q [0001 D NOERROR] A (3)regulationprivilegescan(3)top(0)'}\r\n```\r\n\r\n## Example 2: Query Authentication Logs for top Five Failed Logins, Grouped by Count\r\n```python\r\nimport InsightIDR4Py as idr\r\n\r\n# create the InsightIDR object\r\napi = idr.InsightIDR(api_key)\r\n\r\n# define the query parameters\r\nlogset_name = \"Asset Authentication\"\r\nquery = \"where(source_json.eventCode = 4625) groupby(destination_account) limit(5)\"\r\ntime_range = \"Last 24 Hours\"\r\n\r\n# query the logs\r\ngroups = api.QueryGroups(logset_name, query, time_range)\r\n\r\n# print out the groups\r\nfor group in groups.items():\r\n print(group)\r\n```\r\nResult:\r\n```\r\n('Mark.Corrigan', 132)\r\n('Jeremy.Usborne', 102)\r\n('Sophie.Chapman', 88)\r\n('Alan.Johnson', 64)\r\n('Super.Hans', 24)\r\n```\r\n\r\n## Example 3: Query VPN Logins from a Certain IP Range and Check the Results Using [AbuseIPDB](https://www.abuseipdb.com/)\r\nThis example uses [python-abuseipdb](https://github.com/meatyite/python-abuseipdb), a Python object oriented wrapper for AbuseIPDB v2 API. \r\n\r\nIt requires an API key, which you can get by creating a free account. From there, go to User Account > API, choose Create Key, and enter this string into the abuse_ip_db_api_key variable in the example below.\r\n\r\nThe same API key security principles mentioned above apply here. Guard your API keys to prevent rogue usage!\r\n\r\n```python\r\nimport InsightIDR4Py as idr\r\nimport abuseipdb import *\r\n\r\n# create the InsightIDR object\r\napi = idr.InsightIDR(api_key)\r\n\r\n# define the AbuseIPDB API key\r\nabuse_ip_db_api_key = \"YOUR_KEY_HERE\"\r\n\r\n# define the query parameters\r\nlogset_name = \"Ingress Authentication\"\r\nquery = \"where(service = vpn AND source_ip = IP(64.62.128.0/17))\"\r\ntime_range = \"Last 24 Hours\"\r\n\r\n# query the logs\r\nevents = api.QueryEvents(logset_name, query, time_range)\r\n\r\n# check the source IP addresses in AbuseIPDB and display results\r\nif len(events) > 0:\r\n ipdb = AbuseIPDB(abuse_ip_db_api_key)\r\n for event in events:\r\n\tcheck = ipdb.check(event[\"source_ip\"])\r\n\tprint(\"----------\")\r\n\tprint(\"IP Address: \" + ip_check.ipAddress)\r\n\tprint(\"Last reported at: \" + ip_check.lastReportedAt)\r\n\tprint(\"Abuse confidence score: \" + str(ip_check.abuseConfidenceScore))\r\n\tprint(\"Abuser country: \" + ip_check.countryName)\r\n\tprint(\"Abuser ISP: \" + ip_check.isp)\r\n\tprint(\"Total reports of abuser: \" + str(ip_check.totalReports))\r\n\tprint(\"----------\")\r\n```\r\n\r\n# License\r\nThis repository is licensed under an [MIT license](https://github.com/mbabinski/InsightIDR4Py/blob/main/LICENSE), which grants extensive permission to use this material however you wish.\r\n\r\n# Contributing\r\nYou are welcome to contribute however you wish! I appreciate feedback in any format.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client allowing simplified interaction with Rapid7's InsightIDR REST API.",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/mbabinski/InsightIDR4Py"
},
"split_keywords": [
"rapid7",
"insightidr",
"siem",
"logsearch",
"investigations",
"threats",
"alerts"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5543e5c54a8c1226aa96225663b8f0137f6bb785ca0a5e90bbaa592679dd9a89",
"md5": "ca256458fec58f0a656562a17fe3858d",
"sha256": "0076d768719868771578fb5b6fa3da68d9420a6e1ba494df05b9ce9457316a69"
},
"downloads": -1,
"filename": "InsightIDR4Py-0.3.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca256458fec58f0a656562a17fe3858d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 10260,
"upload_time": "2023-06-13T17:35:59",
"upload_time_iso_8601": "2023-06-13T17:35:59.849303Z",
"url": "https://files.pythonhosted.org/packages/55/43/e5c54a8c1226aa96225663b8f0137f6bb785ca0a5e90bbaa592679dd9a89/InsightIDR4Py-0.3.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79caaa3dd306eb0965fe8f2b1326bae85d78f0bf7761e02a9007383a513d8301",
"md5": "157cd84826869d4b608c23718c6d2522",
"sha256": "eb512a5edba96e8d065d184de60b84e1bb87b2569650e841efd7ee6d6d94b183"
},
"downloads": -1,
"filename": "InsightIDR4Py-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "157cd84826869d4b608c23718c6d2522",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12719,
"upload_time": "2023-06-13T17:36:01",
"upload_time_iso_8601": "2023-06-13T17:36:01.689613Z",
"url": "https://files.pythonhosted.org/packages/79/ca/aa3dd306eb0965fe8f2b1326bae85d78f0bf7761e02a9007383a513d8301/InsightIDR4Py-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-13 17:36:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mbabinski",
"github_project": "InsightIDR4Py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "insightidr4py"
}
JSON
