Prowler REST SDK

Community-maintained Python SDK for the Prowler REST API.

Prowler is an open-source cloud security platform that automates security and compliance across cloud environments. This SDK wraps the Prowler App / Prowler Cloud REST API (/api/v1/*) so you can manage scans, findings, providers, and more from Python.

Note: This is an independent, community-maintained SDK. It is not affiliated with, endorsed by, or sponsored by the Prowler project or its contributors.

Legal

Community-maintained SDK

This project is independently maintained and is not affiliated with, endorsed by, or sponsored by any third-party organization, project, or its contributors.

Trademarks

Any product names, logos, or brands mentioned (including Prowler, Prowler Cloud, and Prowler App) are the property of their respective owners. Their use is solely for identification and interoperability purposes and does not imply any affiliation, sponsorship, or endorsement.

Disclaimer

This software is provided "as is", without any warranties, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement. The authors and copyright holders are not liable for any claims, damages, or other liabilities arising from the use of this software.

See also NOTICE.md.

Requirements

• Python 3.10+
• A Prowler Cloud account or self-hosted Prowler App instance
• An API key or user credentials

Installation

pip install prowler-rest-sdk

For development:

git clone <this-repo>
cd prowler-rest-sdk
pip install -e ".[dev]"

Quick start

API key authentication (recommended)

from prowler_rest_sdk import ProwlerClient

client = ProwlerClient(api_key="your-api-key")

# List completed scans
scans = client.scans.list(filters={"state": "completed"})

# Trigger a scan
task = client.scans.trigger(provider_id="your-provider-uuid", name="weekly-audit")

# Iterate all critical findings (auto-paginated)
for finding in client.findings.list_all(filters={"severity": "critical"}):
    attrs = finding["attributes"]
    print(attrs["check_id"], attrs["status"])

Email / password authentication

from prowler_rest_sdk import ProwlerClient

client = ProwlerClient.from_credentials(
    email="user@example.com",
    password="your-password",
    tenant_id="optional-tenant-uuid",
)
me = client.users.me()
print(me["data"]["attributes"]["email"])

Self-hosted Prowler App

client = ProwlerClient(
    api_key="your-api-key",
    base_url="http://localhost:8080",
)

API coverage

The SDK exposes resource-oriented accessors that map to the Prowler OpenAPI spec:

Resource	Client accessor	Description
Scans	client.scans	Trigger and manage security scans
Findings	client.findings	Query security findings
Providers	client.providers	Manage cloud provider connections
Tasks	client.tasks	Monitor async scan tasks
Users / Tenants	client.users, client.tenants	User and tenant management
Compliance	client.compliance_overviews	Compliance overview data
Overviews	client.overviews	Dashboard summaries
Integrations	client.integrations	Third-party integrations
Attack Paths	client.attack_paths_scans	Attack path graph queries
API Keys	client.api_keys	API key management

All list endpoints support JSON:API filtering, sorting, field selection, and pagination:

client.findings.list(
    filters={"severity": "high", "status": "FAIL"},
    sort=["-inserted_at"],
    page_size=25,
    include=["resource"],
)

Use list_all() to auto-paginate:

for scan in client.scans.list_all(filters={"provider_type": "aws"}):
    print(scan["id"], scan["attributes"]["state"])

Downloading reports

# Compliance CSV report
csv_bytes = client.scans.get_compliance_report(scan_id, "cis_1.4_aws")
with open("cis_report.csv", "wb") as f:
    f.write(csv_bytes)

# ThreatScore
score = client.scans.get_threatscore(scan_id)

Error handling

from prowler_rest_sdk import ProwlerClient
from prowler_rest_sdk.exceptions import (
    ProwlerAuthenticationError,
    ProwlerNotFoundError,
    ProwlerValidationError,
    ProwlerAPIError,
)

client = ProwlerClient(api_key="key")

try:
    client.scans.get("nonexistent-id")
except ProwlerNotFoundError as exc:
    print(exc.status_code, exc.errors)
except ProwlerAPIError as exc:
    print(f"API error: {exc}")

Environment variables

You can load credentials from the environment in your application code:

import os
from prowler_rest_sdk import ProwlerClient

client = ProwlerClient(
    api_key=os.environ["PROWLER_API_KEY"],
    base_url=os.environ.get("PROWLER_BASE_URL", "https://api.prowler.com"),
)

Development

pip install -e ".[dev]"
pytest
ruff check prowler_rest_sdk tests

Publishing to PyPI

Prerequisites

1. Register the package name on PyPI (first publish only).
2. Create a PyPI API token at https://pypi.org/manage/account/token/
3. For GitHub Actions, add the token as repository secret PYPI_API_TOKEN and create a pypi environment in the repo settings.

Local build and upload

pip install -e ".[dev]"
python -m build
twine check dist/*
twine upload dist/*

Set TWINE_USERNAME=__token__ and TWINE_PASSWORD=<your-pypi-api-token> when uploading.

Version bumps

The package version is read from prowler_rest_sdk/__init__.py (__version__). Bump that value before each release, then tag and publish:

git tag v0.1.0
git push origin v0.1.0

Create a GitHub Release from the tag to trigger the publish workflow, or run the Publish to PyPI workflow manually from the Actions tab.

References

• Prowler GitHub repository
• Prowler documentation
• Prowler API docs (Prowler Cloud)
• OpenAPI specification

License

MIT — see LICENSE.