chore(vercel): add disclaimer for checks depending on billing plan (#10663)

Author: danibarranqueroo

docs/developer-guide/check-metadata-guidelines.mdx

@@ -215,3 +215,6 @@ Also is important to keep all code examples as short as possible, including the
 | e5                      | M365 and Azure Entra checks enabled by or dependent on an E5 license (e.g., advanced threat protection, audit, DLP, and eDiscovery)                                                                    |
 | privilege-escalation    | Detects IAM policies or permissions that allow identities to elevate their privileges beyond their intended scope, potentially gaining administrator or higher-level access through specific action combinations |
 | ec2-imdsv1              | Identifies EC2 instances using Instance Metadata Service version 1 (IMDSv1), which is vulnerable to SSRF attacks and should be replaced with IMDSv2 for enhanced security                        |
+| vercel-hobby-plan       | Vercel checks whose audited feature is available on the Hobby plan (and therefore also on Pro and Enterprise plans)                                                                                   |
+| vercel-pro-plan         | Vercel checks whose audited feature requires a Pro plan or higher, including features also available on Enterprise or via supported paid add-ons for Pro plans                                        |
+| vercel-enterprise-plan  | Vercel checks whose audited feature requires the Enterprise plan                                                                                                                                    |

docs/developer-guide/checks.mdx

@@ -387,7 +387,7 @@ Provides both code examples and best practice recommendations for addressing the
 
 #### Categories
 
-One or more functional groupings used for execution filtering (e.g., `internet-exposed`). You can define new categories just by adding to this field.
+One or more functional groupings used for execution filtering (e.g., `internet-exposed`). Categories must match the predefined values enforced by `CheckMetadata`; adding a new category requires updating the validator and the metadata documentation.
 
 For the complete list of available categories, see [Categories Guidelines](/developer-guide/check-metadata-guidelines#categories-guidelines).
 

docs/user-guide/providers/vercel/getting-started-vercel.mdx

@@ -160,3 +160,25 @@ Prowler for Vercel includes security checks across the following services:
 | **Project** | Deployment protection, environment variable security, fork protection, and skew protection |
 | **Security** | Web Application Firewall (WAF), rate limiting, IP blocking, and managed rulesets |
 | **Team** | SSO enforcement, directory sync, member access, and invitation hygiene |
+
+## Checks With Explicit Plan-Based Behavior
+
+Prowler currently includes 26 Vercel checks. The 11 checks below have explicit billing-plan handling in the provider metadata or check logic. When the scanned scope reports a billing plan, Prowler adds plan-aware context to findings for these checks. If the API does not expose the required configuration, Prowler may return `MANUAL` and require verification in the Vercel dashboard.
+
+| Check ID | Hobby | Pro | Enterprise | Notes |
+|----------|-------|-----|------------|-------|
+| `project_password_protection_enabled` | Not available | Available as a paid add-on | Available | Checks password protection for deployments |
+| `project_production_deployment_protection_enabled` | Not available | Available with supported paid deployment protection options | Available | Checks protection for production deployments |
+| `project_skew_protection_enabled` | Not available | Available | Available | Checks skew protection during rollouts |
+| `security_custom_rules_configured` | Not available | Available | Available | Returns `MANUAL` when the firewall configuration cannot be assessed from the API |
+| `security_ip_blocking_rules_configured` | Not available | Available | Available | Returns `MANUAL` when the firewall configuration cannot be assessed from the API |
+| `team_saml_sso_enabled` | Not available | Available | Available | Checks team SAML SSO configuration |
+| `team_saml_sso_enforced` | Not available | Available | Available | Checks SAML SSO enforcement for all team members |
+| `team_directory_sync_enabled` | Not available | Not available | Available | Checks SCIM directory sync |
+| `security_managed_rulesets_enabled` | Bot Protection and AI Bots managed rulesets | Bot Protection and AI Bots managed rulesets | All managed rulesets, including OWASP Core Ruleset | Returns `MANUAL` when the firewall configuration cannot be assessed from the API |
+| `security_rate_limiting_configured` | Not available | Available | Available | Returns `MANUAL` when the firewall configuration cannot be assessed from the API |
+| `security_waf_enabled` | Not available | Available | Available | Returns `MANUAL` when the firewall configuration cannot be assessed from the API |
+
+<Note>
+The five firewall-related checks (`security_waf_enabled`, `security_custom_rules_configured`, `security_ip_blocking_rules_configured`, `security_rate_limiting_configured`, and `security_managed_rulesets_enabled`) return `MANUAL` when the firewall configuration endpoint is not accessible from the API. The other 15 current Vercel checks do not currently include plan-specific handling in provider logic, but every Vercel check includes exactly one billing-plan metadata category (`vercel-hobby-plan`, `vercel-pro-plan`, or `vercel-enterprise-plan`) alongside its functional security category.
+</Note>

prowler/CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to the **Prowler SDK** are documented in this file.
 - `bedrock_guardrails_configured` check for AWS provider [(#10844)](https://github.com/prowler-cloud/prowler/pull/10844)
 - Universal compliance pipeline integrated into the CLI: `--list-compliance` and `--list-compliance-requirements` show universal frameworks, and CSV plus OCSF outputs are generated for any framework declaring a `TableConfig` [(#10301)](https://github.com/prowler-cloud/prowler/pull/10301)
 - ASD Essential Eight Maturity Model compliance framework for AWS (Maturity Level One, Nov 2023) [(#10808)](https://github.com/prowler-cloud/prowler/pull/10808)
+- Update Vercel checks to return personalized finding status extended depending on billing plan and classify them with billing-plan categories [(#10663)](https://github.com/prowler-cloud/prowler/pull/10663)
 
 ### 🔄 Changed
 

prowler/lib/check/models.py

@@ -62,6 +62,9 @@
         "e5",
         "privilege-escalation",
         "ec2-imdsv1",
+        "vercel-hobby-plan",
+        "vercel-pro-plan",
+        "vercel-enterprise-plan",
     }
 )
 
@@ -244,14 +247,15 @@ class CheckMetadata(BaseModel):
     # store the compliance later if supplied
     Compliance: Optional[list[Any]] = Field(default_factory=list)
 
+    # TODO: Remove noqa and fix cls vulture errors
     @validator("Categories", each_item=True, pre=True, always=True)
-    def valid_category(cls, value, values):
+    def valid_category(cls, value, values):  # noqa: F841
         if not isinstance(value, str):
             raise ValueError("Categories must be a list of strings")
         value_lower = value.lower()
         if not re.match("^[a-z0-9-]+$", value_lower):
             raise ValueError(
-                f"Invalid category: {value}. Categories can only contain lowercase letters, numbers and hyphen '-'"
+                f"Invalid category: {value}. Categories can only contain lowercase letters, numbers, and hyphen '-'"
             )
         if (
             value_lower not in VALID_CATEGORIES
@@ -279,7 +283,7 @@ def valid_resource_type(resource_type):
         return resource_type
 
     @validator("ServiceName", pre=True, always=True)
-    def validate_service_name(cls, service_name, values):
+    def validate_service_name(cls, service_name, values):  # noqa: F841
         if not service_name:
             raise ValueError("ServiceName must be a non-empty string")
 
@@ -296,7 +300,7 @@ def validate_service_name(cls, service_name, values):
         return service_name
 
     @validator("CheckID", pre=True, always=True)
-    def valid_check_id(cls, check_id, values):
+    def valid_check_id(cls, check_id, values):  # noqa: F841
         if not check_id:
             raise ValueError("CheckID must be a non-empty string")
 
@@ -309,7 +313,7 @@ def valid_check_id(cls, check_id, values):
         return check_id
 
     @validator("CheckTitle", pre=True, always=True)
-    def validate_check_title(cls, check_title, values):
+    def validate_check_title(cls, check_title, values):  # noqa: F841
         if values.get("Provider") not in EXTERNAL_TOOL_PROVIDERS:
             if len(check_title) > 150:
                 raise ValueError(
@@ -322,13 +326,13 @@ def validate_check_title(cls, check_title, values):
         return check_title
 
     @validator("RelatedUrl", pre=True, always=True)
-    def validate_related_url(cls, related_url, values):
+    def validate_related_url(cls, related_url, values):  # noqa: F841
         if related_url and values.get("Provider") not in EXTERNAL_TOOL_PROVIDERS:
             raise ValueError("RelatedUrl must be empty. This field is deprecated.")
         return related_url
 
     @validator("Remediation")
-    def validate_recommendation_url(cls, remediation, values):
+    def validate_recommendation_url(cls, remediation, values):  # noqa: F841
         if values.get("Provider") not in EXTERNAL_TOOL_PROVIDERS:
             url = remediation.Recommendation.Url
             if url and not url.startswith("https://hub.prowler.com/"):
@@ -338,7 +342,7 @@ def validate_recommendation_url(cls, remediation, values):
         return remediation
 
     @validator("CheckType", pre=True, always=True)
-    def validate_check_type(cls, check_type, values):
+    def validate_check_type(cls, check_type, values):  # noqa: F841
         provider = values.get("Provider", "").lower()
 
         # Non-AWS providers must have an empty CheckType list
@@ -367,7 +371,7 @@ def validate_check_type(cls, check_type, values):
         return check_type
 
     @validator("Description", pre=True, always=True)
-    def validate_description(cls, description, values):
+    def validate_description(cls, description, values):  # noqa: F841
         if values.get("Provider") not in EXTERNAL_TOOL_PROVIDERS:
             if len(description) > 400:
                 raise ValueError(
@@ -376,7 +380,7 @@ def validate_description(cls, description, values):
         return description
 
     @validator("Risk", pre=True, always=True)
-    def validate_risk(cls, risk, values):
+    def validate_risk(cls, risk, values):  # noqa: F841
         if values.get("Provider") not in EXTERNAL_TOOL_PROVIDERS:
             if len(risk) > 400:
                 raise ValueError(
@@ -385,15 +389,15 @@ def validate_risk(cls, risk, values):
         return risk
 
     @validator("ResourceGroup", pre=True, always=True)
-    def validate_resource_group(cls, resource_group):
+    def validate_resource_group(cls, resource_group):  # noqa: F841
         if resource_group and resource_group not in VALID_RESOURCE_GROUPS:
             raise ValueError(
                 f"Invalid ResourceGroup: '{resource_group}'. Must be one of: {', '.join(sorted(VALID_RESOURCE_GROUPS))} or empty string."
             )
         return resource_group
 
     @validator("AdditionalURLs", pre=True, always=True)
-    def validate_additional_urls(cls, additional_urls):
+    def validate_additional_urls(cls, additional_urls):  # noqa: F841
         if not isinstance(additional_urls, list):
             raise ValueError("AdditionalURLs must be a list")
 

prowler/providers/vercel/lib/billing.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+
+def extract_billing_plan(data: Optional[dict]) -> Optional[str]:
+    """Return the Vercel billing plan from a user or team payload.
+
+    Vercel's REST API consistently returns the plan identifier at
+    ``data["billing"]["plan"]`` (e.g. ``"hobby"``, ``"pro"``, ``"enterprise"``)
+    on both ``GET /v2/user`` and ``GET /v2/teams`` responses, even though the
+    field is not part of the public OpenAPI schema.
+    """
+    if not isinstance(data, dict):
+        return None
+    billing = data.get("billing")
+    if not isinstance(billing, dict):
+        return None
+    plan = billing.get("plan")
+    return plan.lower() if isinstance(plan, str) else None
+
+
+def plan_reason_suffix(
+    billing_plan: Optional[str], unsupported_plans: set[str], explanation: str
+) -> str:
+    """Return a plan-based explanation suffix only when the plan proves it."""
+    if billing_plan in unsupported_plans:
+        return f" This may be expected because {explanation}"
+    return ""

prowler/providers/vercel/lib/service/service.py

@@ -84,10 +84,10 @@ def _get(self, path: str, params: dict = None) -> dict:
                     )
 
                 if response.status_code == 403:
-                    # Plan limitation or permission error — return None for graceful handling
-                    logger.warning(
+                    # Endpoint unavailable for this token/scope; let checks handle it gracefully
+                    logger.info(
                         f"{self.service} - Access denied for {path} (403). "
-                        "This may be a plan limitation."
+                        "This may be caused by plan or permission restrictions."
                     )
                     return None
 

prowler/providers/vercel/models.py

@@ -21,6 +21,7 @@ class VercelTeamInfo(BaseModel):
     id: str
     name: str
     slug: str
+    billing_plan: Optional[str] = None
 
 
 class VercelIdentityInfo(BaseModel):
@@ -29,9 +30,27 @@ class VercelIdentityInfo(BaseModel):
     user_id: Optional[str] = None
     username: Optional[str] = None
     email: Optional[str] = None
+    billing_plan: Optional[str] = None
     team: Optional[VercelTeamInfo] = None
     teams: list[VercelTeamInfo] = Field(default_factory=list)
 
+    def get_billing_plan_for(self, scope_id: Optional[str]) -> Optional[str]:
+        """Return the billing plan for an explicit user or team scope."""
+        if not scope_id:
+            return None
+
+        if self.team and self.team.id == scope_id and self.team.billing_plan:
+            return self.team.billing_plan
+
+        for team in self.teams:
+            if team.id == scope_id:
+                return team.billing_plan
+
+        if self.user_id == scope_id:
+            return self.billing_plan
+
+        return None
+
 
 class VercelOutputOptions(ProviderOutputOptions):
     """Customize output filenames for Vercel scans."""

prowler/providers/vercel/services/authentication/authentication_no_stale_tokens/authentication_no_stale_tokens.metadata.json

@@ -28,7 +28,8 @@
     }
   },
   "Categories": [
-    "trust-boundaries"
+    "trust-boundaries",
+    "vercel-hobby-plan"
   ],
   "DependsOn": [],
   "RelatedTo": [

prowler/providers/vercel/services/authentication/authentication_token_not_expired/authentication_token_not_expired.metadata.json

@@ -28,7 +28,8 @@
     }
   },
   "Categories": [
-    "trust-boundaries"
+    "trust-boundaries",
+    "vercel-hobby-plan"
   ],
   "DependsOn": [],
   "RelatedTo": [