mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-10-31 15:54:24 +00:00
docs(api): use mintlify for API specs
This commit is contained in:
pedrooot committed
1 parent
f831171a21
commit
77089eba57
136 files changed
+23969
No files matched your search
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: "List Latest Findings"
|
||||
api: "GET /api/v1/findings/latest"
|
||||
description: "Retrieve the latest findings from the most recent scans for each provider."
|
||||
---
|
||||
|
||||
Retrieve the most recent findings from the latest scan for each provider in your account. This endpoint automatically filters to show only the latest scan results, making it ideal for dashboards and monitoring.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
The endpoint supports the same filtering options as the regular findings list, except for the `inserted_at` filter (which is not required for this endpoint).
|
||||
|
||||
### Common Filters
|
||||
|
||||
**By Status:**
|
||||
- `filter[status]`, `filter[status__in]` - Filter by status
|
||||
- `filter[severity]`, `filter[severity__in]` - Filter by severity
|
||||
- `filter[delta]`, `filter[delta__in]` - Filter by change status
|
||||
- `filter[muted]` - Filter by mute status
|
||||
|
||||
**By Provider:**
|
||||
- `filter[provider]`, `filter[provider__in]` - Filter by provider
|
||||
- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type
|
||||
- `filter[provider_alias]`, `filter[provider_alias__icontains]` - Filter by provider alias
|
||||
|
||||
**By Resource:**
|
||||
- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name
|
||||
- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type
|
||||
- `filter[region]`, `filter[region__in]` - Filter by region
|
||||
- `filter[service]`, `filter[service__icontains]` - Filter by service
|
||||
|
||||
**By Check:**
|
||||
- `filter[check_id]`, `filter[check_id__icontains]` - Filter by check ID
|
||||
|
||||
### Pagination & Sorting
|
||||
|
||||
- `page[number]`, `page[size]` - Pagination options
|
||||
- `sort` - Sort by field
|
||||
- `fields[findings]` - Select specific fields
|
||||
- `include` - Include related resources
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings/latest?filter[severity]=critical&filter[status]=FAIL&filter[provider_type]=aws" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns findings from the most recent scan for each provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "findings",
|
||||
"id": "finding-uuid",
|
||||
"attributes": {
|
||||
"uid": "prowler-aws-iam-password-policy-weak",
|
||||
"check_id": "iam_password_policy_uppercase",
|
||||
"status": "FAIL",
|
||||
"status_extended": "IAM password policy does not require uppercase letters",
|
||||
"severity": "medium",
|
||||
"muted": false,
|
||||
"muted_reason": null,
|
||||
"delta": "new",
|
||||
"inserted_at": "2024-01-20T10:30:00Z",
|
||||
"updated_at": "2024-01-20T10:30:00Z",
|
||||
"first_seen_at": "2024-01-20T10:30:00Z",
|
||||
"check_metadata": {},
|
||||
"raw_result": {}
|
||||
},
|
||||
"relationships": {
|
||||
"scan": {
|
||||
"data": {
|
||||
"type": "scans",
|
||||
"id": "scan-uuid"
|
||||
}
|
||||
},
|
||||
"resources": {
|
||||
"data": []
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"page": {
|
||||
"number": 1,
|
||||
"size": 20,
|
||||
"total": 45,
|
||||
"total_pages": 3
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"self": "https://api.prowler.com/api/v1/findings/latest?page[number]=1",
|
||||
"first": "https://api.prowler.com/api/v1/findings/latest?page[number]=1",
|
||||
"next": "https://api.prowler.com/api/v1/findings/latest?page[number]=2",
|
||||
"last": "https://api.prowler.com/api/v1/findings/latest?page[number]=3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Use this endpoint for real-time monitoring and dashboards, as it automatically focuses on the latest scan results without requiring date filters.
|
||||
</Tip>
|
||||
@@ -0,0 +1,287 @@
|
||||
---
|
||||
title: "List Findings"
|
||||
api: "GET /api/v1/findings"
|
||||
description: "Retrieve a list of all findings with options for filtering by various criteria."
|
||||
---
|
||||
|
||||
Retrieve security findings (vulnerabilities, misconfigurations, compliance violations) across your cloud infrastructure. This is one of the most frequently used endpoints for analyzing your security posture.
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Security Dashboard**: Display current security findings and trends
|
||||
- **Compliance Reporting**: Filter findings by compliance framework
|
||||
- **Vulnerability Management**: Track and remediate security issues
|
||||
- **Alerting & Notifications**: Query new or critical findings for alerts
|
||||
- **Risk Assessment**: Analyze findings by severity and service
|
||||
- **Audit Trails**: Export findings for compliance audits
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Required Filters
|
||||
|
||||
- `filter[inserted_at]` - At least one variation of this filter is required
|
||||
- `filter[inserted_at__gte]` - Filter by creation date (greater than or equal). Maximum date range is 7 days
|
||||
- `filter[inserted_at__lte]` - Filter by creation date (less than or equal). Maximum date range is 7 days
|
||||
|
||||
### Filtering Options
|
||||
|
||||
**By Check:**
|
||||
- `filter[check_id]`, `filter[check_id__icontains]`, `filter[check_id__in]` - Filter by check ID
|
||||
|
||||
**By Status:**
|
||||
- `filter[status]` - Filter by status: `FAIL`, `PASS`, `MANUAL`
|
||||
- `filter[severity]` - Filter by severity: `critical`, `high`, `medium`, `low`, `informational`
|
||||
- `filter[delta]` - Filter by change status: `new`, `changed`
|
||||
- `filter[muted]` - Filter by mute status (boolean)
|
||||
|
||||
**By Provider:**
|
||||
- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID
|
||||
- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci`
|
||||
- `filter[provider_alias]`, `filter[provider_alias__icontains]` - Filter by provider alias
|
||||
- `filter[provider_uid]`, `filter[provider_uid__icontains]` - Filter by provider UID
|
||||
|
||||
**By Resource:**
|
||||
- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name
|
||||
- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type
|
||||
- `filter[resource_uid]`, `filter[resource_uid__icontains]` - Filter by resource UID
|
||||
- `filter[region]`, `filter[region__icontains]`, `filter[region__in]` - Filter by region
|
||||
- `filter[service]`, `filter[service__icontains]` - Filter by cloud service
|
||||
|
||||
**By Scan:**
|
||||
- `filter[scan]`, `filter[scan__in]` - Filter by scan UUID
|
||||
|
||||
### Pagination
|
||||
|
||||
- `page[number]` - Page number to retrieve
|
||||
- `page[size]` - Number of results per page
|
||||
|
||||
### Sorting
|
||||
|
||||
- `sort` - Field to sort by: `status`, `-status`, `severity`, `-severity`, `check_id`, `-check_id`, `inserted_at`, `-inserted_at`, `updated_at`, `-updated_at`
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[findings]` - Specify which fields to return
|
||||
|
||||
### Include Related Resources
|
||||
|
||||
- `include` - Include related resources: `scan`, `resources`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings?filter[inserted_at__gte]=2024-01-01&filter[status]=FAIL&filter[severity]=high&page[size]=20" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns a paginated list of findings with full details:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"type": "findings",
|
||||
"id": "finding-uuid",
|
||||
"attributes": {
|
||||
"uid": "prowler-aws-s3-bucket-unencrypted-123456",
|
||||
"check_id": "s3_bucket_default_encryption",
|
||||
"status": "FAIL",
|
||||
"status_extended": "S3 Bucket 'my-bucket' does not have default encryption enabled",
|
||||
"severity": "high",
|
||||
"muted": false,
|
||||
"muted_reason": null,
|
||||
"delta": "new",
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z",
|
||||
"first_seen_at": "2024-01-15T10:30:00Z",
|
||||
"check_metadata": {
|
||||
"Provider": "aws",
|
||||
"CheckID": "s3_bucket_default_encryption",
|
||||
"CheckTitle": "Check if S3 buckets have default encryption enabled",
|
||||
"CheckType": "Software and Configuration Checks",
|
||||
"ServiceName": "s3",
|
||||
"SubServiceName": "",
|
||||
"ResourceIdTemplate": "arn:partition:s3:::bucket_name",
|
||||
"Severity": "high",
|
||||
"ResourceType": "AwsS3Bucket",
|
||||
"Description": "S3 buckets should have encryption at rest enabled...",
|
||||
"Risk": "Unencrypted S3 buckets can expose sensitive data...",
|
||||
"RelatedUrl": "https://docs.aws.amazon.com/...",
|
||||
"Remediation": {
|
||||
"Code": {
|
||||
"CLI": "aws s3api put-bucket-encryption...",
|
||||
"NativeIaC": "...",
|
||||
"Other": "...",
|
||||
"Terraform": "..."
|
||||
},
|
||||
"Recommendation": {
|
||||
"Text": "Enable default encryption on S3 bucket",
|
||||
"Url": "https://docs.aws.amazon.com/..."
|
||||
}
|
||||
},
|
||||
"Categories": ["encryption"],
|
||||
"DependsOn": [],
|
||||
"RelatedTo": [],
|
||||
"Notes": ""
|
||||
},
|
||||
"raw_result": {
|
||||
"finding_unique_id": "...",
|
||||
"finding_uid": "...",
|
||||
"status": "FAIL",
|
||||
"status_extended": "...",
|
||||
"raw": {...}
|
||||
}
|
||||
},
|
||||
"relationships": {
|
||||
"scan": {
|
||||
"data": {
|
||||
"type": "scans",
|
||||
"id": "scan-uuid"
|
||||
}
|
||||
},
|
||||
"resources": {
|
||||
"data": [
|
||||
{
|
||||
"type": "resources",
|
||||
"id": "resource-uuid"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"page": {
|
||||
"number": 1,
|
||||
"size": 20,
|
||||
"total": 156,
|
||||
"total_pages": 8
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"self": "https://api.prowler.com/api/v1/findings?page[number]=1&page[size]=20",
|
||||
"first": "https://api.prowler.com/api/v1/findings?page[number]=1&page[size]=20",
|
||||
"next": "https://api.prowler.com/api/v1/findings?page[number]=2&page[size]=20",
|
||||
"last": "https://api.prowler.com/api/v1/findings?page[number]=8&page[size]=20"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
**Core Finding Information:**
|
||||
- `uid` (string, required) - Unique identifier for the finding (max 300 characters)
|
||||
- `check_id` (string, required) - ID of the security check that generated this finding (max 100 characters)
|
||||
- `status` (enum, required) - Finding status: `FAIL`, `PASS`, or `MANUAL`
|
||||
- `status_extended` (string, nullable) - Detailed human-readable status message
|
||||
- `severity` (enum, required) - Severity level: `critical`, `high`, `medium`, `low`, `informational`
|
||||
- `delta` (enum, nullable) - Change status: `new`, `changed`, or `null`
|
||||
|
||||
**Mute Management:**
|
||||
- `muted` (boolean) - Whether finding is muted (suppressed)
|
||||
- `muted_reason` (string, nullable) - Reason for muting (3-500 characters)
|
||||
|
||||
**Timestamps:**
|
||||
- `inserted_at` (datetime, read-only) - When finding was first created
|
||||
- `updated_at` (datetime, read-only) - Last time finding was modified
|
||||
- `first_seen_at` (datetime, nullable, read-only) - First time this finding was detected
|
||||
|
||||
**Check Details:**
|
||||
- `check_metadata` (object) - Complete metadata about the security check including:
|
||||
- Title, description, risk assessment
|
||||
- Remediation steps and code examples
|
||||
- Related documentation URLs
|
||||
- Compliance frameworks and categories
|
||||
- `raw_result` (object) - Complete raw output from the security check
|
||||
|
||||
**Relationships:**
|
||||
- `scan` - Reference to the scan that generated this finding
|
||||
- `resources` - References to affected cloud resources (read-only)
|
||||
|
||||
<Note>
|
||||
Resource information (service, region, resource name, etc.) is available through the `resources` relationship. Use `include=resources` to fetch resource details along with findings.
|
||||
</Note>
|
||||
|
||||
### Common Query Patterns
|
||||
|
||||
**Get all critical findings:**
|
||||
```bash
|
||||
curl "https://api.prowler.com/api/v1/findings?filter[severity]=critical&filter[status]=FAIL&filter[inserted_at__gte]=2024-01-01"
|
||||
```
|
||||
|
||||
**Get new findings from last scan:**
|
||||
```bash
|
||||
curl "https://api.prowler.com/api/v1/findings/latest?filter[delta]=new&filter[status]=FAIL"
|
||||
```
|
||||
|
||||
**Get findings for specific service:**
|
||||
```bash
|
||||
curl "https://api.prowler.com/api/v1/findings?filter[service]=s3&filter[inserted_at__gte]=2024-01-01"
|
||||
```
|
||||
|
||||
**Get findings for specific region:**
|
||||
```bash
|
||||
curl "https://api.prowler.com/api/v1/findings?filter[region]=us-east-1&filter[inserted_at__gte]=2024-01-01"
|
||||
```
|
||||
|
||||
**Get unmuted high/critical findings:**
|
||||
```bash
|
||||
curl "https://api.prowler.com/api/v1/findings?filter[severity__in]=critical,high&filter[muted]=false&filter[inserted_at__gte]=2024-01-01"
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
Use pagination parameters to navigate large result sets:
|
||||
|
||||
```bash
|
||||
# First page, 50 results
|
||||
curl "https://api.prowler.com/api/v1/findings?page[size]=50&page[number]=1&filter[inserted_at__gte]=2024-01-01"
|
||||
|
||||
# Next page
|
||||
curl "https://api.prowler.com/api/v1/findings?page[size]=50&page[number]=2&filter[inserted_at__gte]=2024-01-01"
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
**400 Bad Request** - Invalid filter or parameter
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "400",
|
||||
"title": "Invalid Filter",
|
||||
"detail": "Date range cannot exceed 7 days for inserted_at filters"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**422 Unprocessable Entity** - Missing required filter
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "422",
|
||||
"title": "Validation Error",
|
||||
"detail": "At least one variation of filter[inserted_at] is required"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Performance Tip:** Maximum date range for `inserted_at` filters is 7 days. For historical analysis, use multiple requests or export data to external storage.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
**Rate Limiting:** This endpoint is rate-limited to 100 requests per minute. For real-time monitoring, consider using webhooks or the `/findings/latest` endpoint.
|
||||
</Warning>
|
||||
|
||||
<Tip>
|
||||
Use `filter[delta]=new` to only retrieve findings discovered in the most recent scan, perfect for alerting on new security issues.
|
||||
</Tip>
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: "Retrieve Latest Findings Metadata"
|
||||
api: "GET /api/v1/findings/metadata/latest"
|
||||
description: "Fetch unique metadata values from the latest scans for each provider. This is useful for dynamic filtering."
|
||||
---
|
||||
|
||||
Retrieve metadata values such as services, regions, and resource types from the latest findings for each provider. This endpoint automatically filters to only include data from the most recent scans.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Filtering Options
|
||||
|
||||
**By Check:**
|
||||
- `filter[check_id]`, `filter[check_id__icontains]`, `filter[check_id__in]` - Filter by check ID
|
||||
|
||||
**By Status:**
|
||||
- `filter[status]` - Filter by status: `FAIL`, `PASS`, `MANUAL`
|
||||
- `filter[severity]` - Filter by severity: `critical`, `high`, `medium`, `low`, `informational`
|
||||
- `filter[delta]` - Filter by change status: `new`, `changed`
|
||||
- `filter[muted]` - Filter by mute status (boolean)
|
||||
|
||||
**By Provider:**
|
||||
- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID
|
||||
- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci`
|
||||
- `filter[provider_alias]`, `filter[provider_alias__icontains]` - Filter by provider alias
|
||||
- `filter[provider_uid]`, `filter[provider_uid__icontains]` - Filter by provider UID
|
||||
|
||||
**By Resource:**
|
||||
- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name
|
||||
- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type
|
||||
- `filter[resource_uid]`, `filter[resource_uid__icontains]` - Filter by resource UID
|
||||
- `filter[region]`, `filter[region__icontains]`, `filter[region__in]` - Filter by region
|
||||
- `filter[service]`, `filter[service__icontains]` - Filter by cloud service
|
||||
|
||||
### Sorting
|
||||
|
||||
- `sort` - Field to sort by: `status`, `-status`, `severity`, `-severity`, `check_id`, `-check_id`, `inserted_at`, `-inserted_at`, `updated_at`, `-updated_at`
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[findings-metadata]` - Specify which fields to return: `services`, `regions`, `resource_types`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings/metadata/latest?filter[provider_type]=aws" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns unique metadata values from the latest scan findings:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "findings-metadata",
|
||||
"id": "metadata",
|
||||
"attributes": {
|
||||
"services": ["s3", "ec2", "iam", "vpc", "cloudtrail"],
|
||||
"regions": ["us-east-1", "us-west-2", "eu-west-1"],
|
||||
"resource_types": ["aws_s3_bucket", "aws_ec2_instance", "aws_iam_role"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `services` (array of strings) - List of unique cloud services from latest scans
|
||||
- `regions` (array of strings) - List of unique regions from latest scans
|
||||
- `resource_types` (array of strings) - List of unique resource types from latest scans
|
||||
|
||||
<Note>
|
||||
This endpoint is optimized for dashboard views where you only want to show data from the most recent scans.
|
||||
</Note>
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Retrieve Findings Metadata"
|
||||
api: "GET /api/v1/findings/metadata"
|
||||
description: "Fetch unique metadata values from a set of findings. This is useful for dynamic filtering."
|
||||
---
|
||||
|
||||
Retrieve metadata values such as services, regions, and resource types from your findings. This endpoint is useful for building dynamic filters in your application.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Required Filters
|
||||
|
||||
- `filter[inserted_at]` - At least one variation of this filter is required
|
||||
- `filter[inserted_at__gte]` - Filter by creation date (greater than or equal). Maximum date range is 7 days
|
||||
- `filter[inserted_at__lte]` - Filter by creation date (less than or equal). Maximum date range is 7 days
|
||||
|
||||
### Filtering Options
|
||||
|
||||
**By Check:**
|
||||
- `filter[check_id]`, `filter[check_id__icontains]`, `filter[check_id__in]` - Filter by check ID
|
||||
|
||||
**By Status:**
|
||||
- `filter[status]` - Filter by status: `FAIL`, `PASS`, `MANUAL`
|
||||
- `filter[severity]` - Filter by severity: `critical`, `high`, `medium`, `low`, `informational`
|
||||
- `filter[delta]` - Filter by change status: `new`, `changed`
|
||||
- `filter[muted]` - Filter by mute status (boolean)
|
||||
|
||||
**By Provider:**
|
||||
- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID
|
||||
- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci`
|
||||
- `filter[provider_alias]`, `filter[provider_alias__icontains]` - Filter by provider alias
|
||||
- `filter[provider_uid]`, `filter[provider_uid__icontains]` - Filter by provider UID
|
||||
|
||||
**By Resource:**
|
||||
- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name
|
||||
- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type
|
||||
- `filter[resource_uid]`, `filter[resource_uid__icontains]` - Filter by resource UID
|
||||
- `filter[region]`, `filter[region__icontains]`, `filter[region__in]` - Filter by region
|
||||
- `filter[service]`, `filter[service__icontains]` - Filter by cloud service
|
||||
|
||||
**By Scan:**
|
||||
- `filter[scan]`, `filter[scan__in]` - Filter by scan UUID
|
||||
|
||||
### Sorting
|
||||
|
||||
- `sort` - Field to sort by: `status`, `-status`, `severity`, `-severity`, `check_id`, `-check_id`, `inserted_at`, `-inserted_at`, `updated_at`, `-updated_at`
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[findings-metadata]` - Specify which fields to return: `services`, `regions`, `resource_types`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings/metadata?filter[inserted_at__gte]=2024-01-01" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns unique metadata values from the filtered findings:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "findings-metadata",
|
||||
"id": "metadata",
|
||||
"attributes": {
|
||||
"services": ["s3", "ec2", "iam", "rds", "lambda", "cloudtrail"],
|
||||
"regions": ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"],
|
||||
"resource_types": ["aws_s3_bucket", "aws_ec2_instance", "aws_iam_user", "aws_rds_db_instance"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `services` (array of strings) - List of unique cloud services found in the findings
|
||||
- `regions` (array of strings) - List of unique regions found in the findings
|
||||
- `resource_types` (array of strings) - List of unique resource types found in the findings
|
||||
|
||||
<Note>
|
||||
This endpoint is useful for populating dropdowns and filters in your UI with actual values from your findings data. The maximum date range is 7 days.
|
||||
</Note>
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: "Retrieve Finding"
|
||||
api: "GET /api/v1/findings/{id}"
|
||||
description: "Fetch detailed information about a specific finding by its ID."
|
||||
---
|
||||
|
||||
Retrieve complete details about a specific security finding, including check metadata, raw results, and affected resources.
|
||||
|
||||
## Path Parameters
|
||||
|
||||
- `id` (required) - The UUID of the finding to retrieve
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[findings]` - Specify which fields to return: `uid`, `delta`, `status`, `status_extended`, `severity`, `check_id`, `check_metadata`, `raw_result`, `inserted_at`, `updated_at`, `first_seen_at`, `muted`, `muted_reason`, `url`, `scan`, `resources`
|
||||
|
||||
### Include Related Resources
|
||||
|
||||
- `include` - Include related resources: `scan`, `resources`
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings/{id}?include=scan,resources" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns detailed information about the finding:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "findings",
|
||||
"id": "finding-uuid",
|
||||
"attributes": {
|
||||
"uid": "prowler-aws-s3-bucket-unencrypted-123456",
|
||||
"check_id": "s3_bucket_default_encryption",
|
||||
"status": "FAIL",
|
||||
"status_extended": "S3 Bucket 'my-bucket' does not have default encryption enabled",
|
||||
"severity": "high",
|
||||
"muted": false,
|
||||
"muted_reason": null,
|
||||
"delta": "new",
|
||||
"inserted_at": "2024-01-15T10:30:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z",
|
||||
"first_seen_at": "2024-01-15T10:30:00Z",
|
||||
"check_metadata": {
|
||||
"Provider": "aws",
|
||||
"CheckID": "s3_bucket_default_encryption",
|
||||
"CheckTitle": "Check if S3 buckets have default encryption enabled",
|
||||
"CheckType": "Software and Configuration Checks",
|
||||
"ServiceName": "s3",
|
||||
"Severity": "high",
|
||||
"ResourceType": "AwsS3Bucket",
|
||||
"Description": "S3 buckets should have encryption at rest enabled...",
|
||||
"Risk": "Unencrypted S3 buckets can expose sensitive data...",
|
||||
"RelatedUrl": "https://docs.aws.amazon.com/...",
|
||||
"Remediation": {
|
||||
"Code": {
|
||||
"CLI": "aws s3api put-bucket-encryption...",
|
||||
"Terraform": "..."
|
||||
},
|
||||
"Recommendation": {
|
||||
"Text": "Enable default encryption on S3 bucket",
|
||||
"Url": "https://docs.aws.amazon.com/..."
|
||||
}
|
||||
},
|
||||
"Categories": ["encryption"]
|
||||
},
|
||||
"raw_result": {
|
||||
"finding_unique_id": "...",
|
||||
"status": "FAIL",
|
||||
"status_extended": "...",
|
||||
"raw": {}
|
||||
}
|
||||
},
|
||||
"relationships": {
|
||||
"scan": {
|
||||
"data": {
|
||||
"type": "scans",
|
||||
"id": "scan-uuid"
|
||||
}
|
||||
},
|
||||
"resources": {
|
||||
"data": [
|
||||
{
|
||||
"type": "resources",
|
||||
"id": "resource-uuid"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response Fields
|
||||
|
||||
- `uid` (string, required) - Unique identifier for the finding (max 300 characters)
|
||||
- `check_id` (string, required) - ID of the security check (max 100 characters)
|
||||
- `status` (enum, required) - Finding status: `FAIL`, `PASS`, or `MANUAL`
|
||||
- `status_extended` (string, nullable) - Detailed status message
|
||||
- `severity` (enum, required) - Severity: `critical`, `high`, `medium`, `low`, `informational`
|
||||
- `delta` (enum, nullable) - Change status: `new`, `changed`, or `null`
|
||||
- `muted` (boolean) - Whether finding is muted
|
||||
- `muted_reason` (string, nullable) - Reason for muting (3-500 characters)
|
||||
- `inserted_at` (datetime, read-only) - Creation timestamp
|
||||
- `updated_at` (datetime, read-only) - Last modification timestamp
|
||||
- `first_seen_at` (datetime, nullable, read-only) - First detection timestamp
|
||||
- `check_metadata` (object) - Complete check metadata
|
||||
- `raw_result` (object) - Raw scan output
|
||||
|
||||
### Error Responses
|
||||
|
||||
**404 Not Found** - Finding does not exist
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"status": "404",
|
||||
"title": "Not Found",
|
||||
"detail": "Finding not found"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: "Get Services and Regions"
|
||||
api: "GET /api/v1/findings/findings_services_regions"
|
||||
description: "Fetch services and regions affected in findings."
|
||||
---
|
||||
|
||||
<Warning>
|
||||
This endpoint is deprecated. Please use alternative filtering methods for retrieving services and regions information.
|
||||
</Warning>
|
||||
|
||||
Retrieve a list of unique services and regions that have findings matching the specified criteria. This is useful for populating dynamic filters in user interfaces.
|
||||
|
||||
## Query Parameters
|
||||
|
||||
### Field Selection
|
||||
|
||||
- `fields[finding-dynamic-filters]` - Specify which fields to return: `services`, `regions`
|
||||
|
||||
### Filtering
|
||||
|
||||
The endpoint supports the same filtering options as the regular findings list endpoint to scope the services and regions returned.
|
||||
|
||||
## Example Request
|
||||
|
||||
```bash
|
||||
curl -X GET "https://api.prowler.com/api/v1/findings/findings_services_regions?filter[provider_type]=aws&filter[status]=FAIL" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/vnd.api+json"
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
### Success Response (200 OK)
|
||||
|
||||
Returns unique services and regions from findings:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"type": "finding-dynamic-filters",
|
||||
"id": "filters",
|
||||
"attributes": {
|
||||
"services": ["s3", "ec2", "iam"],
|
||||
"regions": ["us-east-1", "us-west-2"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
This endpoint is deprecated. Use `/api/v1/findings/metadata` or `/api/v1/findings/metadata/latest` instead.
|
||||
</Warning>
|
||||
Reference in new issue
Block a user