mirror of
https://github.com/prowler-cloud/prowler.git
synced 2025-12-19 05:17:47 +00:00
docs(mcp): add comprehensive MCP Server documentation (#8931)
This commit is contained in:
Rubén De la Torre Vico
committed by
GitHub
GitHub
parent
ba765fa07d
commit
6f394cf9de
@@ -41,13 +41,6 @@
|
||||
"getting-started/basic-usage/prowler-cli"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Prowler Lighthouse AI",
|
||||
"pages": [
|
||||
"user-guide/tutorials/prowler-app-lighthouse",
|
||||
"getting-started/goto/prowler-mcp"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Prowler App",
|
||||
"pages": [
|
||||
@@ -56,6 +49,21 @@
|
||||
"getting-started/basic-usage/prowler-app"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Prowler Lighthouse AI",
|
||||
"pages": [
|
||||
"user-guide/tutorials/prowler-app-lighthouse"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Prowler MCP Server",
|
||||
"pages": [
|
||||
"getting-started/products/prowler-mcp",
|
||||
"getting-started/installation/prowler-mcp",
|
||||
"getting-started/basic-usage/prowler-mcp",
|
||||
"getting-started/basic-usage/prowler-mcp-tools"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Prowler Hub",
|
||||
"pages": [
|
||||
|
||||
122
docs/getting-started/basic-usage/prowler-mcp-tools.mdx
Normal file
122
docs/getting-started/basic-usage/prowler-mcp-tools.mdx
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "Tools Reference"
|
||||
---
|
||||
|
||||
Complete reference guide for all tools available in the Prowler MCP Server. Tools are organized by namespace.
|
||||
|
||||
## Tool Categories Summary
|
||||
|
||||
| Category | Tool Count | Authentication Required |
|
||||
|----------|------------|------------------------|
|
||||
| Prowler Hub | 10 tools | No |
|
||||
| Prowler Documentation | 2 tools | No |
|
||||
| Prowler Cloud/App | 28 tools | Yes |
|
||||
|
||||
## Tool Naming Convention
|
||||
|
||||
All tools follow a consistent naming pattern with prefixes:
|
||||
|
||||
- `prowler_hub_*` - Prowler Hub catalog and compliance tools
|
||||
- `prowler_docs_*` - Prowler documentation search and retrieval
|
||||
- `prowler_app_*` - Prowler Cloud and App (Self-Managed) management tools
|
||||
|
||||
## Prowler Hub Tools
|
||||
|
||||
Access Prowler's security check catalog and compliance frameworks. **No authentication required.**
|
||||
|
||||
### Check Discovery
|
||||
|
||||
- **`prowler_hub_get_checks`** - List security checks with advanced filtering options
|
||||
- **`prowler_hub_get_check_filters`** - Return available filter values for checks (providers, services, severities, categories, compliances)
|
||||
- **`prowler_hub_search_checks`** - Full-text search across check metadata
|
||||
- **`prowler_hub_get_check_raw_metadata`** - Fetch raw check metadata in JSON format
|
||||
|
||||
### Check Code
|
||||
|
||||
- **`prowler_hub_get_check_code`** - Fetch the Python implementation code for a security check
|
||||
- **`prowler_hub_get_check_fixer`** - Fetch the automated fixer code for a check (if available)
|
||||
|
||||
### Compliance Frameworks
|
||||
|
||||
- **`prowler_hub_get_compliance_frameworks`** - List and filter compliance frameworks
|
||||
- **`prowler_hub_search_compliance_frameworks`** - Full-text search across compliance frameworks
|
||||
|
||||
### Provider Information
|
||||
|
||||
- **`prowler_hub_list_providers`** - List Prowler official providers and their services
|
||||
- **`prowler_hub_get_artifacts_count`** - Get total count of checks and frameworks in Prowler Hub
|
||||
|
||||
## Prowler Documentation Tools
|
||||
|
||||
Search and access official Prowler documentation. **No authentication required.**
|
||||
|
||||
- **`prowler_docs_search`** - Search the official Prowler documentation using full-text search
|
||||
- **`prowler_docs_get_document`** - Retrieve the full markdown content of a specific documentation file
|
||||
|
||||
## Prowler Cloud/App Tools
|
||||
|
||||
Manage Prowler Cloud or Prowler App (Self-Managed) features. **Requires authentication.**
|
||||
|
||||
<Note>
|
||||
These tools require a valid API key. See the [Configuration Guide](/getting-started/basic-usage/prowler-mcp) for authentication setup.
|
||||
</Note>
|
||||
|
||||
### Findings Management
|
||||
|
||||
- **`prowler_app_list_findings`** - List security findings with advanced filtering
|
||||
- **`prowler_app_get_finding`** - Get detailed information about a specific finding
|
||||
- **`prowler_app_get_latest_findings`** - Retrieve latest findings from the most recent scans
|
||||
- **`prowler_app_get_findings_metadata`** - Get unique metadata values from filtered findings
|
||||
- **`prowler_app_get_latest_findings_metadata`** - Get metadata from latest findings across all providers
|
||||
|
||||
### Provider Management
|
||||
|
||||
- **`prowler_app_list_providers`** - List all providers with filtering options
|
||||
- **`prowler_app_create_provider`** - Create a new provider in the current tenant
|
||||
- **`prowler_app_get_provider`** - Get detailed information about a specific provider
|
||||
- **`prowler_app_update_provider`** - Update provider details (alias, etc.)
|
||||
- **`prowler_app_delete_provider`** - Delete a specific provider
|
||||
- **`prowler_app_test_provider_connection`** - Test provider connection status
|
||||
|
||||
### Provider Secrets Management
|
||||
|
||||
- **`prowler_app_list_provider_secrets`** - List all provider secrets with filtering
|
||||
- **`prowler_app_add_provider_secret`** - Add or update credentials for a provider
|
||||
- **`prowler_app_get_provider_secret`** - Get detailed information about a provider secret
|
||||
- **`prowler_app_update_provider_secret`** - Update provider secret details
|
||||
- **`prowler_app_delete_provider_secret`** - Delete a provider secret
|
||||
|
||||
### Scan Management
|
||||
|
||||
- **`prowler_app_list_scans`** - List all scans with filtering options
|
||||
- **`prowler_app_create_scan`** - Trigger a manual scan for a specific provider
|
||||
- **`prowler_app_get_scan`** - Get detailed information about a specific scan
|
||||
- **`prowler_app_update_scan`** - Update scan details
|
||||
- **`prowler_app_get_scan_compliance_report`** - Download compliance report as CSV
|
||||
- **`prowler_app_get_scan_report`** - Download ZIP file containing complete scan report
|
||||
|
||||
### Schedule Management
|
||||
|
||||
- **`prowler_app_schedules_daily_scan`** - Create a daily scheduled scan for a provider
|
||||
|
||||
### Processor Management
|
||||
|
||||
- **`prowler_app_processors_list`** - List all processors with filtering
|
||||
- **`prowler_app_processors_create`** - Create a new processor (currently only mute lists supported)
|
||||
- **`prowler_app_processors_retrieve`** - Get processor details by ID
|
||||
- **`prowler_app_processors_partial_update`** - Update processor configuration
|
||||
- **`prowler_app_processors_destroy`** - Delete a processor
|
||||
|
||||
## Usage Tips
|
||||
|
||||
- Use natural language to interact with the tools through your AI assistant
|
||||
- Tools can be combined for complex workflows
|
||||
- Filter options are available on most list tools
|
||||
- Authentication is only required for Prowler Cloud/App tools
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [MCP Protocol Specification](https://modelcontextprotocol.io)
|
||||
- [Prowler API Documentation](https://api.prowler.com/api/v1/docs)
|
||||
- [Prowler Hub API](https://hub.prowler.com/api/docs)
|
||||
- [GitHub Repository](https://github.com/prowler-cloud/prowler)
|
||||
247
docs/getting-started/basic-usage/prowler-mcp.mdx
Normal file
247
docs/getting-started/basic-usage/prowler-mcp.mdx
Normal file
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Configuration"
|
||||
---
|
||||
|
||||
Configure your MCP client to connect to Prowler MCP Server.
|
||||
|
||||
## Step 1: Get Your API Key (Optional)
|
||||
|
||||
<Note>
|
||||
**Authentication is optional**: Prowler Hub and Prowler Documentation features work without authentication. An API key is only required for Prowler Cloud and Prowler App (Self-Managed) features.
|
||||
</Note>
|
||||
|
||||
To use Prowler Cloud or Prowler App (Self-Managed) features. To get the API key, please refer to the [API Keys](/user-guide/providers/prowler-app-api-keys) guide.
|
||||
|
||||
<Warning>
|
||||
Keep the API key secure. Never share it publicly or commit it to version control.
|
||||
</Warning>
|
||||
|
||||
## Step 2: Configure Your MCP Client
|
||||
|
||||
Choose the configuration based on your deployment:
|
||||
|
||||
- **STDIO Mode**: Local installation only (runs as subprocess).
|
||||
- **HTTP Mode**: Prowler Cloud MCP Server or self-hosted Prowler MCP Server.
|
||||
|
||||
### HTTP Mode (Prowler Cloud MCP Server or self-hosted Prowler MCP Server)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Native HTTP Support (Cursor, VSCode)">
|
||||
**Clients that support HTTP with custom headers natively**
|
||||
|
||||
For example: Cursor, VSCode, LobeChat, etc.
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"url": "https://mcp.prowler.com/mcp", // or your self-hosted Prowler MCP Server URL
|
||||
"headers": {
|
||||
"Authorization": "Bearer pk_your_api_key_here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Using mcp-remote (Claude Desktop)">
|
||||
**For clients without native HTTP support (like Claude Desktop)**
|
||||
|
||||
For example: Claude Desktop.
|
||||
|
||||
**Configuration:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://mcp.prowler.com/mcp", // or your self-hosted Prowler MCP Server URL
|
||||
"--header",
|
||||
"Authorization: Bearer ${PROWLER_APP_API_KEY}"
|
||||
],
|
||||
"env": {
|
||||
"PROWLER_APP_API_KEY": "pk_your_api_key_here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Info>
|
||||
The `mcp-remote` tool acts as a bridge for clients that don't support HTTP natively. Learn more at [mcp-remote on npm](https://www.npmjs.com/package/mcp-remote).
|
||||
</Info>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### STDIO Mode (Local Installation Only)
|
||||
|
||||
STDIO mode is only available when running the MCP server locally.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Using uvx">
|
||||
**Run from source or local installation**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"command": "uvx",
|
||||
"args": ["/absolute/path/to/prowler/mcp_server/"],
|
||||
"env": {
|
||||
"PROWLER_APP_API_KEY": "pk_your_api_key_here",
|
||||
"PROWLER_API_BASE_URL": "https://api.prowler.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `/absolute/path/to/prowler/mcp_server/` with the actual path. The `PROWLER_API_BASE_URL` is optional and defaults to Prowler Cloud API.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Using Docker">
|
||||
**Run with Docker image**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"command": "docker",
|
||||
"args": [
|
||||
"run",
|
||||
"--rm",
|
||||
"-i",
|
||||
"--env",
|
||||
"PROWLER_APP_API_KEY=pk_your_api_key_here",
|
||||
"--env",
|
||||
"PROWLER_API_BASE_URL=https://api.prowler.com",
|
||||
"prowlercloud/prowler-mcp"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
The `PROWLER_API_BASE_URL` is optional and defaults to Prowler Cloud API.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 3: Start Using Prowler MCP
|
||||
|
||||
Restart your MCP client and start asking questions:
|
||||
- *"Show me all critical findings from my AWS accounts"*
|
||||
- *"What does the S3 bucket public access check do?"*
|
||||
- *"Onboard this new AWS account in my Prowler Organization"*
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
Prowler MCP Server supports two authentication methods to connect to Prowler Cloud or Prowler App (Self-Managed):
|
||||
|
||||
### API Key (Recommended)
|
||||
|
||||
Use your Prowler API key directly in the Bearer token:
|
||||
|
||||
```
|
||||
Authorization: Bearer pk_your_api_key_here
|
||||
```
|
||||
|
||||
This is the recommended method for most users.
|
||||
|
||||
### JWT Token
|
||||
|
||||
Alternatively, obtain a JWT token from Prowler:
|
||||
|
||||
```bash
|
||||
curl -X POST https://api.prowler.com/api/v1/tokens \
|
||||
-H "Content-Type: application/vnd.api+json" \
|
||||
-H "Accept: application/vnd.api+json" \
|
||||
-d '{
|
||||
"data": {
|
||||
"type": "tokens",
|
||||
"attributes": {
|
||||
"email": "your-email@example.com",
|
||||
"password": "your-password"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Use the returned JWT token in place of the API key:
|
||||
|
||||
```
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
||||
```
|
||||
|
||||
<Warning>
|
||||
JWT tokens are only valid for 30 minutes. You need to generate a new token if you want to continue using the MCP server.
|
||||
</Warning>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Detected
|
||||
|
||||
- Restart your MCP client after configuration changes
|
||||
- Check the configuration file syntax (valid JSON)
|
||||
- Review client logs for specific error messages
|
||||
- Verify the server URL is correct
|
||||
|
||||
### Authentication Failures
|
||||
|
||||
**Error: Unauthorized (401)**
|
||||
- Verify your API key is correct
|
||||
- Ensure the key hasn't expired
|
||||
- Check you're using the right API endpoint
|
||||
|
||||
### Connection Issues
|
||||
|
||||
**Cannot Reach Server:**
|
||||
- Verify the server URL is correct
|
||||
- Check network connectivity
|
||||
- For local servers, ensure the server is running
|
||||
- Check firewall settings
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Protect Your API Key**
|
||||
- Never commit API keys to version control.
|
||||
- Use environment variables or secure vaults.
|
||||
- Rotate keys regularly.
|
||||
|
||||
2. **Network Security**
|
||||
- Use HTTPS for production deployments.
|
||||
- Restrict network access to the MCP server.
|
||||
- Consider VPN for remote access.
|
||||
|
||||
3. **Least Privilege**
|
||||
- API key gives the permission of the user who created the key, make sure to use the key with the minimal required permissions.
|
||||
- Review the tools that are gonna be used and how they are gonna be used to avoid prompt injections or unintended behavior.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that your MCP server is configured:
|
||||
|
||||
<CardGroup cols={1}>
|
||||
<Card title="Tools Reference" icon="wrench" href="/getting-started/basic-usage/prowler-mcp-tools">
|
||||
Explore all available tools
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Getting Help
|
||||
|
||||
Need assistance with configuration?
|
||||
|
||||
- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues)
|
||||
- Ask for help in our [Slack community](https://goto.prowler.com/slack)
|
||||
- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new)
|
||||
247
docs/getting-started/installation/prowler-mcp.mdx
Normal file
247
docs/getting-started/installation/prowler-mcp.mdx
Normal file
@@ -0,0 +1,247 @@
|
||||
---
|
||||
title: "Installation"
|
||||
---
|
||||
|
||||
There are **two ways** to use Prowler MCP Server:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Option 1: Managed by Prowler" icon="cloud" color="#10B981">
|
||||
**No installation required** - Just configuration
|
||||
|
||||
Use `https://mcp.prowler.com/mcp`
|
||||
</Card>
|
||||
<Card title="Option 2: Run Locally" icon="server" color="#6366F1">
|
||||
**Local installation** - Full control
|
||||
|
||||
Install via Docker, PyPI, or source code
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
|
||||
For "Option 1: Managed by Prowler", go directly to the [Configuration Guide](/getting-started/basic-usage/prowler-mcp#hosted-server-configuration-recommended) to set up your Claude Desktop, Cursor, or other MCP client.
|
||||
**This guide is focused on local installation, "Option 2: Run Locally"**.
|
||||
|
||||
## Installation Methods
|
||||
|
||||
Choose one of the following installation methods:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Docker (Recommended)">
|
||||
### Pull from Docker Hub
|
||||
|
||||
The easiest way to run locally is using the official Docker image:
|
||||
|
||||
```bash
|
||||
docker pull prowlercloud/prowler-mcp
|
||||
```
|
||||
|
||||
### Run the Container
|
||||
|
||||
```bash
|
||||
# STDIO mode (for local MCP clients)
|
||||
docker run --rm -i prowlercloud/prowler-mcp
|
||||
|
||||
# HTTP mode (for remote access)
|
||||
docker run --rm -p 8000:8000 \
|
||||
prowlercloud/prowler-mcp \
|
||||
--transport http --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### With Environment Variables
|
||||
|
||||
```bash
|
||||
docker run --rm -i \
|
||||
-e PROWLER_APP_API_KEY="pk_your_api_key" \
|
||||
-e PROWLER_API_BASE_URL="https://api.prowler.com" \
|
||||
prowlercloud/prowler-mcp
|
||||
```
|
||||
|
||||
<Info>
|
||||
**Docker Hub:** [prowlercloud/prowler-mcp](https://hub.docker.com/r/prowlercloud/prowler-mcp)
|
||||
</Info>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="PyPI Package">
|
||||
### Install via pip
|
||||
|
||||
<Warning>
|
||||
**Coming Soon** - PyPI package will be available shortly
|
||||
</Warning>
|
||||
</Tab>
|
||||
|
||||
<Tab title="From Source (Development)">
|
||||
### Install uv
|
||||
|
||||
If `uv` is not installed, install it first. Visit [uv documentation](https://docs.astral.sh/uv/) for more installation options.
|
||||
|
||||
### Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/prowler-cloud/prowler.git
|
||||
cd prowler/mcp_server
|
||||
```
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
The MCP server uses `uv` for dependency management. Install dependencies with:
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
Test that the server is properly installed:
|
||||
|
||||
```bash
|
||||
uv run prowler-mcp --help
|
||||
```
|
||||
|
||||
The help message with available command-line options should appear.
|
||||
|
||||
<Note>
|
||||
**For Development:** This method is recommended if you're developing or contributing to the MCP server.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Build Docker Image">
|
||||
### Prerequisites
|
||||
|
||||
Ensure Docker is installed on your system. Visit [Docker documentation](https://docs.docker.com/get-docker/) for more installation options.
|
||||
|
||||
### Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/prowler-cloud/prowler.git
|
||||
cd prowler/mcp_server
|
||||
```
|
||||
|
||||
### Build the Docker Image
|
||||
|
||||
```bash
|
||||
docker build -t prowler-mcp .
|
||||
```
|
||||
|
||||
This creates a Docker image named `prowler-mcp` with all necessary dependencies.
|
||||
|
||||
### Verify Installation
|
||||
|
||||
Test that the Docker image was built successfully:
|
||||
|
||||
```bash
|
||||
docker run --rm prowler-mcp --help
|
||||
```
|
||||
|
||||
The help message with available command-line options should appear.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Command Line Options
|
||||
|
||||
The Prowler MCP Server supports the following command-line arguments:
|
||||
|
||||
```bash
|
||||
prowler-mcp [--transport {stdio,http}] [--host HOST] [--port PORT]
|
||||
```
|
||||
|
||||
| Argument | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `--transport` | `stdio`, `http` | `stdio` | Transport method for MCP communication |
|
||||
| `--host` | Any valid hostname/IP | `127.0.0.1` | Host to bind to (HTTP mode only) |
|
||||
| `--port` | Port number | `8000` | Port to bind to (HTTP mode only) |
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Default STDIO mode for local MCP client integration
|
||||
prowler-mcp
|
||||
|
||||
# Explicit STDIO mode
|
||||
prowler-mcp --transport stdio
|
||||
|
||||
# HTTP mode on default host and port (127.0.0.1:8000)
|
||||
prowler-mcp --transport http
|
||||
|
||||
# HTTP mode accessible from any network interface
|
||||
prowler-mcp --transport http --host 0.0.0.0
|
||||
|
||||
# HTTP mode with custom port
|
||||
prowler-mcp --transport http --host 0.0.0.0 --port 8080
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Configure the server using environment variables:
|
||||
|
||||
| Variable | Description | Required | Default |
|
||||
|----------|-------------|----------|---------|
|
||||
| `PROWLER_APP_API_KEY` | Prowler API key | Only for STDIO mode | - |
|
||||
| `PROWLER_API_BASE_URL` | Custom Prowler API endpoint | No | `https://api.prowler.com` |
|
||||
| `PROWLER_MCP_MODE` | Default transport mode (overwritten by `--transport` argument) | No | `stdio` |
|
||||
|
||||
<CodeGroup>
|
||||
```bash macOS/Linux
|
||||
export PROWLER_APP_API_KEY="pk_your_api_key_here"
|
||||
export PROWLER_API_BASE_URL="https://api.prowler.com"
|
||||
export PROWLER_MCP_MODE="http"
|
||||
```
|
||||
|
||||
```bash Windows PowerShell
|
||||
$env:PROWLER_APP_API_KEY="pk_your_api_key_here"
|
||||
$env:PROWLER_API_BASE_URL="https://api.prowler.com"
|
||||
$env:PROWLER_MCP_MODE="http"
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Warning>
|
||||
Never commit your API key to version control. Use environment variables or secure secret management solutions.
|
||||
</Warning>
|
||||
|
||||
### Using Environment Files
|
||||
|
||||
For convenience, create a `.env` file in the `mcp_server` directory:
|
||||
|
||||
```bash .env
|
||||
PROWLER_APP_API_KEY=pk_your_api_key_here
|
||||
PROWLER_API_BASE_URL=https://api.prowler.com
|
||||
PROWLER_MCP_MODE=stdio
|
||||
```
|
||||
|
||||
When using Docker, pass the environment file:
|
||||
|
||||
```bash
|
||||
docker run --rm --env-file .env -it prowler-mcp
|
||||
```
|
||||
|
||||
## Running from Any Location
|
||||
|
||||
Run the MCP server from anywhere using `uvx`:
|
||||
|
||||
```bash
|
||||
uvx /path/to/prowler/mcp_server/
|
||||
```
|
||||
|
||||
This is particularly useful when configuring MCP clients that need to launch the server from a specific path.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you have the Prowler MCP Server installed, proceed to configure your MCP client:
|
||||
|
||||
<CardGroup cols={1}>
|
||||
<Card title="Configuration" icon="gear" href="/getting-started/basic-usage/prowler-mcp">
|
||||
Configure Claude Desktop, Cursor, or other MCP clients
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during installation:
|
||||
|
||||
- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues)
|
||||
- Ask for help in our [Slack community](https://goto.prowler.com/slack)
|
||||
- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new)
|
||||
125
docs/getting-started/products/prowler-mcp.mdx
Normal file
125
docs/getting-started/products/prowler-mcp.mdx
Normal file
@@ -0,0 +1,125 @@
|
||||
---
|
||||
title: "Overview"
|
||||
---
|
||||
|
||||
**Prowler MCP Server** brings the entire Prowler ecosystem to AI assistants through the Model Context Protocol (MCP). It enables seamless integration with AI tools like Claude Desktop, Cursor, and other MCP clients, allowing interaction with Prowler's security capabilities through natural language.
|
||||
|
||||
<Warning>
|
||||
**Preview Feature**: This MCP server is currently in preview and under active development. Features and functionality may change. We welcome your feedback—please report any issues on [GitHub](https://github.com/prowler-cloud/prowler/issues) or join our [Slack community](https://goto.prowler.com/slack) to discuss and share your thoughts.
|
||||
</Warning>
|
||||
|
||||
## What is the Model Context Protocol?
|
||||
|
||||
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard developed by Anthropic that enables AI assistants to securely connect to external data sources and tools. It functions as a universal adapter enabling AI assistants to interact with various services through a standardized interface.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
The Prowler MCP Server provides three main integration points:
|
||||
|
||||
### 1. Prowler Cloud and Prowler App (Self-Managed)
|
||||
|
||||
Full access to Prowler Cloud platform and self-managed Prowler App for:
|
||||
- **Provider Management**: Create, configure, and manage cloud providers (AWS, Azure, GCP, etc.).
|
||||
- **Scan Orchestration**: Trigger on-demand scans and schedule recurring security assessments.
|
||||
- **Findings Analysis**: Query, filter, and analyze security findings across all your cloud environments.
|
||||
- **Compliance Reporting**: Generate compliance reports for various frameworks (CIS, PCI-DSS, HIPAA, etc.).
|
||||
- **Secrets Management**: Securely manage provider credentials and connection details.
|
||||
- **Processor Configuration**: Set up the [Prowler Mutelist](/user-guide/tutorials/prowler-app-mute-findings) to mute findings.
|
||||
|
||||
### 2. Prowler Hub
|
||||
|
||||
Access to Prowler's comprehensive security knowledge base:
|
||||
- **Security Checks Catalog**: Browse and search **over 1000 security checks** across multiple cloud providers.
|
||||
- **Check Implementation**: View the Python code that powers each security check.
|
||||
- **Automated Fixers**: Access remediation scripts for common security issues.
|
||||
- **Compliance Frameworks**: Explore mappings to **over 70 compliance standards and frameworks**.
|
||||
- **Provider Services**: View available services and checks for each cloud provider.
|
||||
|
||||
### 3. Prowler Documentation
|
||||
|
||||
Search and retrieve official Prowler documentation:
|
||||
- **Intelligent Search**: Full-text search across all Prowler documentation.
|
||||
- **Contextual Results**: Get relevant documentation pages with highlighted snippets.
|
||||
- **Document Retrieval**: Access complete markdown content of any documentation file.
|
||||
|
||||
## Use Cases
|
||||
|
||||
The Prowler MCP Server enables powerful workflows through AI assistants:
|
||||
|
||||
**Security Operations**
|
||||
- "Show me all critical findings from my AWS production accounts"
|
||||
- "What is my compliance status for the PCI standards accross all my AWS accounts according to the latest Prowler scan results?"
|
||||
- "Register my new AWS account in Prowler and run an scheduled scan every day"
|
||||
|
||||
**Security Research**
|
||||
- "Explain what the S3 bucket public access check does"
|
||||
- "Find all checks related to encryption at rest"
|
||||
- "What is the latest version of the CIS that Prowler is covering per provider?"
|
||||
|
||||
**Documentation & Learning**
|
||||
- "How do I configure Prowler to scan my GCP organization?"
|
||||
- "What authentication methods does Prowler support for Azure?"
|
||||
- "How can I contribute with a new security check to Prowler?"
|
||||
|
||||
## Deployment Options
|
||||
|
||||
Prowler MCP Server can be used in three ways:
|
||||
|
||||
### 1. Prowler Cloud MCP Server
|
||||
|
||||
**Use Prowler's managed MCP server at `https://mcp.prowler.com/mcp`**
|
||||
|
||||
- No installation required.
|
||||
- Managed and maintained by Prowler team.
|
||||
- Authentication to Prowler Cloud or Prowler App (self-managed) via API key or JWT token.
|
||||
|
||||
### 2. Local STDIO Mode
|
||||
|
||||
**Run the server locally on your machine**
|
||||
|
||||
- Runs as a subprocess of your MCP client.
|
||||
- Possibility to connect to a self-hosted Prowler App (e.g. self-hosted Prowler App).
|
||||
- Authentication to Prowler Cloud or Prowler App (self-managed) via environment variables.
|
||||
- Requires Python 3.12+ or Docker.
|
||||
|
||||
### 3. Self-Hosted HTTP Mode
|
||||
|
||||
**Deploy your own remote MCP server**
|
||||
|
||||
- Full control over deployment.
|
||||
- Possibility to connect to a self-hosted Prowler App (e.g. self-hosted Prowler App).
|
||||
- Authentication to Prowler App (self-managed) via API key or JWT token.
|
||||
- Requires Python 3.12+ or Docker.
|
||||
|
||||
## Requirements
|
||||
|
||||
Requirements vary based on deployment option:
|
||||
|
||||
**For Prowler Cloud MCP Server:**
|
||||
- Prowler Cloud account and API key (only for Prowler Cloud/App features)
|
||||
|
||||
**For self-hosted STDIO/HTTP Mode:**
|
||||
- Python 3.12+ or Docker
|
||||
- Network access to:
|
||||
- `https://hub.prowler.com` (for Prowler Hub)
|
||||
- `https://docs.prowler.com` (for Prowler Documentation)
|
||||
- Prowler Cloud API or self-hosted Prowler App API (for Prowler Cloud/App features)
|
||||
|
||||
<Note>
|
||||
**No Authentication Required**: Prowler Hub and Prowler Documentation features work without authentication in both deployment options. A Prowler API key is only required to access Prowler Cloud or Prowler App (Self-Managed) features.
|
||||
</Note>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Installation" icon="download" href="/getting-started/installation/prowler-mcp">
|
||||
Install the Prowler MCP Server using uv or Docker
|
||||
</Card>
|
||||
<Card title="Configuration" icon="gear" href="/getting-started/basic-usage/prowler-mcp">
|
||||
Configure your MCP client to connect to the server
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Tools Reference" icon="wrench" href="/getting-started/basic-usage/prowler-mcp-tools" horizontal>
|
||||
Explore all available tools and capabilities
|
||||
</Card>
|
||||
@@ -8,39 +8,108 @@ Access the entire Prowler ecosystem through the Model Context Protocol (MCP). Th
|
||||
- **Prowler Hub**: Access to Prowler's security checks, fixers, and compliance frameworks catalog
|
||||
- **Prowler Documentation**: Search and retrieve official Prowler documentation
|
||||
|
||||
## Quick Start with Hosted Server (Recommended)
|
||||
|
||||
## Requirements
|
||||
**The easiest way to use Prowler MCP is through our hosted server at `https://mcp.prowler.com/mcp`**
|
||||
|
||||
- Python 3.12+
|
||||
- Network access to `https://hub.prowler.com` (for Prowler Hub)
|
||||
- Network access to `https://prowler.mintlify.app` (for Prowler Documentation)
|
||||
- Network access to Prowler Cloud and Prowler App (Self-Managed) API (it can be Prowler Cloud API or self-hosted Prowler App API)
|
||||
- Prowler Cloud account credentials (for Prowler Cloud and Prowler App (Self-Managed) features)
|
||||
No installation required! Just configure your MCP client:
|
||||
|
||||
## Installation
|
||||
|
||||
### From Sources
|
||||
|
||||
It is needed to have [uv](https://docs.astral.sh/uv/) installed.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/prowler-cloud/prowler.git
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://mcp.prowler.com/mcp",
|
||||
"--header",
|
||||
"Authorization: Bearer pk_YOUR_API_KEY_HERE"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using Docker
|
||||
**Configuration file locations:**
|
||||
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Claude Desktop (Windows)**: `%AppData%\Claude\claude_desktop_config.json`
|
||||
- **Cursor**: `~/.cursor/mcp.json`
|
||||
|
||||
Alternatively, you can build and run the MCP server using Docker:
|
||||
Get your API key at [Prowler Cloud](https://cloud.prowler.com) → Settings → API Keys
|
||||
|
||||
> **Benefits:** Always up-to-date, no maintenance, managed by Prowler team
|
||||
|
||||
## Local/Self-Hosted Installation
|
||||
|
||||
If you need to run the MCP server locally or self-host it, choose one of the following installation methods. **Configuration is the same** for both managed and local installations - just point to your local server URL instead of `https://mcp.prowler.com/mcp`.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Python 3.12+ (for source/PyPI installation)
|
||||
- Docker (for Docker installation)
|
||||
- Network access to `https://hub.prowler.com` (for Prowler Hub)
|
||||
- Network access to `https://prowler.mintlify.app` (for Prowler Documentation)
|
||||
- Network access to Prowler Cloud and Prowler App (Self-Managed) API (optional, only for Prowler Cloud/App features)
|
||||
- Prowler Cloud account credentials (only for Prowler Cloud and Prowler App features)
|
||||
|
||||
### Installation Methods
|
||||
|
||||
#### Option 1: Docker Hub (Recommended)
|
||||
|
||||
Pull the official image from Docker Hub:
|
||||
|
||||
```bash
|
||||
docker pull prowlercloud/prowler-mcp
|
||||
```
|
||||
|
||||
Run in STDIO mode:
|
||||
```bash
|
||||
docker run --rm -i prowlercloud/prowler-mcp
|
||||
```
|
||||
|
||||
Run in HTTP mode:
|
||||
```bash
|
||||
docker run --rm -p 8000:8000 \
|
||||
prowlercloud/prowler-mcp \
|
||||
--transport http --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
With environment variables:
|
||||
```bash
|
||||
docker run --rm -i \
|
||||
-e PROWLER_APP_API_KEY="pk_your_api_key" \
|
||||
-e PROWLER_API_BASE_URL="https://api.prowler.com" \
|
||||
prowlercloud/prowler-mcp
|
||||
```
|
||||
|
||||
**Docker Hub:** [prowlercloud/prowler-mcp](https://hub.docker.com/r/prowlercloud/prowler-mcp)
|
||||
|
||||
#### Option 2: PyPI Package (Coming Soon)
|
||||
|
||||
```bash
|
||||
pip install prowler-mcp-server
|
||||
prowler-mcp --help
|
||||
```
|
||||
|
||||
#### Option 3: From Source (Development)
|
||||
|
||||
Clone the repository and use `uv`:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/prowler-cloud/prowler.git
|
||||
cd prowler/mcp_server
|
||||
uv run prowler-mcp --help
|
||||
```
|
||||
|
||||
# Build the Docker image
|
||||
Install [uv](https://docs.astral.sh/uv/) first if needed.
|
||||
|
||||
#### Option 4: Build Docker Image from Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/prowler-cloud/prowler.git
|
||||
cd prowler/mcp_server
|
||||
docker build -t prowler-mcp .
|
||||
|
||||
# Run the container with environment variables
|
||||
docker run --rm --env-file ./.env -it prowler-mcp
|
||||
docker run --rm -i prowler-mcp
|
||||
```
|
||||
|
||||
## Running
|
||||
@@ -320,18 +389,60 @@ For local execution, configure your MCP client to launch the server directly. Be
|
||||
|
||||
For HTTP mode, you can configure your MCP client to connect to a remote Prowler MCP server.
|
||||
|
||||
**Important Limitations:**
|
||||
- HTTP mode support varies by client - some clients may not support HTTP transport yet.
|
||||
- Some MCP clients like Claude Desktop only support OAuth authentication for HTTP connections, which is not currently supported by our MCP server.
|
||||
Most MCP clients don't natively support HTTP transport with Bearer token authentication. However, you can use the `mcp-remote` proxy tool to connect any MCP client to remote HTTP servers.
|
||||
|
||||
Example configuration for clients that support HTTP transport:
|
||||
##### Using mcp-remote Proxy (Recommended for Claude Desktop)
|
||||
|
||||
For clients like Claude Desktop that don't support HTTP transport natively, use the `mcp-remote` npm package as a proxy:
|
||||
|
||||
**Using API Key (Recommended):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"url": "http://mcp.prowler.com/mcp", // Replace with your own MCP server URL, by default when server is run in local it is http://localhost:8000/mcp
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://mcp.prowler.com/mcp",
|
||||
"--header",
|
||||
"Authorization: Bearer pk_your_api_key_here"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Using JWT Token:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"mcp-remote",
|
||||
"https://mcp.prowler.com/mcp",
|
||||
"--header",
|
||||
"Authorization: Bearer <your-jwt-token-here>"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Replace `https://mcp.prowler.com/mcp` with your actual MCP server URL (use `http://localhost:8000/mcp` for local deployment). The `mcp-remote` package is automatically installed by `npx` on first use.
|
||||
|
||||
> **Info:** The `mcp-remote` tool acts as a bridge, converting STDIO protocol (used by Claude Desktop) to HTTP requests (used by the remote MCP server). Learn more at [mcp-remote on npm](https://www.npmjs.com/package/mcp-remote).
|
||||
|
||||
##### Direct HTTP Configuration (For Compatible Clients)
|
||||
|
||||
For clients that natively support HTTP transport with Bearer token authentication:
|
||||
|
||||
**Using API Key:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"url": "https://mcp.prowler.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer pk_your_api_key_here"
|
||||
}
|
||||
@@ -345,7 +456,7 @@ Example configuration for clients that support HTTP transport:
|
||||
{
|
||||
"mcpServers": {
|
||||
"prowler": {
|
||||
"url": "http://mcp.prowler.com/mcp", // Replace with your own MCP server URL, by default when server is run in local it is http://localhost:8000/mcp
|
||||
"url": "https://mcp.prowler.com/mcp",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <your-jwt-token-here>"
|
||||
}
|
||||
@@ -354,6 +465,8 @@ Example configuration for clients that support HTTP transport:
|
||||
}
|
||||
```
|
||||
|
||||
> **Note:** Replace `mcp.prowler.com` with your actual server hostname and adjust the port if needed (e.g., `http://localhost:8000/mcp` for local deployment).
|
||||
|
||||
### Claude Desktop (macOS/Windows)
|
||||
|
||||
Add the example server to Claude Desktop's config file, then restart the app.
|
||||
|
||||
Reference in New Issue
Block a user