{ "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=\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": 1, "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": 2, "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=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": [ "import requests\n", "import os\n", "import json\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": 3, "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=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": [ "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 }