{
  "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
}