Introduction to developing in Prowler¶
Extending Prowler
Prowler can be extended in various ways, with common use cases including:
- New security checks
- New compliance frameworks
- New output formats
- New integrations
- New proposed features
All the relevant information for these cases is included in this guide.
Getting the Code and Installing All Dependencies¶
Prerequisites¶
Before proceeding, ensure the following:
- Git is installed.
- Python 3.9 or higher is installed.
poetry
is installed to manage dependencies.
Forking the Prowler Repository¶
To contribute to Prowler, fork the Prowler GitHub repository. This allows you to propose changes, submit new features, and fix bugs. For guidance on forking, refer to the official GitHub documentation.
Cloning Your Forked Repository¶
Once your fork is created, clone it using the following commands:
Dependency Management and Environment Isolation¶
To prevent conflicts between environments, we recommend using poetry
, a Python dependency management solution. Install it by following the instructions.
Installing Dependencies¶
To install all required dependencies, including those needed for development, run:
Important
Starting from Poetry v2.0.0, poetry shell
has been deprecated in favor of poetry env activate
.
If your poetry version is below 2.0.0 you must keep using poetry shell
to activate your environment.
In case you have any doubts, consult the Poetry environment activation guide.
Contributing to Prowler¶
Ways to Contribute¶
Here are some ideas for collaborating with Prowler:
-
Review Current Issues: Check out our GitHub Issues page. We often tag issues as
good first issue
- these are perfect for new contributors as they are typically well-defined and manageable in scope. -
Expand Prowler's Capabilities: Prowler is constantly evolving, and you can be a part of its growth. Whether you are adding checks, supporting new services, or introducing integrations, your contributions help improve the tool for everyone. Here is how you can get involved:
-
Adding New Checks Want to improve Prowler's detection capabilities for your favorite cloud provider? You can contribute by writing new checks. To get started, follow the create a new check guide.
-
Adding New Services One key service for your favorite cloud provider is missing? Add it to Prowler! To add a new service, check out the create a new service guide. Do not forget to include relevant checks to validate functionality.
-
Adding New Providers If you would like to extend Prowler to work with a new cloud provider, follow the create a new provider guide. This typically involves setting up new services and checks to ensure compatibility.
-
Adding New Output Formats Want to tailor how results are displayed or exported? You can add custom output formats by following the create a new output format guide.
-
Adding New Integrations Prowler can work with other tools and platforms through integrations. If you would like to add one, see the create a new integration guide.
-
Proposing or Implementing Features Got an idea to make Prowler better? Whether it is a brand-new feature or an enhancement to an existing one, you are welcome to propose it or help implement community-requested improvements.
-
-
Improve Documentation: Help make Prowler more accessible by enhancing our documentation, fixing typos, or adding examples/tutorials. See the tutorial of how we write our documentation here.
-
Bug Fixes: If you find any issues or bugs, you can report them in the GitHub Issues page and if you want you can also fix them.
Remember, our community is here to help! If you need guidance, do not hesitate to ask questions in the issues or join our Slack workspace.
Pre-Commit Hooks¶
This repository uses Git pre-commit hooks managed by the pre-commit tool, it is installed with poetry install --with dev
. Next, run the following command in the root of this repository:
Successful installation should produce the following output:
Code Quality and Security Checks¶
Before merging pull requests, several automated checks and utilities ensure code security and updated dependencies:
Note
These should have been already installed if poetry install --with dev
was already run.
bandit
for code security review.safety
anddependabot
for dependencies.hadolint
anddockle
for container security.Snyk
for container security in Docker Hub.clair
for container security in Amazon ECR.vulture
,flake8
,black
, andpylint
for formatting and best practices.
Additionally, ensure the latest version of TruffleHog
is installed to scan for sensitive data in the code. Follow the official installation guide for setup.
Dependency Management¶
All dependencies are listed in the pyproject.toml
file.
For proper code documentation, refer to the following and follow the code documentation practices presented there: Google Python Style Guide - Comments and Docstrings.
Note
If you encounter issues when committing to the Prowler repository, use the --no-verify
flag with the git commit
command.
Repository Folder Structure¶
Understanding the layout of the Prowler codebase will help you quickly find where to add new features, checks, or integrations. The following is a high-level overview from the root of the repository:
prowler/
├── prowler/ # Main source code for Prowler SDK (CLI, providers, services, checks, compliances, config, etc.)
├── api/ # API server and related code
├── dashboard/ # Local Dashboard extracted from the CLI output
├── ui/ # Web UI components
├── util/ # Utility scripts and helpers
├── tests/ # Prowler SDK test suite
├── docs/ # Documentation, including this guide
├── examples/ # Example output formats for providers and scripts
├── permissions/ # Permission-related files and policies
├── contrib/ # Community-contributed scripts or modules
├── kubernetes/ # Kubernetes deployment files
├── .github/ # GitHub related files (workflows, issue templates, etc.)
├── pyproject.toml # Python project configuration (Poetry)
├── poetry.lock # Poetry lock file
├── README.md # Project overview and getting started
├── Makefile # Common development commands
├── Dockerfile # SDK Docker container
├── docker-compose.yml # Prowler App Docker compose
└── ... # Other supporting files
Pull Request Checklist¶
When creating or reviewing a pull request in https://github.com/prowler-cloud/prowler, follow this checklist.
Contribution Appreciation¶
If you enjoy swag, we’d love to thank you for your contribution with laptop stickers or other Prowler merchandise!
To request swag: Share your pull request details in our Slack workspace.
You can also reach out to Toni de la Fuente on Twitter—his DMs are open!