Creating a New Integration¶

Introduction¶

Integrating Prowler with external tools enhances its functionality and enables seamless workflow automation. Prowler supports a variety of integrations to optimize security assessments and reporting.

Supported Integration Targets¶

Messaging Platforms – Example: Slack
Project Management Tools – Example: Jira
Cloud Services – Example: AWS Security Hub

Integration Guidelines¶

To integrate Prowler with a specific product:

Refer to the Prowler Developer Guide to understand its architecture and integration mechanisms.

Identify the most suitable integration method for the intended platform.

Steps to Create an Integration¶

Defining the Integration Purpose¶

Before implementing an integration, clearly define its objective. Common purposes include:
- Sending Prowler findings to a platform for alerting, tracking, or further analysis.
- For inspiration and implementation examples, please review the existing integrations in the prowler/lib/outputs folder.

Developing the Integration¶

Script Development:
- Write a script to process Prowler’s output and interact with the target platform’s API.
- If the goal is to send findings, parse Prowler’s results and use the platform’s API to create entries or notifications.
Configuration:
- Ensure the script supports environment-specific settings, such as:
  - API endpoints
  - Authentication tokens
  - Any necessary configurable parameters.

Fundamental Structure¶

Integration Class:

To implement an integration, create a class that encapsulates the required attributes and methods for interacting with the target platform. Example: Jira Integration

Jira Class

class Jira:
"""
Jira class to interact with the Jira API

[Note]
This integration is limited to a single Jira Cloud instance, meaning all issues will be created under the same Jira Cloud ID. Future improvements will include the ability to specify a Jira Cloud ID for users associated with multiple accounts.

Attributes
    - _redirect_uri: The redirect URI used
    - _client_id: The client identifier
    - _client_secret: The client secret
    - _access_token: The access token
    - _refresh_token: The refresh token
    - _expiration_date: The authentication expiration
    - _cloud_id: The cloud identifier
    - _scopes: The scopes needed to authenticate, read:jira-user read:jira-work write:jira-work
    - AUTH_URL: The URL to authenticate with Jira
    - PARAMS_TEMPLATE: The template for the parameters to authenticate with Jira
    - TOKEN_URL: The URL to get the access token from Jira
    - API_TOKEN_URL: The URL to get the accessible resources from Jira

Methods
    __init__: Initializes the Jira object
    - input_authorization_code: Inputs the authorization code
    - auth_code_url: Generates the URL to authorize the application
    - get_auth: Gets the access token and refreshes it
    - get_cloud_id: Gets the cloud identifier from Jira
    - get_access_token: Gets the access token
    - refresh_access_token: Refreshes the access token from Jira
    - test_connection: Tests the connection to Jira and returns a Connection object
    - get_projects: Gets the projects from Jira
    - get_available_issue_types: Gets the available issue types for a project
    - send_findings: Sends the findings to Jira and creates an issue

Raises:
    - JiraGetAuthResponseError: Failed to get the access token and refresh token
    - JiraGetCloudIDNoResourcesError: No resources were found in Jira when getting the cloud id
    - JiraGetCloudIDResponseError: Failed to get the cloud ID, response code did not match 200
    - JiraGetCloudIDError: Failed to get the cloud ID from Jira
    - JiraAuthenticationError: Failed to authenticate
    - JiraRefreshTokenError: Failed to refresh the access token
    - JiraRefreshTokenResponseError: Failed to refresh the access token, response code did not match 200
    - JiraGetAccessTokenError: Failed to get the access token
    - JiraNoProjectsError: No projects found in Jira
    - JiraGetProjectsError: Failed to get projects from Jira
    - JiraGetProjectsResponseError: Failed to get projects from Jira, response code did not match 200
    - JiraInvalidIssueTypeError: The issue type is invalid
    - JiraGetAvailableIssueTypesError: Failed to get available issue types from Jira
    - JiraGetAvailableIssueTypesResponseError: Failed to get available issue types from Jira, response code did not match 200
    - JiraCreateIssueError: Failed to create an issue in Jira
    - JiraSendFindingsResponseError: Failed to send the findings to Jira
    - JiraTestConnectionError: Failed to test the connection

Usage:
    jira = Jira(
        redirect_uri="http://localhost:8080",
        client_id="client_id",
        client_secret="client_secret
    )
    jira.send_findings(findings=findings, project_key="KEY")
"""

