Files
prowler/examples/api/api-key.ipynb
T

567 lines
24 KiB
Plaintext

{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Prowler API Examples"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Create a New API key\n",
"Follow the instructions in the [Prowler documentation](https://docs.prowler.com/user-guide/providers/prowler-app-api-keys#creating-api-keys) to create a new API key."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Set the API key\n",
"\n",
"You can set your API key as an environment variable like this:\n",
"```bash\n",
"export PROWLER_API_KEY=<your-api-key>\n",
"```\n",
"\n",
"But, for security reasons, in this notebook we will use the `getpass` library to ask for the API key."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [],
"source": [
"import getpass\n",
"\n",
"prowler_api_key = getpass.getpass(\"Enter your Prowler API key: \")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 3. Use the API key"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### List Providers"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"links\": {\n",
" \"first\": \"https://api.dev.prowler.com/api/v1/providers?page%5Bnumber%5D=1\",\n",
" \"last\": \"https://api.dev.prowler.com/api/v1/providers?page%5Bnumber%5D=2\",\n",
" \"next\": \"https://api.dev.prowler.com/api/v1/providers?page%5Bnumber%5D=2\",\n",
" \"prev\": null\n",
" },\n",
" \"data\": [\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"50af9045-023a-4390-b2a6-7e08bb482c7e\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-10-21T14:13:18.925063Z\",\n",
" \"updated_at\": \"2025-10-21T15:09:54.262401Z\",\n",
" \"provider\": \"m365\",\n",
" \"uid\": \"prowler.com\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": true,\n",
" \"last_checked_at\": \"2025-10-21T15:09:54.257607Z\"\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"d7308e68-ab2e-4c22-b388-e5005a5fc57d\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/50af9045-023a-4390-b2a6-7e08bb482c7e\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"e3bf0cb7-791f-42fd-9d19-b6d7db72290a\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-10-13T09:56:07.101323Z\",\n",
" \"updated_at\": \"2025-10-13T10:43:55.963669Z\",\n",
" \"provider\": \"gcp\",\n",
" \"uid\": \"empty-project-465413\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": true,\n",
" \"last_checked_at\": \"2025-10-13T10:43:55.959115Z\"\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"52f16eeb-14d6-46b8-9c97-a283e5386ac2\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/e3bf0cb7-791f-42fd-9d19-b6d7db72290a\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"53237f83-5c4d-45e4-82f3-aa9da4bbbe00\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-10-07T13:57:15.884120Z\",\n",
" \"updated_at\": \"2025-10-07T13:57:15.884136Z\",\n",
" \"provider\": \"gcp\",\n",
" \"uid\": \"test-posthog\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": null,\n",
" \"last_checked_at\": null\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": null\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/53237f83-5c4d-45e4-82f3-aa9da4bbbe00\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"8c776ad5-d2ff-4574-bd41-753dbbd35bec\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-10-01T14:18:04.872628Z\",\n",
" \"updated_at\": \"2025-10-01T14:18:04.872644Z\",\n",
" \"provider\": \"aws\",\n",
" \"uid\": \"123456789122\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": null,\n",
" \"last_checked_at\": null\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"b56191d1-328e-42ee-a0f3-1422bf3dca9f\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/8c776ad5-d2ff-4574-bd41-753dbbd35bec\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"09f9949d-e801-4865-803d-51c8ee9c70f5\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-28T06:57:15.819206Z\",\n",
" \"updated_at\": \"2025-09-25T14:33:14.763507Z\",\n",
" \"provider\": \"github\",\n",
" \"uid\": \"dTroop3r\",\n",
" \"alias\": \"GH using App\",\n",
" \"connection\": {\n",
" \"connected\": true,\n",
" \"last_checked_at\": \"2025-09-25T14:33:14.757995Z\"\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"6ade14ed-0113-4b42-955c-c0159315821a\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/09f9949d-e801-4865-803d-51c8ee9c70f5\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"d664cb20-3cc8-403d-9d62-0773c61642d7\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-28T06:48:40.344590Z\",\n",
" \"updated_at\": \"2025-08-28T09:53:07.955423Z\",\n",
" \"provider\": \"github\",\n",
" \"uid\": \"PieceOfM1nd\",\n",
" \"alias\": \"PieceOfM1nd (org)\",\n",
" \"connection\": {\n",
" \"connected\": true,\n",
" \"last_checked_at\": \"2025-08-28T09:53:07.949871Z\"\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"ca7d8494-069b-4388-9d02-3310b96c6fbd\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/d664cb20-3cc8-403d-9d62-0773c61642d7\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"00acd090-ad97-4182-91d2-f279502fb3eb\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-21T16:35:31.030729Z\",\n",
" \"updated_at\": \"2025-08-21T17:14:25.890660Z\",\n",
" \"provider\": \"aws\",\n",
" \"uid\": \"123456789111\",\n",
" \"alias\": \"Test role bug\",\n",
" \"connection\": {\n",
" \"connected\": null,\n",
" \"last_checked_at\": null\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"332bea53-6381-484d-83ed-ca1ccc52dd76\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/00acd090-ad97-4182-91d2-f279502fb3eb\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"dcf3bc9c-102c-4f47-9753-3732a70601d7\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-21T16:21:18.013721Z\",\n",
" \"updated_at\": \"2025-08-21T16:21:18.013738Z\",\n",
" \"provider\": \"aws\",\n",
" \"uid\": \"123456789012\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": null,\n",
" \"last_checked_at\": null\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": null\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/dcf3bc9c-102c-4f47-9753-3732a70601d7\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"2642ea99-cd32-463c-a7e9-8b7791f8f7e5\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-09T07:54:03.128579Z\",\n",
" \"updated_at\": \"2025-08-09T07:54:03.128594Z\",\n",
" \"provider\": \"github\",\n",
" \"uid\": \"pedrooot\",\n",
" \"alias\": null,\n",
" \"connection\": {\n",
" \"connected\": null,\n",
" \"last_checked_at\": null\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": null\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/2642ea99-cd32-463c-a7e9-8b7791f8f7e5\"\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"providers\",\n",
" \"id\": \"bc7a6295-f706-4361-855d-2352829b6668\",\n",
" \"attributes\": {\n",
" \"inserted_at\": \"2025-08-04T12:36:34.699122Z\",\n",
" \"updated_at\": \"2025-10-21T12:38:42.660182Z\",\n",
" \"provider\": \"kubernetes\",\n",
" \"uid\": \"arn:aws:eks:eu-west-1:106908755756:cluster/test\",\n",
" \"alias\": \"EKS Dev\",\n",
" \"connection\": {\n",
" \"connected\": false,\n",
" \"last_checked_at\": \"2025-10-21T12:38:42.655786Z\"\n",
" }\n",
" },\n",
" \"relationships\": {\n",
" \"secret\": {\n",
" \"data\": {\n",
" \"type\": \"provider-secrets\",\n",
" \"id\": \"52471ba2-27de-4570-a762-aee33bc3f44c\"\n",
" }\n",
" },\n",
" \"provider_groups\": {\n",
" \"meta\": {\n",
" \"count\": 0\n",
" },\n",
" \"data\": []\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/providers/bc7a6295-f706-4361-855d-2352829b6668\"\n",
" }\n",
" }\n",
" ],\n",
" \"meta\": {\n",
" \"pagination\": {\n",
" \"page\": 1,\n",
" \"pages\": 2,\n",
" \"count\": 16\n",
" },\n",
" \"version\": \"v1\"\n",
" }\n",
"}\n"
]
}
],
"source": [
"import requests\n",
"import os\n",
"import json\n",
"\n",
"prowler_api_key = os.environ.get('PROWLER_API_KEY')\n",
"\n",
"headers = {\n",
" 'Authorization': f'Api-Key {prowler_api_key}',\n",
" 'Content-Type': 'application/vnd.api+json'\n",
"}\n",
"\n",
"response = requests.get(\n",
" 'https://api.dev.prowler.com/api/v1/providers',\n",
" headers=headers\n",
")\n",
"\n",
"# Pretty-print the JSON response\n",
"print(json.dumps(response.json(), indent=2))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Get One Critical Finding from Latest Scan"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"{\n",
" \"links\": {\n",
" \"first\": \"https://api.dev.prowler.com/api/v1/findings/latest?filter%5Bseverity__in%5D=critical&page%5Bnumber%5D=1&page%5Bsize%5D=1\",\n",
" \"last\": \"https://api.dev.prowler.com/api/v1/findings/latest?filter%5Bseverity__in%5D=critical&page%5Bnumber%5D=946&page%5Bsize%5D=1\",\n",
" \"next\": \"https://api.dev.prowler.com/api/v1/findings/latest?filter%5Bseverity__in%5D=critical&page%5Bnumber%5D=2&page%5Bsize%5D=1\",\n",
" \"prev\": null\n",
" },\n",
" \"data\": [\n",
" {\n",
" \"type\": \"findings\",\n",
" \"id\": \"019a0753-1e4b-7229-bb7d-91eab8fc0f4f\",\n",
" \"attributes\": {\n",
" \"uid\": \"prowler-m365-teams_unmanaged_communication_disabled-f4dffefa-083f-4e9e-91e0-5d1e04f4b72b-global-Teams User Settings\",\n",
" \"delta\": \"new\",\n",
" \"status\": \"PASS\",\n",
" \"status_extended\": \"Teams users cannot communicate with unmanaged users.\",\n",
" \"severity\": \"critical\",\n",
" \"check_id\": \"teams_unmanaged_communication_disabled\",\n",
" \"check_metadata\": {\n",
" \"risk\": \"Allowing communication with unmanaged Microsoft Teams users increases the risk of targeted attacks such as phishing, malware distribution (e.g., DarkGate), and exploitation techniques like GIFShell and username enumeration. Unmanaged accounts are easier for threat actors to create and use as attack vectors.\",\n",
" \"notes\": \"\",\n",
" \"checkid\": \"teams_unmanaged_communication_disabled\",\n",
" \"provider\": \"m365\",\n",
" \"severity\": \"critical\",\n",
" \"checktype\": [],\n",
" \"dependson\": [],\n",
" \"relatedto\": [],\n",
" \"categories\": [\n",
" \"e3\"\n",
" ],\n",
" \"checktitle\": \"Ensure unmanaged communication is disabled.\",\n",
" \"compliance\": [],\n",
" \"relatedurl\": \"https://learn.microsoft.com/en-us/powershell/module/teams/set-cstenantfederationconfiguration?view=teams-ps\",\n",
" \"description\": \"Ensure unmanaged communication is disabled in Teams admin center.\",\n",
" \"remediation\": {\n",
" \"code\": {\n",
" \"cli\": \"Set-CsTenantFederationConfiguration -AllowTeamsConsumer $false\",\n",
" \"other\": \"1. Navigate to Microsoft Teams admin center https://admin.teams.microsoft.com/. 2. Click to expand Users select External access. 3. Scroll to Teams accounts not managed by an organization. 4. Set People in my organization can communicate with Teams users whose accounts aren't managed by an organization to Off. 5. Click Save.\",\n",
" \"nativeiac\": \"\",\n",
" \"terraform\": \"\"\n",
" },\n",
" \"recommendation\": {\n",
" \"url\": \"https://learn.microsoft.com/en-us/powershell/module/teams/set-cstenantfederationconfiguration?view=teams-ps\",\n",
" \"text\": \"Disable communication with Teams users whose accounts aren't managed by an organization by setting 'People in my organization can communicate with Teams users whose accounts aren't managed by an organization' to Off. This helps prevent unauthorized or risky external interactions.\"\n",
" }\n",
" },\n",
" \"servicename\": \"teams\",\n",
" \"checkaliases\": [],\n",
" \"resourcetype\": \"Teams Settings\",\n",
" \"additionalurls\": [],\n",
" \"subservicename\": \"\",\n",
" \"resourceidtemplate\": \"\"\n",
" },\n",
" \"raw_result\": {},\n",
" \"inserted_at\": \"2025-10-21T15:11:19.115828Z\",\n",
" \"updated_at\": \"2025-10-21T15:11:19.120405Z\",\n",
" \"first_seen_at\": \"2025-10-21T15:11:19.113770Z\",\n",
" \"muted\": false,\n",
" \"muted_reason\": null\n",
" },\n",
" \"relationships\": {\n",
" \"scan\": {\n",
" \"data\": {\n",
" \"type\": \"scans\",\n",
" \"id\": \"019a074f-e8c1-74b9-84e6-95a821f7ac30\"\n",
" }\n",
" },\n",
" \"resources\": {\n",
" \"meta\": {\n",
" \"count\": 1\n",
" },\n",
" \"data\": [\n",
" {\n",
" \"type\": \"resources\",\n",
" \"id\": \"3455f95f-f985-48c4-ac34-d22baac19aa3\"\n",
" }\n",
" ]\n",
" }\n",
" },\n",
" \"links\": {\n",
" \"self\": \"https://api.dev.prowler.com/api/v1/findings/019a0753-1e4b-7229-bb7d-91eab8fc0f4f\"\n",
" }\n",
" }\n",
" ],\n",
" \"meta\": {\n",
" \"pagination\": {\n",
" \"page\": 1,\n",
" \"pages\": 946,\n",
" \"count\": 946\n",
" },\n",
" \"version\": \"v1\"\n",
" }\n",
"}\n"
]
}
],
"source": [
"response = requests.get(\n",
" 'https://api.dev.prowler.com/api/v1/findings/latest',\n",
" headers=headers,\n",
" params={\n",
" 'filter[severity__in]': 'critical',\n",
" 'page[size]': '1'\n",
" }\n",
")\n",
"\n",
"print(json.dumps(response.json(), indent=2))"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "prowler-6nYzd6ct-py3.12",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.11"
}
},
"nbformat": 4,
"nbformat_minor": 2
}