mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-07-19 18:41:50 +00:00
pedrooot
106 lines
2.2 KiB
Plaintext
106 lines
2.2 KiB
Plaintext
---
|
|
title: "Create Scan"
|
|
api: "POST /api/v1/scans"
|
|
description: "Initiate a new security scan for a cloud provider."
|
|
---
|
|
|
|
Trigger a security scan to evaluate your cloud infrastructure against security checks. The scan runs asynchronously and results are available via the findings endpoints.
|
|
|
|
## Request Body
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"type": "scans",
|
|
"attributes": {
|
|
"name": "Weekly Security Audit"
|
|
},
|
|
"relationships": {
|
|
"provider": {
|
|
"data": {
|
|
"type": "providers",
|
|
"id": "provider-uuid"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Attributes
|
|
|
|
- `name` (optional, string, nullable) - Custom name for the scan (3-100 characters)
|
|
|
|
### Relationships
|
|
|
|
- `provider` (required) - The provider to scan
|
|
|
|
## Example Request
|
|
|
|
```bash
|
|
curl -X POST "https://api.prowler.com/api/v1/scans" \
|
|
-H "Authorization: Bearer YOUR_API_KEY" \
|
|
-H "Content-Type: application/vnd.api+json" \
|
|
-d '{
|
|
"data": {
|
|
"type": "scans",
|
|
"relationships": {
|
|
"provider": {
|
|
"data": {
|
|
"type": "providers",
|
|
"id": "provider-uuid"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}'
|
|
```
|
|
|
|
## Response
|
|
|
|
### Success Response (201 Created)
|
|
|
|
```json
|
|
{
|
|
"data": {
|
|
"type": "scans",
|
|
"id": "scan-uuid",
|
|
"attributes": {
|
|
"name": null,
|
|
"state": "scheduled",
|
|
"trigger": "manual",
|
|
"unique_resource_count": 0,
|
|
"progress": 0,
|
|
"duration": null,
|
|
"inserted_at": "2024-01-15T10:00:00Z",
|
|
"started_at": null,
|
|
"completed_at": null,
|
|
"scheduled_at": "2024-01-15T10:00:00Z",
|
|
"next_scan_at": null
|
|
},
|
|
"relationships": {
|
|
"provider": {
|
|
"data": {
|
|
"type": "providers",
|
|
"id": "provider-uuid"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Response Fields
|
|
|
|
- `state` - Will be `scheduled` initially, then `executing`, then `completed` or `failed`
|
|
- `trigger` - How scan was initiated (`manual` for API-created scans)
|
|
- `progress` - Percentage complete (0-100)
|
|
|
|
<Note>
|
|
Monitor the scan progress by polling `GET /api/v1/scans/{id}` and checking the `state` and `progress` fields.
|
|
</Note>
|
|
|
|
<Tip>
|
|
Scans typically complete in 3-10 minutes depending on the number of resources. Poll every 30 seconds to monitor progress.
|
|
</Tip>
|