_redirect_uri: str = None
_client_id: str = None
_client_secret: str = None
_access_token: str = None
_refresh_token: str = None
_expiration_date: int = None
_cloud_id: str = None
_scopes: list[str] = None
AUTH_URL = "https://auth.atlassian.com/authorize"
PARAMS_TEMPLATE = {
    "audience": "api.atlassian.com",
    "client_id": None,
    "scope": None,
    "redirect_uri": None,
    "state": None,
    "response_type": "code",
    "prompt": "consent",
}
TOKEN_URL = "https://auth.atlassian.com/oauth/token"
API_TOKEN_URL = "https://api.atlassian.com/oauth/token/accessible-resources"

def __init__(
    self,
    redirect_uri: str = None,
    client_id: str = None,
    client_secret: str = None,
):
    self._redirect_uri = redirect_uri
    self._client_id = client_id
    self._client_secret = client_secret
    self._scopes = ["read:jira-user", "read:jira-work", "write:jira-work"]
    auth_url = self.auth_code_url()
    authorization_code = self.input_authorization_code(auth_url)
    self.get_auth(authorization_code)

# More properties and methods

Test Connection Method:

Validating Credentials or Tokens

To ensure a successful connection to the target platform, implement a method that validates authentication credentials or tokens.

Method Implementation¶

The following example demonstrates the test_connection method for the Jira class:

Test connection

@staticmethod
def test_connection(
    redirect_uri: str = None,
    client_id: str = None,
    client_secret: str = None,
    raise_on_exception: bool = True,
) -> Connection:
    """Test the connection to Jira

    Args:
        - redirect_uri: The redirect URI used
        - client_id: The client identifier
        - client_secret: The client secret
        - raise_on_exception: Whether to raise an exception or not

    Returns:
        - Connection: The connection object

    Raises:
        - JiraGetCloudIDNoResourcesError: No resources were found in Jira when getting the cloud id
        - JiraGetCloudIDResponseError: Failed to get the cloud ID, response code did not match 200
        - JiraGetCloudIDError: Failed to get the cloud ID from Jira
        - JiraAuthenticationError: Failed to authenticate
        - JiraTestConnectionError: Failed to test the connection
    """
    try:
        jira = Jira(
            redirect_uri=redirect_uri,
            client_id=client_id,
            client_secret=client_secret,
        )
        access_token = jira.get_access_token()

        if not access_token:
            return ValueError("Failed to get access token")

        headers = {"Authorization": f"Bearer {access_token}"}
        response = requests.get(
            f"https://api.atlassian.com/ex/jira/{jira.cloud_id}/rest/api/3/myself",
            headers=headers,
        )

        if response.status_code == 200:
            return Connection(is_connected=True)
        else:
            return Connection(is_connected=False, error=response.json())
    except JiraGetCloudIDNoResourcesError as no_resources_error:
        logger.error(
            f"{no_resources_error.__class__.__name__}[{no_resources_error.__traceback__.tb_lineno}]: {no_resources_error}"
        )
        if raise_on_exception:
            raise no_resources_error
        return Connection(error=no_resources_error)
    except JiraGetCloudIDResponseError as response_error:
        logger.error(
            f"{response_error.__class__.__name__}[{response_error.__traceback__.tb_lineno}]: {response_error}"
        )
        if raise_on_exception:
            raise response_error
        return Connection(error=response_error)
    except JiraGetCloudIDError as cloud_id_error:
        logger.error(
            f"{cloud_id_error.__class__.__name__}[{cloud_id_error.__traceback__.tb_lineno}]: {cloud_id_error}"
        )
        if raise_on_exception:
            raise cloud_id_error
        return Connection(error=cloud_id_error)
    except JiraAuthenticationError as auth_error:
        logger.error(
            f"{auth_error.__class__.__name__}[{auth_error.__traceback__.tb_lineno}]: {auth_error}"
        )
        if raise_on_exception:
            raise auth_error
        return Connection(error=auth_error)
    except Exception as error:
        logger.error(f"Failed to test connection: {error}")
        if raise_on_exception:
            raise JiraTestConnectionError(
                message="Failed to test connection on the Jira integration",
                file=os.path.basename(__file__),
            )
        return Connection(is_connected=False, error=error)

