Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(gcp): improve docstrings #5716

Merged
merged 4 commits into from
Nov 18, 2024
Merged

docs(gcp): improve docstrings #5716

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
355ee36
feat(gcp): improve docstings
pedrooot Nov 11, 2024
fcba8af
feat(gcp): improve docstrings
pedrooot Nov 12, 2024
a597fa0
docs(gcp): resolve comments
pedrooot Nov 18, 2024
5d025e3
docs(gcp): resolve comments
pedrooot Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 148 additions & 0 deletions prowler/providers/gcp/gcp_provider.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,31 @@


class GcpProvider(Provider):
"""
GCP Provider class to handle the GCP provider

Attributes:
- _type: str -> The provider type
- _session: Credentials -> The GCP credentials session
- _project_ids: list -> The list of project IDs
- _excluded_project_ids: list -> The list of excluded project IDs
- _identity: GCPIdentityInfo -> The GCP identity info
- _audit_config: dict -> The audit config
- _mutelist: GCPMutelist -> The GCP mutelist
- audit_metadata: Audit_Metadata -> The audit metadata

Methods:
- __init__ -> GCP Provider
- setup_session -> Setup the GCP session
- test_connection -> Test the connection to GCP
- print_credentials -> Print the GCP credentials
- get_projects -> Get the projects accessible by the provided credentials
- update_projects_with_organizations -> Update the projects with organizations
- is_project_matching -> Check if the input project matches the project to match
- validate_static_arguments -> Validate the static arguments
- validate_project_id -> Validate the provider ID
"""

_type: str = "gcp"
_session: Credentials
_project_ids: list
Expand Down Expand Up @@ -81,6 +106,56 @@
client_id: str
client_secret: str
refresh_token: str

Raises:
GCPNoAccesibleProjectsError if no project IDs can be accessed via Google Credentials
GCPSetUpSessionError if an error occurs during the setup session
GCPLoadCredentialsFromDictError if an error occurs during the loading credentials from dict
GCPGetProjectError if an error occurs during the get project

Returns:
None

Usage:
- Authentication: Prowler will use by default your User Account credentials, you can configure it using:
- Using the gcloud command:
- gcloud init to use a new account
- gcloud config set account <account> to use a specific account
- gcloud auth application-default login to use the Application Default Credentials
- Prowler will use the Application Default Credentials if no credentials are provided
- Using static credentials:
- Using the client_id, client_secret and refresh_token:
>>> GcpProvider(
... client_id="client_id",
... client_secret="client_secret",
... refresh_token="refresh_token"
... )
- Using a credentials file:
>>> GcpProvider(
... credentials_file="credentials_file"
... )
- Impersonating a service account: If you want to impersonate a GCP service account, you can use the impersonate_service_account parameter. For this method user must be authenticated:
>>> GcpProvider(
... impersonate_service_account="service_account"
... )
- Projects: The GCP provider supports multi-project, which means that is capable of scan all the Google Cloud projects the user has access to.
- If you want to scan a specific project(s), you can use the project-ids argument.
>>> GcpProvider(
... project_ids=["project_id1", "project_id2"]
... )
- If you want to exclude a specific project(s), you can use the excluded-project-ids argument.
>>> GcpProvider(
... excluded_project_ids=["project_id1", "project_id2"]
... )
* Note: You can use asterisk * to exclude projects that match a pattern. For example, using "sys*" will exclude all the projects that start with sys.
- If you want to list all the available project IDs, you can use the list-project-ids argument.
>>> GcpProvider(
... list_project_ids=True
... )
- Organizations: If you want to scan a specific organization, you can use the organization-id argument. With this argument, Prowler will scan all the projects under that organization.
>>> GcpProvider(
... organization_id="organization_id"
... )
"""
logger.info("Instantiating GCP Provider ...")
self._impersonated_service_account = impersonate_service_account
Expand Down Expand Up @@ -233,11 +308,21 @@
) -> tuple:
"""
Setup the GCP session with the provided credentials file or service account to impersonate

Args:
credentials_file: str
service_account: str

Returns:
Credentials object and default project ID

Raises:
GCPLoadCredentialsFromDictError if an error occurs during the loading credentials from dict
GCPSetUpSessionError if an error occurs during the setup session

