fix(gcp): surface organization-scan failures instead of silently scanning the home project

[puchy22]

Context

Fix #11250

When a user runs prowler gcp --credentials-file <sa-key.json> --organization-id <org-id> and the service account is missing the IAM/API setup that the Cloud Asset Inventory API requires, Prowler silently scans only the service account's host project instead of the whole organization. The CLI prints a normal banner and a clean run with no error.

Root cause is in GcpProvider.get_projects():

1. The --organization-id branch calls cloudasset.assets.list(parent="organizations/<id>", ...). Any HttpError from that call (403 permission denied, "Cloud Asset API has not been used", quota project issues, etc.) is caught and logged at error level only — never raised.
2. With projects left empty, control falls through to a fallback at gcp_provider.py:785 that opens the credentials JSON file and substitutes project_id from it. The service account's host project becomes the entire scan scope, with no warning printed to the user.

User accounts don't hit this because, without --organization-id, Prowler takes the Cloud Resource Manager listing path, which user identities with org-wide bindings (roles/browser, roles/viewer at the org node) can satisfy.

Description

Provider:

• New exception GCPGetOrganizationProjectsError (code 3011) with a remediation message naming roles/cloudasset.viewer and the Cloud Asset API to enable.
• get_projects() now raises GCPGetOrganizationProjectsError on any HttpError from the org-scoped Cloud Asset API call, instead of swallowing it. Two variants of the message: one for "API not enabled" (with the enable link), one for any other failure (carrying the original error and the role hint).
• The credentials-file home-project fallback (elif credentials_file:) is now gated with and not organization_id. An explicit org-wide scan can no longer be silently downgraded to one project.
• The outer except Exception block now re-raises GCPBaseException so the new exception propagates to the CLI rather than getting consumed by the broad catch-all.

Docs:

• docs/user-guide/providers/gcp/organization.mdx: clarify that roles/cloudasset.viewer must be bound at the organization node (not at a project) and add the gcloud organizations add-iam-policy-binding and gcloud services enable cloudasset.googleapis.com commands.
• docs/user-guide/providers/gcp/authentication.mdx: in the Service Account section, add a note pointing to the org-scan page for the additional role + API needed when using --organization-id.

Steps to review

1. prowler/providers/gcp/gcp_provider.py:631-708 — the org-id branch now raises GCPGetOrganizationProjectsError.
2. prowler/providers/gcp/gcp_provider.py:795-798 — the credentials-file fallback is gated on not organization_id.
3. prowler/providers/gcp/gcp_provider.py:814-820 — the catch-all re-raises GCPBaseException.
4. prowler/providers/gcp/exceptions/exceptions.py — new error code 3011.
5. tests/providers/gcp/gcp_provider_test.py — two new regression tests cover the 403 (permission denied) and "API not enabled" paths. Run pytest tests/providers/gcp/gcp_provider_test.py (23 passed).
6. Reproduce the original symptom by removing roles/cloudasset.viewer from a service account and running prowler gcp --credentials-file <key.json> --organization-id <org-id>; with this PR the CLI now exits with GCPGetOrganizationProjectsError and a clear remediation message instead of silently scanning the host project.

Checklist

Community Checklist

• This feature/issue is listed in here
• Is it assigned to me

• Review if the code is being covered by tests.
• Review if code is being documented following this specification https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
• Review if backport is needed.
• Review if is needed to change the Readme.md
• Ensure new entries are added to CHANGELOG.md, if applicable.

SDK/CLI

• Are there new checks included in this PR? No
  • No new permissions required for the provider. The change documents an existing requirement (roles/cloudasset.viewer + Cloud Asset API enablement) that was previously needed but silently masked.

License

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[github-actions]

✅ All necessary CHANGELOG.md files have been updated.

[github-actions]

✅ Conflict Markers Resolved

All conflict markers have been successfully resolved in this pull request.

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.37%. Comparing base (c660b35) to head (e0424a4).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #11280      +/-   ##
==========================================
- Coverage   93.97%   93.37%   -0.60%     
==========================================
  Files         237      141      -96     
  Lines       34829     3458   -31371     
==========================================
- Hits        32729     3229   -29500     
+ Misses       2100      229    -1871     

Flag	Coverage Δ
api	?
prowler-py3.10-gcp	93.37% <85.71%> (?)
prowler-py3.11-gcp	93.37% <85.71%> (?)
prowler-py3.12-gcp	93.37% <85.71%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
prowler	93.37% <85.71%> (∅)
api	∅ <ø> (∅)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🔒 Container Security Scan

Image: prowler:5cb6abb
Last scan: 2026-05-21 09:35:56 UTC

📊 Vulnerability Summary

Severity	Count
🔴 Critical	6
Total	6

5 package(s) affected

⚠️ Action Required

Critical severity vulnerabilities detected. These should be addressed before merging:

• Review the detailed scan results
• Update affected packages to patched versions
• Consider using a different base image if updates are unavailable

---

📋 Resources:

• Download full report (see artifacts)
• View in Security tab
• Scanned with Trivy