{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "cell-0",
      "metadata": {},
      "source": [
        "# Prowler API Examples"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "cell-1",
      "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",
      "id": "cell-2",
      "metadata": {},
      "source": [
        "## 2. Set the API Key\n",
        "\n",
        "Create a `.envrc` file in this directory with your API key:\n",
        "```bash\n",
        "export PROWLER_API_KEY=your-api-key-here\n",
        "```\n",
        "\n",
        "Then load the environment variable:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 1,
      "id": "cell-3",
      "metadata": {},
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "API key loaded from .envrc file\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "source .envrc\n",
        "echo \"API key loaded from .envrc file\""
      ]
    },
    {
      "cell_type": "markdown",
      "id": "cell-4",
      "metadata": {},
      "source": [
        "## 3. Use the API Key"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "cell-5",
      "metadata": {},
      "source": [
        "### List Providers"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "id": "cell-6",
      "metadata": {},
      "outputs": [
        {
          "name": "stderr",
          "output_type": "stream",
          "text": [
            "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
            "                                 Dload  Upload   Total   Spent    Left  Speed\n",
            "100  1398  100  1398    0     0   2723      0 --:--:-- --:--:-- --:--:--  2719\n"
          ]
        },
        {
          "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=1\",\n",
            "    \"next\": null,\n",
            "    \"prev\": null\n",
            "  },\n",
            "  \"data\": [\n",
            "    {\n",
            "      \"type\": \"providers\",\n",
            "      \"id\": \"46a9435b-a2f6-44ee-b267-710f8a403ace\",\n",
            "      \"attributes\": {\n",
            "        \"inserted_at\": \"2025-10-22T07:46:12.089159Z\",\n",
            "        \"updated_at\": \"2025-10-22T08:00:04.923849Z\",\n",
            "        \"provider\": \"aws\",\n",
            "        \"uid\": \"552455647653\",\n",
            "        \"alias\": \"Prowler Demo\",\n",
            "        \"connection\": {\n",
            "          \"connected\": true,\n",
            "          \"last_checked_at\": \"2025-10-22T08:00:04.918455Z\"\n",
            "        }\n",
            "      },\n",
            "      \"relationships\": {\n",
            "        \"secret\": {\n",
            "          \"data\": {\n",
            "            \"type\": \"provider-secrets\",\n",
            "            \"id\": \"49fafccd-348f-47c1-9147-3494903290ff\"\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/46a9435b-a2f6-44ee-b267-710f8a403ace\"\n",
            "      }\n",
            "    },\n",
            "    {\n",
            "      \"type\": \"providers\",\n",
            "      \"id\": \"9e499bb1-03fd-4588-b58a-75ef71334040\",\n",
            "      \"attributes\": {\n",
            "        \"inserted_at\": \"2025-10-22T07:42:53.856378Z\",\n",
            "        \"updated_at\": \"2025-10-22T07:46:15.197305Z\",\n",
            "        \"provider\": \"github\",\n",
            "        \"uid\": \"PieceOfM1nd\",\n",
            "        \"alias\": \"PieceOfM1nd (org)\",\n",
            "        \"connection\": {\n",
            "          \"connected\": true,\n",
            "          \"last_checked_at\": \"2025-10-22T07:46:15.191930Z\"\n",
            "        }\n",
            "      },\n",
            "      \"relationships\": {\n",
            "        \"secret\": {\n",
            "          \"data\": {\n",
            "            \"type\": \"provider-secrets\",\n",
            "            \"id\": \"3aa2c451-34e3-48c4-a0d6-db532181c892\"\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/9e499bb1-03fd-4588-b58a-75ef71334040\"\n",
            "      }\n",
            "    }\n",
            "  ],\n",
            "  \"meta\": {\n",
            "    \"pagination\": {\n",
            "      \"page\": 1,\n",
            "      \"pages\": 1,\n",
            "      \"count\": 2\n",
            "    },\n",
            "    \"version\": \"v1\"\n",
            "  }\n",
            "}\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "source .envrc\n",
        "\n",
        "curl -X GET 'https://api.dev.prowler.com/api/v1/providers' \\\n",
        "  -H \"Authorization: Api-Key ${PROWLER_API_KEY}\" \\\n",
        "  -H 'Content-Type: application/vnd.api+json' \\\n",
        "  | jq ."
      ]
    },
    {
      "cell_type": "markdown",
      "id": "flvlv96i2r7",
      "metadata": {},
      "source": [
        "### Get One Critical Finding from Latest Scan"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "id": "xkmbmm7rywb",
      "metadata": {},
      "outputs": [
        {
          "name": "stderr",
          "output_type": "stream",
          "text": [
            "  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current\n",
            "                                 Dload  Upload   Total   Spent    Left  Speed\n",
            "100  2465  100  2465    0     0   4558      0 --:--:-- --:--:-- --:--:--  4556\n"
          ]
        },
        {
          "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=138&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\": \"019a0af5-e65a-7735-8223-e9aa5ab4c58e\",\n",
            "      \"attributes\": {\n",
            "        \"uid\": \"prowler-aws-ssm_document_secrets-552455647653-us-east-1-SSM-SessionManagerRunShell\",\n",
            "        \"delta\": \"new\",\n",
            "        \"status\": \"PASS\",\n",
            "        \"status_extended\": \"No secrets found in SSM Document SSM-SessionManagerRunShell.\",\n",
            "        \"severity\": \"critical\",\n",
            "        \"check_id\": \"ssm_document_secrets\",\n",
            "        \"check_metadata\": {\n",
            "          \"risk\": \"Secrets hardcoded into SSM Documents by malware and bad actors to gain lateral access to other services.\",\n",
            "          \"notes\": \"\",\n",
            "          \"checkid\": \"ssm_document_secrets\",\n",
            "          \"provider\": \"aws\",\n",
            "          \"severity\": \"critical\",\n",
            "          \"checktype\": [],\n",
            "          \"dependson\": [],\n",
            "          \"relatedto\": [],\n",
            "          \"categories\": [\n",
            "            \"secrets\"\n",
            "          ],\n",
            "          \"checktitle\": \"Find secrets in SSM Documents.\",\n",
            "          \"compliance\": [],\n",
            "          \"relatedurl\": \"https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-secretsmanager-secret-generatesecretstring.html\",\n",
            "          \"description\": \"Find secrets in SSM Documents.\",\n",
            "          \"remediation\": {\n",
            "            \"code\": {\n",
            "              \"cli\": \"\",\n",
            "              \"other\": \"\",\n",
            "              \"nativeiac\": \"\",\n",
            "              \"terraform\": \"\"\n",
            "            },\n",
            "            \"recommendation\": {\n",
            "              \"url\": \"https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-secretsmanager-secret-generatesecretstring.html\",\n",
            "              \"text\": \"Implement automated detective control (e.g. using tools like Prowler) to scan accounts for passwords and secrets. Use Secrets Manager service to store and retrieve passwords and secrets.\"\n",
            "            }\n",
            "          },\n",
            "          \"servicename\": \"ssm\",\n",
            "          \"checkaliases\": [],\n",
            "          \"resourcetype\": \"AwsSsmDocument\",\n",
            "          \"additionalurls\": [],\n",
            "          \"subservicename\": \"\",\n",
            "          \"resourceidtemplate\": \"arn:aws:ssm:region:account-id:document/document-name\"\n",
            "        },\n",
            "        \"raw_result\": {},\n",
            "        \"inserted_at\": \"2025-10-22T08:07:58.811165Z\",\n",
            "        \"updated_at\": \"2025-10-22T08:07:58.818764Z\",\n",
            "        \"first_seen_at\": \"2025-10-22T08:07:58.808707Z\",\n",
            "        \"muted\": false,\n",
            "        \"muted_reason\": null\n",
            "      },\n",
            "      \"relationships\": {\n",
            "        \"scan\": {\n",
            "          \"data\": {\n",
            "            \"type\": \"scans\",\n",
            "            \"id\": \"019a0aec-edbc-7815-8476-b4efb7a4059a\"\n",
            "          }\n",
            "        },\n",
            "        \"resources\": {\n",
            "          \"meta\": {\n",
            "            \"count\": 1\n",
            "          },\n",
            "          \"data\": [\n",
            "            {\n",
            "              \"type\": \"resources\",\n",
            "              \"id\": \"f1f89f3d-22f8-43f6-a912-4edb23a7522a\"\n",
            "            }\n",
            "          ]\n",
            "        }\n",
            "      },\n",
            "      \"links\": {\n",
            "        \"self\": \"https://api.dev.prowler.com/api/v1/findings/019a0af5-e65a-7735-8223-e9aa5ab4c58e\"\n",
            "      }\n",
            "    }\n",
            "  ],\n",
            "  \"meta\": {\n",
            "    \"pagination\": {\n",
            "      \"page\": 1,\n",
            "      \"pages\": 138,\n",
            "      \"count\": 138\n",
            "    },\n",
            "    \"version\": \"v1\"\n",
            "  }\n",
            "}\n"
          ]
        }
      ],
      "source": [
        "%%bash\n",
        "source .envrc\n",
        "\n",
        "curl -X GET 'https://api.dev.prowler.com/api/v1/findings/latest?filter%5Bseverity__in%5D=critical&page%5Bsize%5D=1' \\\n",
        "  -H \"Authorization: Api-Key ${PROWLER_API_KEY}\" \\\n",
        "  -H 'Content-Type: application/vnd.api+json' \\\n",
        "  | jq ."
      ]
    }
  ],
  "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": 5
}