Usage:
>>> GcpProvider.setup_session(credentials_file, service_account)
>>> GcpProvider.setup_session(service_account, gcp_credentials)
"""
try:
scopes = ["https://www.googleapis.com/auth/cloud-platform"]
Expand Down Expand Up @@ -305,6 +390,7 @@
If the connection is successful, return a Connection object with is_connected set to True. If the connection fails, return a Connection object with error set to the exception.
Raise an exception if raise_on_exception is set to True.
If the Cloud Resource Manager API has not been used before or it is disabled, log a critical message and return a Connection object with error set to the exception.

Args:
credentials_file: str
service_account: str
Expand All @@ -313,8 +399,35 @@
client_secret: str
refresh_token: str
provider_id: Optional[str] -> The provider ID, for GCP it is the project ID

Returns:
Connection object with is_connected set to True if the connection is successful, or error set to the exception if the connection fails

Raises:
GCPLoadCredentialsFromDictError if an error occurs during the loading credentials from dict
GCPSetUpSessionError if an error occurs during the setup session
GCPCloudResourceManagerAPINotUsedError if the Cloud Resource Manager API has not been used before or it is disabled
GCPInvalidProviderIdError if the provider ID does not match with the expected project_id
GCPTestConnectionError if an error occurs during the test connection

Usage:
- Using static credentials:
>>> GcpProvider.test_connection(
... client_id="client_id",
... client_secret="client_secret",
... refresh_token="refresh_token"
... )
- Using a credentials file:
>>> GcpProvider.test_connection(
... credentials_file="credentials_file"
... )
- Using a service account to impersonate, authentication is required to impersonate a service account:
>>> GcpProvider.test_connection(
... client_id="client_id",
... client_secret="client_secret",
... refresh_token="refresh_token",
... service_account="service_account"
... )
"""
try:
# Set the GCP credentials using the provided client_id, client_secret and refresh_token
Expand Down Expand Up @@ -415,11 +528,22 @@
) -> dict[str, GCPProject]:
"""
Get the projects accessible by the provided credentials. If an organization ID is provided, only the projects under that organization are returned.

Args:
credentials: Credentials
organization_id: str

Returns:
dict[str, GCPProject]

Raises:
GCPCloudResourceManagerAPINotUsedError if the Cloud Resource Manager API has not been used before or it is disabled
GCPCloudAssetAPINotUsedError if the Cloud Asset API has not been used before or it is disabled
GCPHTTPError if an error occurs during the HTTP request
GCPGetProjectError if an error occurs during the get project

Usage:
>>> GcpProvider.get_projects(credentials=credentials, organization_id=organization_id)
"""
try:
projects = {}
Expand Down Expand Up @@ -535,6 +659,19 @@
return projects

def update_projects_with_organizations(self):
"""
Update the projects with organizations

Check warning on line 663 in prowler/providers/gcp/gcp_provider.py

View check run for this annotation

Codecov / codecov/patch

prowler/providers/gcp/gcp_provider.py#L663 

Added line #L663 was not covered by tests

Returns:

Check warning on line 665 in prowler/providers/gcp/gcp_provider.py

View check run for this annotation

Codecov / codecov/patch

prowler/providers/gcp/gcp_provider.py#L665 

Added line #L665 was not covered by tests
None

Raises:
GCPHTTPError if an error occurs during the HTTP request
GCPGetProjectError if an error occurs during the get project

Usage:
>>> GcpProvider.update_projects_with_organizations()
"""
try:
service = discovery.build(
"cloudresourcemanager", "v1", credentials=self._session
Expand Down Expand Up @@ -571,11 +708,16 @@
def is_project_matching(self, input_project: str, project_to_match: str) -> bool:
"""
Check if the input project matches the project to match

Args:
input_project: str
project_to_match: str

Returns:
bool

Usage:
>>> GcpProvider.is_project_matching(input_project, project_to_match)
"""
return (
"*" in input_project
Expand All @@ -602,6 +744,9 @@

Raises:
GCPStaticCredentialsError if any of the static arguments is missing

Usage:
>>> GcpProvider.validate_static_arguments(client_id, client_secret, refresh_token)
"""

if not client_id or not client_secret or not refresh_token:
Expand Down Expand Up @@ -631,6 +776,9 @@

Raises:
GCPInvalidProviderIdError if the provider ID does not match with the expected project_id

Usage:
>>> GcpProvider.validate_project_id(provider_id, credentials)
"""

available_projects = list(
Expand Down