Send Findings Method:

Add a method to send Prowler findings to the target platform, adhering to its API specifications.

Method Implementation¶

The following example demonstrates the send_findings method for the Jira class:

Send findings method

def send_findings(
    self,
    findings: list[Finding] = None,
    project_key: str = None,
    issue_type: str = None,
):
    """
    Send the findings to Jira

    Args:
        - findings: The findings to send
        - project_key: The project key
        - issue_type: The issue type

    Raises:
        - JiraRefreshTokenError: Failed to refresh the access token
        - JiraRefreshTokenResponseError: Failed to refresh the access token, response code did not match 200
        - JiraCreateIssueError: Failed to create an issue in Jira
        - JiraSendFindingsResponseError: Failed to send the findings to Jira
    """
    try:
        access_token = self.get_access_token()

        if not access_token:
            raise JiraNoTokenError(
                message="No token was found",
                file=os.path.basename(__file__),
            )

        projects = self.get_projects()

        if project_key not in projects:
            logger.error("The project key is invalid")
            raise JiraInvalidProjectKeyError(
                message="The project key is invalid",
                file=os.path.basename(__file__),
            )

        available_issue_types = self.get_available_issue_types(project_key)

        if issue_type not in available_issue_types:
            logger.error("The issue type is invalid")
            raise JiraInvalidIssueTypeError(
                message="The issue type is invalid", file=os.path.basename(__file__)
            )
        headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json",
        }

        for finding in findings:
            status_color = self.get_color_from_status(finding.status.value)
            adf_description = self.get_adf_description(
                check_id=finding.metadata.CheckID,
                check_title=finding.metadata.CheckTitle,
                severity=finding.metadata.Severity.value.upper(),
                status=finding.status.value,
                status_color=status_color,
                status_extended=finding.status_extended,
                provider=finding.metadata.Provider,
                region=finding.region,
                resource_uid=finding.resource_uid,
                resource_name=finding.resource_name,
                risk=finding.metadata.Risk,
                recommendation_text=finding.metadata.Remediation.Recommendation.Text,
                recommendation_url=finding.metadata.Remediation.Recommendation.Url,
            )
            payload = {
                "fields": {
                    "project": {"key": project_key},
                    "summary": f"[Prowler] {finding.metadata.Severity.value.upper()} - {finding.metadata.CheckID} - {finding.resource_uid}",
                    "description": adf_description,
                    "issuetype": {"name": issue_type},
                }
            }

            response = requests.post(
                f"https://api.atlassian.com/ex/jira/{self.cloud_id}/rest/api/3/issue",
                json=payload,
                headers=headers,
            )

            if response.status_code != 201:
                response_error = f"Failed to send finding: {response.status_code} - {response.json()}"
                logger.warning(response_error)
                raise JiraSendFindingsResponseError(
                    message=response_error, file=os.path.basename(__file__)
                )
            else:
                logger.info(f"Finding sent successfully: {response.json()}")
    except JiraRefreshTokenError as refresh_error:
        raise refresh_error
    except JiraRefreshTokenResponseError as response_error:
        raise response_error
    except Exception as e:
        logger.error(f"Failed to send findings: {e}")
        raise JiraCreateIssueError(
            message="Failed to create an issue in Jira",
            file=os.path.basename(__file__),
        )

Testing the Integration¶

Conduct integration testing in a controlled environment to validate expected behavior. Ensure the following:
- Transmission Accuracy – Verify that Prowler findings are correctly sent and processed by the target platform.
- Error Handling – Simulate edge cases to assess robustness and failure recovery mechanisms.

Documentation¶

Ensure the following elements are included:
- Setup Instructions – List all necessary dependencies and installation steps.
- Configuration Details – Specify required environment variables, authentication steps, etc.
- Example Use Cases – Provide practical scenarios demonstrating functionality.
- Troubleshooting Guide – Document common issues and resolution steps.
- Comprehensive and clear documentation improves maintainability and simplifies onboarding.