From 77089eba57e85ca473f8d3a20a85422adf8bb0b0 Mon Sep 17 00:00:00 2001 From: pedrooot Date: Thu, 30 Oct 2025 18:58:05 +0100 Subject: [PATCH] docs(api): use mintlify for API specs --- docs/api-reference/README.md | 335 + docs/api-reference/api-keys/create.mdx | 182 + docs/api-reference/api-keys/list.mdx | 124 + docs/api-reference/api-keys/retrieve.mdx | 89 + docs/api-reference/api-keys/revoke.mdx | 86 + docs/api-reference/api-keys/update.mdx | 88 + docs/api-reference/compliance/attributes.mdx | 7 + docs/api-reference/compliance/list.mdx | 17 + docs/api-reference/compliance/metadata.mdx | 7 + .../api-reference/compliance/requirements.mdx | 7 + docs/api-reference/findings/latest.mdx | 109 + docs/api-reference/findings/list.mdx | 287 + .../findings/metadata-latest.mdx | 79 + docs/api-reference/findings/metadata.mdx | 88 + docs/api-reference/findings/retrieve.mdx | 133 + .../findings/services-regions.mdx | 52 + .../integrations/check-connection.mdx | 45 + docs/api-reference/integrations/create.mdx | 7 + docs/api-reference/integrations/delete.mdx | 7 + .../integrations/jira-dispatch.mdx | 7 + docs/api-reference/integrations/list.mdx | 7 + docs/api-reference/integrations/retrieve.mdx | 7 + docs/api-reference/integrations/update.mdx | 7 + docs/api-reference/introduction.mdx | 121 + docs/api-reference/invitations/accept.mdx | 50 + docs/api-reference/lighthouse/config-list.mdx | 7 + .../lighthouse/config-update.mdx | 7 + .../lighthouse/configuration-get.mdx | 19 + .../lighthouse/configuration-update.mdx | 37 + .../lighthouse/configurations/create.mdx | 7 + .../lighthouse/configurations/delete.mdx | 7 + .../lighthouse/configurations/list.mdx | 7 + .../lighthouse/configurations/retrieve.mdx | 7 + .../configurations/test-connection.mdx | 7 + .../lighthouse/configurations/update.mdx | 7 + docs/api-reference/lighthouse/models-list.mdx | 25 + docs/api-reference/lighthouse/models/list.mdx | 7 + .../lighthouse/models/retrieve.mdx | 7 + .../lighthouse/providers-create.mdx | 40 + .../lighthouse/providers-list.mdx | 25 + .../lighthouse/providers/create.mdx | 21 + .../lighthouse/providers/delete.mdx | 7 + .../lighthouse/providers/list.mdx | 7 + .../lighthouse/providers/refresh-models.mdx | 7 + .../lighthouse/providers/retrieve.mdx | 7 + .../lighthouse/providers/test-connection.mdx | 7 + .../lighthouse/providers/update.mdx | 7 + docs/api-reference/openapi.yaml | 18070 ++++++++++++++++ .../overviews/findings-severity.mdx | 7 + docs/api-reference/overviews/findings.mdx | 7 + .../overviews/providers-count.mdx | 7 + docs/api-reference/overviews/providers.mdx | 7 + docs/api-reference/overviews/services.mdx | 7 + docs/api-reference/processors/create.mdx | 7 + docs/api-reference/processors/delete.mdx | 7 + docs/api-reference/processors/list.mdx | 7 + docs/api-reference/processors/retrieve.mdx | 7 + docs/api-reference/processors/update.mdx | 7 + .../provider-groups/add-providers.mdx | 7 + docs/api-reference/provider-groups/create.mdx | 20 + docs/api-reference/provider-groups/delete.mdx | 7 + docs/api-reference/provider-groups/list.mdx | 17 + .../provider-groups/remove-providers.mdx | 7 + .../provider-groups/retrieve.mdx | 7 + .../provider-groups/update-providers.mdx | 7 + docs/api-reference/provider-groups/update.mdx | 7 + .../providers/check-connection.mdx | 27 + docs/api-reference/providers/create.mdx | 293 + docs/api-reference/providers/delete.mdx | 27 + docs/api-reference/providers/list.mdx | 120 + docs/api-reference/providers/retrieve.mdx | 101 + .../providers/secrets/create.mdx | 266 + .../providers/secrets/delete.mdx | 73 + docs/api-reference/providers/secrets/list.mdx | 133 + .../providers/secrets/retrieve.mdx | 96 + .../providers/secrets/update.mdx | 168 + docs/api-reference/providers/update.mdx | 123 + docs/api-reference/resources/latest.mdx | 42 + docs/api-reference/resources/list.mdx | 43 + .../resources/metadata-latest.mdx | 29 + docs/api-reference/resources/metadata.mdx | 32 + docs/api-reference/resources/retrieve.mdx | 23 + .../roles/add-provider-groups.mdx | 7 + docs/api-reference/roles/create.mdx | 20 + docs/api-reference/roles/delete.mdx | 7 + docs/api-reference/roles/list.mdx | 7 + .../roles/remove-provider-groups.mdx | 7 + docs/api-reference/roles/retrieve.mdx | 7 + .../roles/update-provider-groups.mdx | 7 + docs/api-reference/roles/update.mdx | 7 + docs/api-reference/saml/create.mdx | 21 + docs/api-reference/saml/delete.mdx | 7 + docs/api-reference/saml/list.mdx | 7 + docs/api-reference/saml/retrieve.mdx | 7 + docs/api-reference/saml/update.mdx | 7 + docs/api-reference/scans/compliance.mdx | 28 + docs/api-reference/scans/create.mdx | 105 + docs/api-reference/scans/list.mdx | 207 + docs/api-reference/scans/report.mdx | 32 + docs/api-reference/scans/retrieve.mdx | 29 + docs/api-reference/scans/threatscore.mdx | 27 + docs/api-reference/scans/update.mdx | 35 + docs/api-reference/schedules/create-daily.mdx | 7 + docs/api-reference/schedules/daily.mdx | 39 + docs/api-reference/tasks/delete.mdx | 7 + docs/api-reference/tasks/list.mdx | 7 + docs/api-reference/tasks/retrieve.mdx | 7 + docs/api-reference/tenants/create.mdx | 7 + docs/api-reference/tenants/delete.mdx | 7 + .../tenants/invitations-create.mdx | 42 + .../tenants/invitations-list.mdx | 19 + .../tenants/invitations/delete.mdx | 7 + .../tenants/invitations/retrieve.mdx | 7 + .../tenants/invitations/update.mdx | 7 + docs/api-reference/tenants/list.mdx | 19 + .../tenants/memberships/delete.mdx | 7 + .../tenants/memberships/list.mdx | 7 + docs/api-reference/tenants/retrieve.mdx | 7 + docs/api-reference/tenants/update.mdx | 7 + docs/api-reference/tokens/create.mdx | 201 + docs/api-reference/tokens/refresh.mdx | 43 + docs/api-reference/tokens/switch.mdx | 40 + docs/api-reference/users/add-roles.mdx | 7 + docs/api-reference/users/create.mdx | 20 + docs/api-reference/users/delete.mdx | 7 + docs/api-reference/users/list.mdx | 7 + docs/api-reference/users/me.mdx | 23 + docs/api-reference/users/memberships-list.mdx | 7 + .../users/memberships-retrieve.mdx | 7 + docs/api-reference/users/remove-roles.mdx | 7 + docs/api-reference/users/retrieve.mdx | 7 + docs/api-reference/users/update-roles.mdx | 7 + docs/api-reference/users/update.mdx | 7 + docs/docs.json | 275 + docs/generate-api-docs.py | 409 + docs/sync-api-spec.sh | 62 + 136 files changed, 23969 insertions(+) create mode 100644 docs/api-reference/README.md create mode 100644 docs/api-reference/api-keys/create.mdx create mode 100644 docs/api-reference/api-keys/list.mdx create mode 100644 docs/api-reference/api-keys/retrieve.mdx create mode 100644 docs/api-reference/api-keys/revoke.mdx create mode 100644 docs/api-reference/api-keys/update.mdx create mode 100644 docs/api-reference/compliance/attributes.mdx create mode 100644 docs/api-reference/compliance/list.mdx create mode 100644 docs/api-reference/compliance/metadata.mdx create mode 100644 docs/api-reference/compliance/requirements.mdx create mode 100644 docs/api-reference/findings/latest.mdx create mode 100644 docs/api-reference/findings/list.mdx create mode 100644 docs/api-reference/findings/metadata-latest.mdx create mode 100644 docs/api-reference/findings/metadata.mdx create mode 100644 docs/api-reference/findings/retrieve.mdx create mode 100644 docs/api-reference/findings/services-regions.mdx create mode 100644 docs/api-reference/integrations/check-connection.mdx create mode 100644 docs/api-reference/integrations/create.mdx create mode 100644 docs/api-reference/integrations/delete.mdx create mode 100644 docs/api-reference/integrations/jira-dispatch.mdx create mode 100644 docs/api-reference/integrations/list.mdx create mode 100644 docs/api-reference/integrations/retrieve.mdx create mode 100644 docs/api-reference/integrations/update.mdx create mode 100644 docs/api-reference/introduction.mdx create mode 100644 docs/api-reference/invitations/accept.mdx create mode 100644 docs/api-reference/lighthouse/config-list.mdx create mode 100644 docs/api-reference/lighthouse/config-update.mdx create mode 100644 docs/api-reference/lighthouse/configuration-get.mdx create mode 100644 docs/api-reference/lighthouse/configuration-update.mdx create mode 100644 docs/api-reference/lighthouse/configurations/create.mdx create mode 100644 docs/api-reference/lighthouse/configurations/delete.mdx create mode 100644 docs/api-reference/lighthouse/configurations/list.mdx create mode 100644 docs/api-reference/lighthouse/configurations/retrieve.mdx create mode 100644 docs/api-reference/lighthouse/configurations/test-connection.mdx create mode 100644 docs/api-reference/lighthouse/configurations/update.mdx create mode 100644 docs/api-reference/lighthouse/models-list.mdx create mode 100644 docs/api-reference/lighthouse/models/list.mdx create mode 100644 docs/api-reference/lighthouse/models/retrieve.mdx create mode 100644 docs/api-reference/lighthouse/providers-create.mdx create mode 100644 docs/api-reference/lighthouse/providers-list.mdx create mode 100644 docs/api-reference/lighthouse/providers/create.mdx create mode 100644 docs/api-reference/lighthouse/providers/delete.mdx create mode 100644 docs/api-reference/lighthouse/providers/list.mdx create mode 100644 docs/api-reference/lighthouse/providers/refresh-models.mdx create mode 100644 docs/api-reference/lighthouse/providers/retrieve.mdx create mode 100644 docs/api-reference/lighthouse/providers/test-connection.mdx create mode 100644 docs/api-reference/lighthouse/providers/update.mdx create mode 100644 docs/api-reference/openapi.yaml create mode 100644 docs/api-reference/overviews/findings-severity.mdx create mode 100644 docs/api-reference/overviews/findings.mdx create mode 100644 docs/api-reference/overviews/providers-count.mdx create mode 100644 docs/api-reference/overviews/providers.mdx create mode 100644 docs/api-reference/overviews/services.mdx create mode 100644 docs/api-reference/processors/create.mdx create mode 100644 docs/api-reference/processors/delete.mdx create mode 100644 docs/api-reference/processors/list.mdx create mode 100644 docs/api-reference/processors/retrieve.mdx create mode 100644 docs/api-reference/processors/update.mdx create mode 100644 docs/api-reference/provider-groups/add-providers.mdx create mode 100644 docs/api-reference/provider-groups/create.mdx create mode 100644 docs/api-reference/provider-groups/delete.mdx create mode 100644 docs/api-reference/provider-groups/list.mdx create mode 100644 docs/api-reference/provider-groups/remove-providers.mdx create mode 100644 docs/api-reference/provider-groups/retrieve.mdx create mode 100644 docs/api-reference/provider-groups/update-providers.mdx create mode 100644 docs/api-reference/provider-groups/update.mdx create mode 100644 docs/api-reference/providers/check-connection.mdx create mode 100644 docs/api-reference/providers/create.mdx create mode 100644 docs/api-reference/providers/delete.mdx create mode 100644 docs/api-reference/providers/list.mdx create mode 100644 docs/api-reference/providers/retrieve.mdx create mode 100644 docs/api-reference/providers/secrets/create.mdx create mode 100644 docs/api-reference/providers/secrets/delete.mdx create mode 100644 docs/api-reference/providers/secrets/list.mdx create mode 100644 docs/api-reference/providers/secrets/retrieve.mdx create mode 100644 docs/api-reference/providers/secrets/update.mdx create mode 100644 docs/api-reference/providers/update.mdx create mode 100644 docs/api-reference/resources/latest.mdx create mode 100644 docs/api-reference/resources/list.mdx create mode 100644 docs/api-reference/resources/metadata-latest.mdx create mode 100644 docs/api-reference/resources/metadata.mdx create mode 100644 docs/api-reference/resources/retrieve.mdx create mode 100644 docs/api-reference/roles/add-provider-groups.mdx create mode 100644 docs/api-reference/roles/create.mdx create mode 100644 docs/api-reference/roles/delete.mdx create mode 100644 docs/api-reference/roles/list.mdx create mode 100644 docs/api-reference/roles/remove-provider-groups.mdx create mode 100644 docs/api-reference/roles/retrieve.mdx create mode 100644 docs/api-reference/roles/update-provider-groups.mdx create mode 100644 docs/api-reference/roles/update.mdx create mode 100644 docs/api-reference/saml/create.mdx create mode 100644 docs/api-reference/saml/delete.mdx create mode 100644 docs/api-reference/saml/list.mdx create mode 100644 docs/api-reference/saml/retrieve.mdx create mode 100644 docs/api-reference/saml/update.mdx create mode 100644 docs/api-reference/scans/compliance.mdx create mode 100644 docs/api-reference/scans/create.mdx create mode 100644 docs/api-reference/scans/list.mdx create mode 100644 docs/api-reference/scans/report.mdx create mode 100644 docs/api-reference/scans/retrieve.mdx create mode 100644 docs/api-reference/scans/threatscore.mdx create mode 100644 docs/api-reference/scans/update.mdx create mode 100644 docs/api-reference/schedules/create-daily.mdx create mode 100644 docs/api-reference/schedules/daily.mdx create mode 100644 docs/api-reference/tasks/delete.mdx create mode 100644 docs/api-reference/tasks/list.mdx create mode 100644 docs/api-reference/tasks/retrieve.mdx create mode 100644 docs/api-reference/tenants/create.mdx create mode 100644 docs/api-reference/tenants/delete.mdx create mode 100644 docs/api-reference/tenants/invitations-create.mdx create mode 100644 docs/api-reference/tenants/invitations-list.mdx create mode 100644 docs/api-reference/tenants/invitations/delete.mdx create mode 100644 docs/api-reference/tenants/invitations/retrieve.mdx create mode 100644 docs/api-reference/tenants/invitations/update.mdx create mode 100644 docs/api-reference/tenants/list.mdx create mode 100644 docs/api-reference/tenants/memberships/delete.mdx create mode 100644 docs/api-reference/tenants/memberships/list.mdx create mode 100644 docs/api-reference/tenants/retrieve.mdx create mode 100644 docs/api-reference/tenants/update.mdx create mode 100644 docs/api-reference/tokens/create.mdx create mode 100644 docs/api-reference/tokens/refresh.mdx create mode 100644 docs/api-reference/tokens/switch.mdx create mode 100644 docs/api-reference/users/add-roles.mdx create mode 100644 docs/api-reference/users/create.mdx create mode 100644 docs/api-reference/users/delete.mdx create mode 100644 docs/api-reference/users/list.mdx create mode 100644 docs/api-reference/users/me.mdx create mode 100644 docs/api-reference/users/memberships-list.mdx create mode 100644 docs/api-reference/users/memberships-retrieve.mdx create mode 100644 docs/api-reference/users/remove-roles.mdx create mode 100644 docs/api-reference/users/retrieve.mdx create mode 100644 docs/api-reference/users/update-roles.mdx create mode 100644 docs/api-reference/users/update.mdx create mode 100755 docs/generate-api-docs.py create mode 100755 docs/sync-api-spec.sh diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md new file mode 100644 index 0000000000..42f9bae3c7 --- /dev/null +++ b/docs/api-reference/README.md @@ -0,0 +1,335 @@ +# Prowler API Reference Documentation + +This directory contains the API reference documentation for Prowler Cloud, integrated with Mintlify. + +## Structure + +``` +api-reference/ +├── README.md # This file +├── openapi.yaml # OpenAPI specification (auto-synced from api/src/backend/api/specs/v1.yaml) +├── introduction.mdx # API introduction and getting started guide +│ +├── tokens/ # Authentication endpoints +│ ├── create.mdx # Create JWT token +│ ├── refresh.mdx # Refresh JWT token +│ └── switch.mdx # Switch tenant context +│ +├── api-keys/ # API Keys endpoints +│ ├── list.mdx +│ ├── create.mdx +│ ├── retrieve.mdx +│ ├── update.mdx +│ └── revoke.mdx +│ +├── users/ # User endpoints +│ └── me.mdx # Get current user +│ +├── tenants/ # Tenant management +│ ├── list.mdx +│ ├── invitations-list.mdx +│ └── invitations-create.mdx +│ +├── invitations/ # Invitation endpoints +│ └── accept.mdx +│ +├── providers/ # Cloud provider management +│ ├── list.mdx +│ ├── create.mdx +│ ├── retrieve.mdx +│ ├── update.mdx +│ ├── delete.mdx +│ └── check-connection.mdx +│ +├── scans/ # Security scan endpoints +│ ├── list.mdx +│ ├── retrieve.mdx +│ ├── compliance.mdx +│ ├── report.mdx +│ └── threatscore.mdx +│ +├── findings/ # Security findings endpoints +│ ├── list.mdx +│ ├── retrieve.mdx +│ ├── latest.mdx +│ ├── services-regions.mdx +│ ├── metadata.mdx +│ └── metadata-latest.mdx +│ +├── resources/ # Cloud resource endpoints +│ ├── list.mdx +│ ├── retrieve.mdx +│ ├── latest.mdx +│ ├── metadata.mdx +│ └── metadata-latest.mdx +│ +├── compliance/ # Compliance framework endpoints +│ ├── list.mdx +│ ├── requirements.mdx +│ ├── attributes.mdx +│ └── metadata.mdx +│ +├── overviews/ # Dashboard overview endpoints +│ ├── findings.mdx +│ ├── findings-severity.mdx +│ ├── providers.mdx +│ ├── providers-count.mdx +│ └── services.mdx +│ +├── integrations/ # External integrations +│ ├── list.mdx +│ ├── create.mdx +│ ├── retrieve.mdx +│ ├── update.mdx +│ ├── delete.mdx +│ ├── check-connection.mdx +│ └── jira-dispatch.mdx +│ +├── lighthouse/ # Lighthouse AI endpoints +│ ├── configuration-get.mdx +│ ├── configuration-update.mdx +│ ├── providers-list.mdx +│ ├── providers-create.mdx +│ └── models-list.mdx +│ +├── processors/ # Finding processors (mutelists) +│ ├── list.mdx +│ └── create.mdx +│ +├── schedules/ # Automated scan scheduling +│ └── daily.mdx +│ +└── tasks/ # Asynchronous task management + ├── list.mdx + └── retrieve.mdx +``` + +**Total: 131 endpoint documentation files organized in 18 groups** + +✅ **100% API Coverage** - All 123 operation IDs documented + +## How It Works + +The API documentation uses Mintlify's native OpenAPI support to automatically generate interactive API documentation from the OpenAPI specification file. + +### Components + +1. **openapi.yaml**: The source of truth for API endpoints, copied from `api/src/backend/api/specs/v1.yaml` +2. **MDX files**: Enhanced documentation for each endpoint with examples, tips, and additional context +3. **docs.json**: Mintlify configuration that references the OpenAPI spec + +## Updating the Documentation + +### When the API Spec Changes + +When you update the OpenAPI specification in `api/src/backend/api/specs/v1.yaml`, you need to sync it to the docs: + +```bash +# From the root of the repository +cp api/src/backend/api/specs/v1.yaml docs/api-reference/openapi.yaml +``` + +Consider automating this with a pre-commit hook or CI/CD pipeline. + +### Adding New Endpoints + +To document a new API endpoint: + +1. **Update the OpenAPI spec** in `api/src/backend/api/specs/v1.yaml` +2. **Sync to docs**: Copy the spec to `docs/api-reference/openapi.yaml` +3. **Create MDX file**: Create a new `.mdx` file in the appropriate directory +4. **Update navigation**: Add the new page to `docs/docs.json` in the API Reference tab + +#### MDX File Template + +```mdx +--- +title: "Endpoint Title" +api: "METHOD /api/v1/endpoint" +description: "Brief description of what this endpoint does." +--- + +Detailed description of the endpoint. + +## Path Parameters + +- `param` (required/optional) - Description + +## Query Parameters + +- `param` (required/optional) - Description + +## Request Body + +```json +{ + "example": "request" +} +``` + +## Example Request + +```bash +curl -X METHOD "https://api.prowler.com/api/v1/endpoint" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Description of the response. +``` + +### Testing Changes Locally + +To preview documentation changes locally: + +```bash +cd docs +mintlify dev +``` + +Then open http://localhost:3000 in your browser. + +## Mintlify Configuration + +The API documentation is configured in `docs/docs.json`: + +- **openapi**: Points to the OpenAPI spec file +- **api.baseUrl**: The base URL for the API +- **api.auth.method**: Authentication method (bearer token) +- **api.playground.mode**: Interactive API playground mode + +## API Endpoint Groups + +### Core Endpoints +- **Authentication (3)**: JWT token management and tenant switching +- **API Keys (5)**: Programmatic API access management +- **Users (1)**: User profile and information +- **Tenants (3)**: Organization and invitation management + +### Cloud Infrastructure +- **Providers (6)**: Cloud provider (AWS, Azure, GCP, etc.) configuration +- **Scans (5)**: Security scan execution and results +- **Findings (6)**: Security findings and vulnerabilities +- **Resources (5)**: Cloud resource inventory and metadata + +### Compliance & Reporting +- **Compliance (4)**: Compliance framework assessments (CIS, PCI-DSS, etc.) +- **Overviews (5)**: Dashboard aggregated statistics + +### Integrations & Automation +- **Integrations (7)**: External service integrations (S3, Security Hub, JIRA, Slack) +- **Lighthouse AI (5)**: AI-powered security insights configuration +- **Processors (2)**: Finding processors and mutelists +- **Schedules (1)**: Automated scan scheduling + +### System +- **Tasks (2)**: Asynchronous task monitoring + +## Best Practices + +1. **Keep OpenAPI spec up to date**: Always update the source spec first, then sync to docs +2. **Add examples**: Include real-world examples in MDX files +3. **Use callouts**: Leverage Mintlify components like ``, ``, `` for important information +4. **Test playground**: Verify that the interactive API playground works for each endpoint +5. **Document filters**: For list endpoints, clearly document all available filters +6. **Include rate limits**: Document any rate limiting or pagination requirements +7. **Group related endpoints**: Keep related endpoints in the same directory +8. **Use consistent naming**: Follow the pattern `action.mdx` (e.g., `list.mdx`, `create.mdx`, `retrieve.mdx`) + +## Resources + +- [Mintlify OpenAPI Guide](https://mintlify.com/docs/api-playground/openapi-support) +- [Mintlify Components](https://mintlify.com/docs/content/components) +- [JSON:API Specification](https://jsonapi.org/) +- [Prowler Cloud API](https://api.prowler.com/api/v1/docs) + +## Syncing OpenAPI Spec + +The OpenAPI specification is maintained in the API repository and should be synced regularly: + +```bash +# Using the provided sync script +cd docs +./sync-api-spec.sh + +# Or manually +cp ../api/src/backend/api/specs/v1.yaml ./api-reference/openapi.yaml +``` + +The `sync-api-spec.sh` script automates this process and can be integrated into your CI/CD pipeline. + +## Automation 🤖 + +**NEW**: Documentation can now be auto-generated from the OpenAPI specification! + +### Quick Start with Automation + +```bash +cd docs + +# 1. Sync latest OpenAPI spec from GitHub +./sync-api-spec.sh + +# 2. Generate MDX files automatically +python3 generate-api-docs.py + +# 3. Test locally +mintlify dev +``` + +### Available Scripts + +1. **`sync-api-spec.sh`** - Downloads latest OpenAPI spec from GitHub +2. **`generate-api-docs.py`** - Generates/updates MDX files from OpenAPI spec + +### Features + +- ✅ Auto-generate MDX files from OpenAPI spec +- ✅ Update existing or create new endpoints +- ✅ Dry-run mode to preview changes +- ✅ Proper directory structure and naming +- ✅ Frontmatter generation (title, API path, description) +- ✅ Parameter documentation extraction +- ✅ Request/response examples + +### Documentation + +See **[AUTOMATION.md](./AUTOMATION.md)** for complete automation guide including: +- Detailed usage instructions +- CI/CD integration examples +- Troubleshooting +- Best practices + +## Recent Updates + +### January 2025 - Complete API Documentation & Automation + +#### Documentation Expansion +- ✅ **100% Coverage**: All 123 operation IDs documented (131 MDX files) +- ✅ **18 Endpoint Groups**: Complete organization +- ✅ **New Groups Added**: + - Provider Secrets (5 endpoints) + - Provider Groups (8 endpoints) + - Roles (8 endpoints) + - SAML Configuration (5 endpoints) + - Lighthouse AI expanded (17 endpoints with nested structure) + - Processors (5 endpoints) + - Tasks (3 endpoints) + - Compliance Overview (4 endpoints) + - Overviews (5 endpoints) + +#### Automation Implementation +- ✅ **Auto-generation script**: `generate-api-docs.py` +- ✅ **Sync script**: `sync-api-spec.sh` +- ✅ **Complete automation guide**: AUTOMATION.md +- ✅ **CI/CD ready**: GitHub Actions example included + +#### Quality Improvements +- ✅ Field name corrections verified against OpenAPI spec +- ✅ JSON:API compliance in all examples +- ✅ Proper nested structures (Provider Secrets, Tenant Memberships/Invitations) +- ✅ Comprehensive documentation files (CORRECTIONS.md, VERIFICATION.md, IMPROVEMENTS.md) + +**Total coverage increased from 14 to 131 documented endpoints (843% increase)** diff --git a/docs/api-reference/api-keys/create.mdx b/docs/api-reference/api-keys/create.mdx new file mode 100644 index 0000000000..74ae4e7fb1 --- /dev/null +++ b/docs/api-reference/api-keys/create.mdx @@ -0,0 +1,182 @@ +--- +title: "Create API Key" +api: "POST /api/v1/api-keys" +description: "Create a new API key for the tenant." +--- + +Create a new API key for programmatic access to the Prowler API. The API key will be returned in the response and should be stored securely as it cannot be retrieved later. + +## Request Body + +The request must follow the JSON:API specification format: + +```json +{ + "data": { + "type": "api-keys", + "attributes": { + "name": "string", + "expires_at": "2024-12-31T23:59:59Z" + } + } +} +``` + +### Attributes + +- `name` (required) - A descriptive name for the API key +- `expires_at` (optional) - Expiration date for the API key in ISO 8601 format + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/api-keys" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "api-keys", + "attributes": { + "name": "Production API Key", + "expires_at": "2025-12-31T23:59:59Z" + } + } + }' +``` + +## Response + +### Success Response (201 Created) + +Returns the created API key **including the full key value** (only shown once): + +```json +{ + "data": { + "type": "api-keys", + "id": "api-key-uuid", + "attributes": { + "name": "Production API Key", + "prefix": "pk_live_abc123", + "api_key": "pk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz", + "expires_at": "2025-12-31T23:59:59Z", + "revoked": false, + "inserted_at": "2024-01-15T10:30:00Z", + "last_used_at": null + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + } +} +``` + +### Response Fields + +- `id` - Unique UUID for the API key record +- `name` - Descriptive name you provided (3-100 characters) +- `prefix` - First characters of the key (for identification, read-only) +- `api_key` - **Full API key value** (only returned on creation, read-only) +- `expires_at` - Expiration date in ISO 8601 format (optional) +- `revoked` - Whether key has been revoked (always false on creation, read-only) +- `inserted_at` - When key was created (read-only) +- `last_used_at` - Last usage timestamp (null initially, read-only) + +### Error Responses + +**400 Bad Request** - Invalid expiration date +```json +{ + "errors": [ + { + "status": "400", + "title": "Invalid Expiration Date", + "detail": "Expiration date must be in the future" + } + ] +} +``` + +**422 Unprocessable Entity** - Missing required fields +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "Name is required", + "source": { + "pointer": "/data/attributes/name" + } + } + ] +} +``` + +**429 Too Many Requests** - API key limit reached +```json +{ + "errors": [ + { + "status": "429", + "title": "API Key Limit Exceeded", + "detail": "Maximum of 10 active API keys per tenant. Revoke unused keys to create new ones." + } + ] +} +``` + +## Usage Example + +After creating the API key, use it to authenticate API requests: + +```bash +# Save the API key +API_KEY="pk_live_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz" + +# Use it in requests +curl -X GET "https://api.prowler.com/api/v1/providers" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Security Best Practices + +1. **Store Securely**: Save the API key in a secure location immediately (password manager, secrets vault, environment variables) +2. **Never Commit**: Do not commit API keys to version control systems +3. **Use Environment Variables**: Store keys in environment variables, not in code +4. **Set Expiration**: Always set an expiration date for API keys (recommended: 90 days) +5. **Rotate Regularly**: Rotate API keys every 90 days +6. **Limit Scope**: Use separate API keys for different environments (dev, staging, production) +7. **Monitor Usage**: Regularly check `last_used_at` to identify unused keys +8. **Revoke Unused**: Revoke API keys that are no longer needed + +## Naming Conventions + +Use descriptive names that include: +- **Environment**: Production, Staging, Development +- **Purpose**: CI/CD, Dashboard, Integration +- **Owner/Team**: Security Team, DevOps, Monitoring + +Examples: +- "Production CI/CD Pipeline" +- "Staging Dashboard API Access" +- "Security Team Automation" +- "JIRA Integration - Production" + + +**CRITICAL:** The API key is only shown once in the creation response. It cannot be retrieved later. If you lose the key, you must revoke it and create a new one. Store it securely immediately after creation. + + + +API keys have the same permissions as the user who created them. For automated systems, consider creating a dedicated service account with limited permissions. + + + +**Automation Tip:** API keys are ideal for CI/CD pipelines, scheduled scans, and integrations. Unlike JWT tokens, they don't expire hourly and don't require refresh logic. + diff --git a/docs/api-reference/api-keys/list.mdx b/docs/api-reference/api-keys/list.mdx new file mode 100644 index 0000000000..e2eca038e2 --- /dev/null +++ b/docs/api-reference/api-keys/list.mdx @@ -0,0 +1,124 @@ +--- +title: "List API Keys" +api: "GET /api/v1/api-keys" +description: "Retrieve a list of API keys for the tenant, with filtering support." +--- + +Retrieve a list of all API keys associated with your tenant. This endpoint supports various filtering options to help you find specific keys. + +## Query Parameters + +### Filtering + +- `filter[name]` - Filter by exact API key name +- `filter[name__icontains]` - Filter by API key name (case-insensitive) +- `filter[prefix]` - Filter by API key prefix +- `filter[revoked]` - Filter by revocation status (boolean) +- `filter[expires_at]`, `filter[expires_at__gte]`, `filter[expires_at__lte]` - Filter by expiration date +- `filter[inserted_at]`, `filter[inserted_at__gte]`, `filter[inserted_at__lte]` - Filter by creation date +- `filter[search]` - General search term + +### Pagination + +- `page[number]` - Page number to retrieve +- `page[size]` - Number of results per page + +### Sorting + +- `sort` - Field to sort by. Available options: `name`, `-name`, `prefix`, `-prefix`, `revoked`, `-revoked`, `inserted_at`, `-inserted_at`, `expires_at`, `-expires_at` + +### Field Selection + +- `fields[api-keys]` - Specify which fields to return: `name`, `prefix`, `expires_at`, `revoked`, `inserted_at`, `last_used_at`, `entity` + +### Include Related Resources + +- `include` - Include related resources. Available: `entity` + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/api-keys?page[size]=10&sort=-inserted_at" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns a paginated list of API keys with their metadata: + +```json +{ + "data": [ + { + "type": "api-keys", + "id": "api-key-uuid-1", + "attributes": { + "name": "Production CI/CD Pipeline", + "prefix": "pk_live_abc123", + "expires_at": "2025-12-31T23:59:59Z", + "revoked": false, + "inserted_at": "2024-01-15T10:30:00Z", + "last_used_at": "2024-01-20T14:22:00Z" + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + }, + { + "type": "api-keys", + "id": "api-key-uuid-2", + "attributes": { + "name": "Staging Dashboard API Access", + "prefix": "pk_live_def456", + "expires_at": null, + "revoked": false, + "inserted_at": "2024-01-10T08:15:00Z", + "last_used_at": null + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + } + ], + "meta": { + "page": { + "number": 1, + "size": 20, + "total": 2, + "total_pages": 1 + } + }, + "links": { + "self": "https://api.prowler.com/api/v1/api-keys?page[number]=1", + "first": "https://api.prowler.com/api/v1/api-keys?page[number]=1", + "last": "https://api.prowler.com/api/v1/api-keys?page[number]=1" + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the API key record +- `name` (string) - Descriptive name (3-100 characters) +- `prefix` (string, read-only) - First characters of the key for identification +- `expires_at` (datetime, nullable) - Expiration date in ISO 8601 format +- `revoked` (boolean, read-only) - Whether key has been revoked +- `inserted_at` (datetime, read-only) - When key was created +- `last_used_at` (datetime, nullable, read-only) - Last usage timestamp + + +The full API key value is never returned after creation. Only the prefix is shown for identification purposes. + diff --git a/docs/api-reference/api-keys/retrieve.mdx b/docs/api-reference/api-keys/retrieve.mdx new file mode 100644 index 0000000000..a7ffc70705 --- /dev/null +++ b/docs/api-reference/api-keys/retrieve.mdx @@ -0,0 +1,89 @@ +--- +title: "Retrieve API Key" +api: "GET /api/v1/api-keys/{id}" +description: "Fetch detailed information about a specific API key by its ID." +--- + +Retrieve detailed information about a specific API key. Note that the full API key value is never returned, only metadata about the key. + +## Path Parameters + +- `id` (required) - The UUID of the API key to retrieve + +## Query Parameters + +### Field Selection + +- `fields[api-keys]` - Specify which fields to return: `name`, `prefix`, `expires_at`, `revoked`, `inserted_at`, `last_used_at`, `entity` + +### Include Related Resources + +- `include` - Include related resources. Available: `entity` + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/api-keys/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns detailed metadata about the API key: + +```json +{ + "data": { + "type": "api-keys", + "id": "api-key-uuid", + "attributes": { + "name": "Production CI/CD Pipeline", + "prefix": "pk_live_abc123", + "expires_at": "2025-12-31T23:59:59Z", + "revoked": false, + "inserted_at": "2024-01-15T10:30:00Z", + "last_used_at": "2024-01-20T14:22:00Z" + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the API key record +- `name` (string) - Descriptive name (3-100 characters) +- `prefix` (string, read-only) - First characters of the key for identification +- `expires_at` (datetime, nullable) - Expiration date in ISO 8601 format +- `revoked` (boolean, read-only) - Whether key has been revoked +- `inserted_at` (datetime, read-only) - When key was created +- `last_used_at` (datetime, nullable, read-only) - Last usage timestamp + +### Error Responses + +**404 Not Found** - API key does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "API key not found" + } + ] +} +``` + + +The full API key value is never returned after creation. Only the prefix is shown for identification purposes. + diff --git a/docs/api-reference/api-keys/revoke.mdx b/docs/api-reference/api-keys/revoke.mdx new file mode 100644 index 0000000000..8d52122a99 --- /dev/null +++ b/docs/api-reference/api-keys/revoke.mdx @@ -0,0 +1,86 @@ +--- +title: "Revoke API Key" +api: "DELETE /api/v1/api-keys/{id}/revoke" +description: "Revoke an API key by its ID. This action is irreversible." +--- + +Revoke an API key, preventing it from being used for further API requests. This action cannot be undone. + +## Path Parameters + +- `id` (required) - The UUID of the API key to revoke + +## Example Request + +```bash +curl -X DELETE "https://api.prowler.com/api/v1/api-keys/{id}/revoke" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns the API key with `revoked` status set to `true`: + +```json +{ + "data": { + "type": "api-keys", + "id": "api-key-uuid", + "attributes": { + "name": "Production CI/CD Pipeline", + "prefix": "pk_live_abc123", + "expires_at": "2025-12-31T23:59:59Z", + "revoked": true, + "inserted_at": "2024-01-15T10:30:00Z", + "last_used_at": "2024-01-20T14:22:00Z" + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + } +} +``` + +### Error Responses + +**404 Not Found** - API key does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "API key not found" + } + ] +} +``` + +**409 Conflict** - API key already revoked +```json +{ + "errors": [ + { + "status": "409", + "title": "Already Revoked", + "detail": "This API key has already been revoked" + } + ] +} +``` + + +Revoking an API key is permanent and cannot be undone. Any applications using this key will immediately lose access. The `revoked` field will be set to `true` and the key will no longer authenticate API requests. + + + +Monitor the `last_used_at` field before revoking to ensure the key is no longer in active use. + diff --git a/docs/api-reference/api-keys/update.mdx b/docs/api-reference/api-keys/update.mdx new file mode 100644 index 0000000000..1249f3328c --- /dev/null +++ b/docs/api-reference/api-keys/update.mdx @@ -0,0 +1,88 @@ +--- +title: "Update API Key" +api: "PATCH /api/v1/api-keys/{id}" +description: "Modify certain fields of an existing API key without affecting other settings." +--- + +Partially update an API key's properties. This endpoint allows you to modify the name or expiration date without affecting other settings. + +## Path Parameters + +- `id` (required) - The UUID of the API key to update + +## Request Body + +The request must follow the JSON:API specification format: + +```json +{ + "data": { + "type": "api-keys", + "id": "string", + "attributes": { + "name": "string", + "expires_at": "2024-12-31T23:59:59Z" + } + } +} +``` + +### Attributes + +- `name` (optional, string) - Update the API key name (3-100 characters) + + +Only the `name` field can be updated. Other fields like `expires_at`, `prefix`, and `revoked` are read-only and cannot be modified after creation. + + +## Example Request + +```bash +curl -X PATCH "https://api.prowler.com/api/v1/api-keys/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "api-keys", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "attributes": { + "name": "Updated API Key Name" + } + } + }' +``` + +## Response + +### Success Response (200 OK) + +Returns the updated API key with modified metadata: + +```json +{ + "data": { + "type": "api-keys", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "attributes": { + "name": "Updated API Key Name", + "prefix": "pk_live_abc123", + "expires_at": "2025-12-31T23:59:59Z", + "revoked": false, + "inserted_at": "2024-01-15T10:30:00Z", + "last_used_at": "2024-01-20T14:22:00Z" + }, + "relationships": { + "entity": { + "data": { + "type": "users", + "id": "user-uuid" + } + } + } + } +} +``` + + +The full API key value is never returned in responses after creation. Only the prefix is shown for identification. + diff --git a/docs/api-reference/compliance/attributes.mdx b/docs/api-reference/compliance/attributes.mdx new file mode 100644 index 0000000000..e064e0792b --- /dev/null +++ b/docs/api-reference/compliance/attributes.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Compliance Attributes" +api: "GET /api/v1/compliance-overviews/attributes" +description: "Get compliance framework attributes." +--- + +Retrieve detailed attributes for compliance frameworks. diff --git a/docs/api-reference/compliance/list.mdx b/docs/api-reference/compliance/list.mdx new file mode 100644 index 0000000000..506674e1ca --- /dev/null +++ b/docs/api-reference/compliance/list.mdx @@ -0,0 +1,17 @@ +--- +title: "List Compliance Overviews" +api: "GET /api/v1/compliance-overviews" +description: "Retrieve compliance framework coverage for scans." +--- + +Get compliance status across frameworks like CIS, PCI-DSS, HIPAA, etc. + +## Query Parameters +- `filter[scan]` - Filter by scan UUID (required) +- `filter[framework]` - Filter by framework name + +## Example +\`\`\`bash +curl "https://api.prowler.com/api/v1/compliance-overviews?filter[scan]=scan-uuid" \\ + -H "Authorization: Bearer YOUR_API_KEY" +\`\`\` diff --git a/docs/api-reference/compliance/metadata.mdx b/docs/api-reference/compliance/metadata.mdx new file mode 100644 index 0000000000..354490e182 --- /dev/null +++ b/docs/api-reference/compliance/metadata.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Compliance Metadata" +api: "GET /api/v1/compliance-overviews/metadata" +description: "Get available compliance frameworks and metadata." +--- + +Fetch list of available compliance frameworks and their details. diff --git a/docs/api-reference/compliance/requirements.mdx b/docs/api-reference/compliance/requirements.mdx new file mode 100644 index 0000000000..a3a79bf0d7 --- /dev/null +++ b/docs/api-reference/compliance/requirements.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Compliance Requirements" +api: "GET /api/v1/compliance-overviews/requirements" +description: "Get compliance requirements details." +--- + +Fetch specific requirements for compliance frameworks. diff --git a/docs/api-reference/findings/latest.mdx b/docs/api-reference/findings/latest.mdx new file mode 100644 index 0000000000..b70c9b30fd --- /dev/null +++ b/docs/api-reference/findings/latest.mdx @@ -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" + } +} +``` + + +Use this endpoint for real-time monitoring and dashboards, as it automatically focuses on the latest scan results without requiring date filters. + diff --git a/docs/api-reference/findings/list.mdx b/docs/api-reference/findings/list.mdx new file mode 100644 index 0000000000..c2a7ac0139 --- /dev/null +++ b/docs/api-reference/findings/list.mdx @@ -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) + + +Resource information (service, region, resource name, etc.) is available through the `resources` relationship. Use `include=resources` to fetch resource details along with findings. + + +### 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" + } + ] +} +``` + + +**Performance Tip:** Maximum date range for `inserted_at` filters is 7 days. For historical analysis, use multiple requests or export data to external storage. + + + +**Rate Limiting:** This endpoint is rate-limited to 100 requests per minute. For real-time monitoring, consider using webhooks or the `/findings/latest` endpoint. + + + +Use `filter[delta]=new` to only retrieve findings discovered in the most recent scan, perfect for alerting on new security issues. + diff --git a/docs/api-reference/findings/metadata-latest.mdx b/docs/api-reference/findings/metadata-latest.mdx new file mode 100644 index 0000000000..1ba801b867 --- /dev/null +++ b/docs/api-reference/findings/metadata-latest.mdx @@ -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 + + +This endpoint is optimized for dashboard views where you only want to show data from the most recent scans. + diff --git a/docs/api-reference/findings/metadata.mdx b/docs/api-reference/findings/metadata.mdx new file mode 100644 index 0000000000..c7aa1f3d93 --- /dev/null +++ b/docs/api-reference/findings/metadata.mdx @@ -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 + + +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. + diff --git a/docs/api-reference/findings/retrieve.mdx b/docs/api-reference/findings/retrieve.mdx new file mode 100644 index 0000000000..c953a2869b --- /dev/null +++ b/docs/api-reference/findings/retrieve.mdx @@ -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" + } + ] +} +``` diff --git a/docs/api-reference/findings/services-regions.mdx b/docs/api-reference/findings/services-regions.mdx new file mode 100644 index 0000000000..0fc22653f7 --- /dev/null +++ b/docs/api-reference/findings/services-regions.mdx @@ -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." +--- + + +This endpoint is deprecated. Please use alternative filtering methods for retrieving services and regions information. + + +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"] + } + } +} +``` + + +This endpoint is deprecated. Use `/api/v1/findings/metadata` or `/api/v1/findings/metadata/latest` instead. + diff --git a/docs/api-reference/integrations/check-connection.mdx b/docs/api-reference/integrations/check-connection.mdx new file mode 100644 index 0000000000..128ed5c5eb --- /dev/null +++ b/docs/api-reference/integrations/check-connection.mdx @@ -0,0 +1,45 @@ +--- +title: "Check Integration Connection" +api: "POST /api/v1/integrations/{id}/connection" +description: "Try to verify integration connection." +--- + +Test the connection to an integration to ensure it is configured correctly and can communicate with the external service. + +## Path Parameters + +- `id` (required) - UUID of the integration to test + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/integrations/{id}/connection" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns a task object. The connection test is performed asynchronously. + +```json +{ + "data": { + "type": "tasks", + "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", + "attributes": { + "inserted_at": "2019-08-24T14:15:22Z", + "completed_at": "2019-08-24T14:15:22Z", + "name": "string", + "state": "available", + "result": null, + "task_args": null, + "metadata": null + } + } +} +``` + + +Use the returned task ID to check the connection test status via the Tasks API. + diff --git a/docs/api-reference/integrations/create.mdx b/docs/api-reference/integrations/create.mdx new file mode 100644 index 0000000000..a614cc7ef4 --- /dev/null +++ b/docs/api-reference/integrations/create.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Integration" +api: "POST /api/v1/integrations" +description: "Configure a new integration." +--- + +Add integration with external systems. diff --git a/docs/api-reference/integrations/delete.mdx b/docs/api-reference/integrations/delete.mdx new file mode 100644 index 0000000000..d5a1221f4a --- /dev/null +++ b/docs/api-reference/integrations/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Integration" +api: "DELETE /api/v1/integrations/{id}" +description: "Remove an integration." +--- + +Delete integration configuration. diff --git a/docs/api-reference/integrations/jira-dispatch.mdx b/docs/api-reference/integrations/jira-dispatch.mdx new file mode 100644 index 0000000000..6f8e74fdd6 --- /dev/null +++ b/docs/api-reference/integrations/jira-dispatch.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Jira Dispatch" +api: "POST /api/v1/integrations/{id}/jira/dispatches" +description: "Send findings to Jira." +--- + +Dispatch findings to Jira for tracking. diff --git a/docs/api-reference/integrations/list.mdx b/docs/api-reference/integrations/list.mdx new file mode 100644 index 0000000000..cc5d406159 --- /dev/null +++ b/docs/api-reference/integrations/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Integrations" +api: "GET /api/v1/integrations" +description: "Retrieve configured integrations." +--- + +Get all configured integrations (S3, Security Hub, Jira, etc). diff --git a/docs/api-reference/integrations/retrieve.mdx b/docs/api-reference/integrations/retrieve.mdx new file mode 100644 index 0000000000..4b3511126e --- /dev/null +++ b/docs/api-reference/integrations/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Integration" +api: "GET /api/v1/integrations/{id}" +description: "Get integration details." +--- + +Fetch specific integration configuration. diff --git a/docs/api-reference/integrations/update.mdx b/docs/api-reference/integrations/update.mdx new file mode 100644 index 0000000000..df6e8ea59b --- /dev/null +++ b/docs/api-reference/integrations/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Integration" +api: "PATCH /api/v1/integrations/{id}" +description: "Update integration settings." +--- + +Modify integration configuration. diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx new file mode 100644 index 0000000000..e7024b5989 --- /dev/null +++ b/docs/api-reference/introduction.mdx @@ -0,0 +1,121 @@ +--- +title: "API Reference" +description: "Comprehensive API documentation for Prowler Cloud" +--- + +## Welcome to the Prowler API + +The Prowler API provides programmatic access to Prowler Cloud's security compliance scanning and reporting capabilities. This API follows RESTful principles and uses JSON:API specification for request and response formatting. + +### Base URL + +``` +https://api.prowler.com/api/v1 +``` + +### Authentication + +All API requests require authentication using either: + +- **JWT Token**: Obtained through user authentication +- **API Key**: Generated from your Prowler Cloud account + +Include your authentication credentials in the `Authorization` header: + +```bash +Authorization: Bearer YOUR_API_KEY_OR_JWT_TOKEN +``` + +### API Keys Management + +You can manage your API keys through the [API Keys endpoints](/api-reference/api-keys/list). API keys provide: + +- Programmatic access to your Prowler Cloud resources +- Fine-grained access control +- Expiration and revocation capabilities +- Usage tracking + +### Request Format + +All requests should include the following headers: + +``` +Content-Type: application/vnd.api+json +Accept: application/vnd.api+json +Authorization: Bearer YOUR_API_KEY_OR_JWT_TOKEN +``` + +### Response Format + +The API follows the [JSON:API specification](https://jsonapi.org/). Responses include: + +- **data**: The primary data for the response +- **included**: Related resources (when using `include` parameter) +- **meta**: Metadata about the response +- **links**: Pagination links + +### Pagination + +List endpoints support pagination using the following query parameters: + +- `page[number]`: The page number to retrieve +- `page[size]`: Number of results per page + +### Filtering + +Most list endpoints support filtering using query parameters in the format: + +``` +filter[field_name]=value +filter[field_name__operator]=value +``` + +Common operators: +- `__gte`: Greater than or equal +- `__lte`: Less than or equal +- `__icontains`: Case-insensitive contains +- `__in`: In a list of values + +### Sorting + +Use the `sort` parameter to order results: + +``` +sort=field_name # Ascending order +sort=-field_name # Descending order +``` + +### Field Selection + +Optimize responses by requesting only specific fields: + +``` +fields[resource-type]=field1,field2,field3 +``` + +### Rate Limits + +API requests are subject to rate limiting to ensure service stability. Rate limit information is included in response headers. + +### Support + +For questions or issues with the API: + +- Join our [Slack community](https://goto.prowler.com/slack) +- Visit [Prowler Cloud](https://cloud.prowler.com) +- Check our [GitHub repository](https://github.com/prowler-cloud/prowler) + +## API Endpoints + +Explore the complete API reference using the navigation menu. Main endpoint categories include: + +- **API Keys**: Manage programmatic access credentials +- **Findings**: Security findings and vulnerabilities +- **Compliance**: Compliance frameworks and requirements +- **Scans**: Security scan operations and results +- **Providers**: Cloud provider configurations +- **Resources**: Cloud resources inventory + + +The Prowler API is currently at version 1.15.0. We maintain backward compatibility and announce breaking changes in advance. + diff --git a/docs/api-reference/invitations/accept.mdx b/docs/api-reference/invitations/accept.mdx new file mode 100644 index 0000000000..65dc0847fc --- /dev/null +++ b/docs/api-reference/invitations/accept.mdx @@ -0,0 +1,50 @@ +--- +title: "Accept Invitation" +api: "POST /api/v1/invitations/accept" +description: "Accept an invitation to an existing tenant." +--- + +Accept an invitation to join a tenant. This invitation cannot be expired and the emails must match. + +## Request Body + +The request must follow the JSON:API specification format: + +```json +{ + "data": { + "type": "invitations", + "attributes": { + "token": "invitation-token" + } + } +} +``` + +### Attributes + +- `token` (required) - The invitation token received via email + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/invitations/accept" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "invitations", + "attributes": { + "token": "your-invitation-token" + } + } + }' +``` + +## Response + +Returns a success response indicating you have been added to the tenant. + + +The email address associated with your account must match the email address to which the invitation was sent. + diff --git a/docs/api-reference/lighthouse/config-list.mdx b/docs/api-reference/lighthouse/config-list.mdx new file mode 100644 index 0000000000..d369a73e47 --- /dev/null +++ b/docs/api-reference/lighthouse/config-list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Lighthouse Config (Legacy)" +api: "GET /api/v1/lighthouse/configuration" +description: "Legacy configuration endpoint." +--- + +Legacy endpoint for configuration. diff --git a/docs/api-reference/lighthouse/config-update.mdx b/docs/api-reference/lighthouse/config-update.mdx new file mode 100644 index 0000000000..12826f47ec --- /dev/null +++ b/docs/api-reference/lighthouse/config-update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Lighthouse Config (Legacy)" +api: "PATCH /api/v1/lighthouse/configuration" +description: "Update legacy configuration." +--- + +Legacy endpoint for updating configuration. diff --git a/docs/api-reference/lighthouse/configuration-get.mdx b/docs/api-reference/lighthouse/configuration-get.mdx new file mode 100644 index 0000000000..d84f4e0783 --- /dev/null +++ b/docs/api-reference/lighthouse/configuration-get.mdx @@ -0,0 +1,19 @@ +--- +title: "Get Lighthouse AI Tenant Config" +api: "GET /api/v1/lighthouse/configuration" +description: "Retrieve current tenant-level Lighthouse AI settings." +--- + +Get your tenant's Lighthouse AI configuration including business context and default models. + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/lighthouse/configuration" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns tenant Lighthouse AI configuration. diff --git a/docs/api-reference/lighthouse/configuration-update.mdx b/docs/api-reference/lighthouse/configuration-update.mdx new file mode 100644 index 0000000000..ba4a125a13 --- /dev/null +++ b/docs/api-reference/lighthouse/configuration-update.mdx @@ -0,0 +1,37 @@ +--- +title: "Update Lighthouse AI Tenant Config" +api: "PATCH /api/v1/lighthouse/configuration" +description: "Update tenant-level Lighthouse AI settings." +--- + +Update your tenant's Lighthouse AI configuration including business context and default providers/models. + +## Request Body + +```json +{ + "data": { + "type": "lighthouse-config", + "attributes": { + "business_context": "Financial services company focusing on security and compliance", + "default_provider": "openai", + "default_models": { + "chat": "gpt-4", + "analysis": "gpt-4" + } + } + } +} +``` + +## Example Request + +```bash +curl -X PATCH "https://api.prowler.com/api/v1/lighthouse/configuration" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns updated configuration. diff --git a/docs/api-reference/lighthouse/configurations/create.mdx b/docs/api-reference/lighthouse/configurations/create.mdx new file mode 100644 index 0000000000..0857d621de --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/create.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Lighthouse Configuration" +api: "POST /api/v1/lighthouse/configurations" +description: "Create AI configuration profile." +--- + +Configure Lighthouse AI settings. diff --git a/docs/api-reference/lighthouse/configurations/delete.mdx b/docs/api-reference/lighthouse/configurations/delete.mdx new file mode 100644 index 0000000000..42d20771ba --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Lighthouse Configuration" +api: "DELETE /api/v1/lighthouse/configurations/{id}" +description: "Remove configuration profile." +--- + +Delete Lighthouse configuration. diff --git a/docs/api-reference/lighthouse/configurations/list.mdx b/docs/api-reference/lighthouse/configurations/list.mdx new file mode 100644 index 0000000000..8a16d5c179 --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Lighthouse Configurations" +api: "GET /api/v1/lighthouse/configurations" +description: "Retrieve Lighthouse AI configurations." +--- + +Get Lighthouse configuration profiles. diff --git a/docs/api-reference/lighthouse/configurations/retrieve.mdx b/docs/api-reference/lighthouse/configurations/retrieve.mdx new file mode 100644 index 0000000000..4eb63eabaf --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Lighthouse Configuration" +api: "GET /api/v1/lighthouse/configurations/{id}" +description: "Get configuration details." +--- + +Fetch Lighthouse configuration profile. diff --git a/docs/api-reference/lighthouse/configurations/test-connection.mdx b/docs/api-reference/lighthouse/configurations/test-connection.mdx new file mode 100644 index 0000000000..4ab62e1623 --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/test-connection.mdx @@ -0,0 +1,7 @@ +--- +title: "Test Lighthouse Configuration" +api: "POST /api/v1/lighthouse/configurations/{id}/connection" +description: "Test configuration." +--- + +Verify Lighthouse configuration works. diff --git a/docs/api-reference/lighthouse/configurations/update.mdx b/docs/api-reference/lighthouse/configurations/update.mdx new file mode 100644 index 0000000000..d2d488d931 --- /dev/null +++ b/docs/api-reference/lighthouse/configurations/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Lighthouse Configuration" +api: "PATCH /api/v1/lighthouse/configurations/{id}" +description: "Update configuration profile." +--- + +Modify Lighthouse AI settings. diff --git a/docs/api-reference/lighthouse/models-list.mdx b/docs/api-reference/lighthouse/models-list.mdx new file mode 100644 index 0000000000..a168da1cb3 --- /dev/null +++ b/docs/api-reference/lighthouse/models-list.mdx @@ -0,0 +1,25 @@ +--- +title: "List LLM Models" +api: "GET /api/v1/lighthouse/models" +description: "List available LLM models per configured provider." +--- + +Retrieve all available LLM models from your configured providers. + +## Query Parameters + +- `filter[provider_type]` - Filter by provider type +- `filter[model_id]`, `filter[model_id__icontains]` - Filter by model ID +- `page[number]`, `page[size]` - Pagination + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/lighthouse/models?filter[provider_type]=openai" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns list of available LLM models with their parameters. diff --git a/docs/api-reference/lighthouse/models/list.mdx b/docs/api-reference/lighthouse/models/list.mdx new file mode 100644 index 0000000000..da6ac52c68 --- /dev/null +++ b/docs/api-reference/lighthouse/models/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Lighthouse Models" +api: "GET /api/v1/lighthouse/models" +description: "Retrieve available AI models." +--- + +Get list of available LLM models. diff --git a/docs/api-reference/lighthouse/models/retrieve.mdx b/docs/api-reference/lighthouse/models/retrieve.mdx new file mode 100644 index 0000000000..d65d0ea5f7 --- /dev/null +++ b/docs/api-reference/lighthouse/models/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Lighthouse Model" +api: "GET /api/v1/lighthouse/models/{id}" +description: "Get AI model details." +--- + +Fetch information about a specific model. diff --git a/docs/api-reference/lighthouse/providers-create.mdx b/docs/api-reference/lighthouse/providers-create.mdx new file mode 100644 index 0000000000..b547249ed3 --- /dev/null +++ b/docs/api-reference/lighthouse/providers-create.mdx @@ -0,0 +1,40 @@ +--- +title: "Create LLM Provider Config" +api: "POST /api/v1/lighthouse/providers" +description: "Create configuration for an LLM provider." +--- + +Configure an LLM provider for use with Lighthouse AI. + +## Request Body + +```json +{ + "data": { + "type": "lighthouse-providers", + "attributes": { + "provider_type": "openai", + "base_url": "https://api.openai.com/v1", + "credentials": { + "api_key": "sk-..." + } + } + } +} +``` + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/lighthouse/providers" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns the created provider configuration. + + +Only one configuration per provider type is allowed per tenant. + diff --git a/docs/api-reference/lighthouse/providers-list.mdx b/docs/api-reference/lighthouse/providers-list.mdx new file mode 100644 index 0000000000..68278a25ec --- /dev/null +++ b/docs/api-reference/lighthouse/providers-list.mdx @@ -0,0 +1,25 @@ +--- +title: "List LLM Provider Configs" +api: "GET /api/v1/lighthouse/providers" +description: "Retrieve all LLM provider configurations for Lighthouse AI." +--- + +Retrieve all configured LLM provider configurations (OpenAI, etc.) for Lighthouse AI. + +## Query Parameters + +- `filter[provider_type]` - Filter by provider type: `openai` +- `filter[is_active]` - Filter by active status (boolean) +- `page[number]`, `page[size]` - Pagination + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/lighthouse/providers" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns list of LLM provider configurations. diff --git a/docs/api-reference/lighthouse/providers/create.mdx b/docs/api-reference/lighthouse/providers/create.mdx new file mode 100644 index 0000000000..4cfc3b30ac --- /dev/null +++ b/docs/api-reference/lighthouse/providers/create.mdx @@ -0,0 +1,21 @@ +--- +title: "Create Lighthouse Provider" +api: "POST /api/v1/lighthouse/providers" +description: "Add AI provider for Lighthouse." +--- + +Configure an LLM provider. + +## Request Body +\`\`\`json +{ + "data": { + "type": "lighthouse-providers", + "attributes": { + "provider_type": "openai", + "api_key": "sk-...", + "name": "OpenAI Production" + } + } +} +\`\`\` diff --git a/docs/api-reference/lighthouse/providers/delete.mdx b/docs/api-reference/lighthouse/providers/delete.mdx new file mode 100644 index 0000000000..638fca1a97 --- /dev/null +++ b/docs/api-reference/lighthouse/providers/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Lighthouse Provider" +api: "DELETE /api/v1/lighthouse/providers/{id}" +description: "Remove AI provider." +--- + +Delete LLM provider configuration. diff --git a/docs/api-reference/lighthouse/providers/list.mdx b/docs/api-reference/lighthouse/providers/list.mdx new file mode 100644 index 0000000000..d8df346b5f --- /dev/null +++ b/docs/api-reference/lighthouse/providers/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Lighthouse Providers" +api: "GET /api/v1/lighthouse/providers" +description: "Retrieve LLM providers for Lighthouse AI." +--- + +Get configured AI/LLM providers (OpenAI, Azure OpenAI, etc). diff --git a/docs/api-reference/lighthouse/providers/refresh-models.mdx b/docs/api-reference/lighthouse/providers/refresh-models.mdx new file mode 100644 index 0000000000..6ef547ff1c --- /dev/null +++ b/docs/api-reference/lighthouse/providers/refresh-models.mdx @@ -0,0 +1,7 @@ +--- +title: "Refresh Lighthouse Provider Models" +api: "POST /api/v1/lighthouse/providers/{id}/refresh-models" +description: "Refresh available models from provider." +--- + +Update the list of available AI models. diff --git a/docs/api-reference/lighthouse/providers/retrieve.mdx b/docs/api-reference/lighthouse/providers/retrieve.mdx new file mode 100644 index 0000000000..c93e348a77 --- /dev/null +++ b/docs/api-reference/lighthouse/providers/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Lighthouse Provider" +api: "GET /api/v1/lighthouse/providers/{id}" +description: "Get AI provider details." +--- + +Fetch LLM provider configuration. diff --git a/docs/api-reference/lighthouse/providers/test-connection.mdx b/docs/api-reference/lighthouse/providers/test-connection.mdx new file mode 100644 index 0000000000..0255102efd --- /dev/null +++ b/docs/api-reference/lighthouse/providers/test-connection.mdx @@ -0,0 +1,7 @@ +--- +title: "Test Lighthouse Provider Connection" +api: "POST /api/v1/lighthouse/providers/{id}/connection" +description: "Test AI provider connectivity." +--- + +Verify LLM provider is properly configured. diff --git a/docs/api-reference/lighthouse/providers/update.mdx b/docs/api-reference/lighthouse/providers/update.mdx new file mode 100644 index 0000000000..4c2567500a --- /dev/null +++ b/docs/api-reference/lighthouse/providers/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Lighthouse Provider" +api: "PATCH /api/v1/lighthouse/providers/{id}" +description: "Update AI provider settings." +--- + +Modify LLM provider configuration. diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml new file mode 100644 index 0000000000..6c05866c76 --- /dev/null +++ b/docs/api-reference/openapi.yaml @@ -0,0 +1,18070 @@ +openapi: 3.0.3 +info: + title: Prowler API + version: 1.15.0 + description: |- + Prowler API specification. + + This file is auto-generated. +paths: + /api/v1/api-keys: + get: + operationId: api_keys_list + description: Retrieve a list of API keys for the tenant, with filtering support. + summary: List API keys + parameters: + - in: query + name: fields[api-keys] + schema: + type: array + items: + type: string + enum: + - name + - prefix + - expires_at + - revoked + - inserted_at + - last_used_at + - entity + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[expires_at] + schema: + type: string + format: date + - in: query + name: filter[expires_at__gte] + schema: + type: string + format: date + - in: query + name: filter[expires_at__lte] + schema: + type: string + format: date + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[prefix] + schema: + type: string + - in: query + name: filter[prefix__icontains] + schema: + type: string + - in: query + name: filter[revoked] + schema: + type: boolean + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - entity + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - prefix + - -prefix + - revoked + - -revoked + - inserted_at + - -inserted_at + - expires_at + - -expires_at + explode: false + tags: + - API Keys + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedTenantApiKeyList' + description: '' + post: + operationId: api_keys_create + description: Create a new API key for the tenant. + summary: Create a new API key + tags: + - API Keys + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantApiKeyCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/TenantApiKeyCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/TenantApiKeyCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantApiKeyCreateResponse' + description: '' + /api/v1/api-keys/{id}: + get: + operationId: api_keys_retrieve + description: Fetch detailed information about a specific API key by its ID. + summary: Retrieve API key details + parameters: + - in: query + name: fields[api-keys] + schema: + type: array + items: + type: string + enum: + - name + - prefix + - expires_at + - revoked + - inserted_at + - last_used_at + - entity + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant api key. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - entity + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - API Keys + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantApiKeyResponse' + description: '' + patch: + operationId: api_keys_partial_update + description: Modify certain fields of an existing API key without affecting + other settings. + summary: Partially update an API key + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant api key. + required: true + tags: + - API Keys + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedTenantApiKeyUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedTenantApiKeyUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedTenantApiKeyUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantApiKeyUpdateResponse' + description: '' + /api/v1/api-keys/{id}/revoke: + delete: + operationId: api_keys_revoke_destroy + description: Revoke an API key by its ID. This action is irreversible and will + prevent the key from being used. + summary: Revoke an API key + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant api key. + required: true + tags: + - API Keys + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OpenApiResponseResponse' + description: API key was successfully revoked + /api/v1/compliance-overviews: + get: + operationId: compliance_overviews_list + description: Retrieve an overview of all the compliance in a given scan. + summary: List compliance overviews for a scan + parameters: + - in: query + name: fields[compliance-overviews] + schema: + type: array + items: + type: string + enum: + - id + - framework + - version + - requirements_passed + - requirements_failed + - requirements_manual + - total_requirements + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[compliance_id] + schema: + type: string + - in: query + name: filter[compliance_id__icontains] + schema: + type: string + - in: query + name: filter[framework] + schema: + type: string + - in: query + name: filter[framework__icontains] + schema: + type: string + - in: query + name: filter[framework__iexact] + schema: + type: string + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan_id] + schema: + type: string + format: uuid + description: Related scan ID. + required: true + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[version] + schema: + type: string + - in: query + name: filter[version__icontains] + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - compliance_id + - -compliance_id + explode: false + tags: + - Compliance Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedComplianceOverviewList' + description: Compliance overviews obtained successfully + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: The task is in progress + '500': + description: Compliance overviews generation task failed + /api/v1/compliance-overviews/attributes: + get: + operationId: compliance_overviews_attributes_retrieve + description: Retrieve detailed attribute information for all requirements in + a specific compliance framework along with the associated check IDs for each + requirement. + summary: Get compliance requirement attributes + parameters: + - in: query + name: fields[compliance-requirements-attributes] + schema: + type: array + items: + type: string + enum: + - id + - compliance_name + - framework_description + - name + - framework + - version + - description + - attributes + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[compliance_id] + schema: + type: string + description: Compliance framework ID to get attributes for. + required: true + tags: + - Compliance Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedComplianceOverviewAttributesList' + description: Compliance attributes obtained successfully + /api/v1/compliance-overviews/metadata: + get: + operationId: compliance_overviews_metadata_retrieve + description: Fetch unique metadata values from a set of compliance overviews. + This is useful for dynamic filtering. + summary: Retrieve metadata values from compliance overviews + parameters: + - in: query + name: fields[compliance-overviews-metadata] + schema: + type: array + items: + type: string + enum: + - regions + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[scan_id] + schema: + type: string + format: uuid + description: Related scan ID. + required: true + tags: + - Compliance Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OpenApiResponseResponse' + description: Compliance overviews metadata obtained successfully + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: The task is in progress + '500': + description: Compliance overviews generation task failed + /api/v1/compliance-overviews/requirements: + get: + operationId: compliance_overviews_requirements_retrieve + description: Retrieve a detailed overview of compliance requirements in a given + scan, grouped by compliance framework. This endpoint provides requirement-level + details and aggregates status across regions. + summary: List compliance requirements overview for a scan + parameters: + - in: query + name: fields[compliance-requirements-details] + schema: + type: array + items: + type: string + enum: + - id + - framework + - version + - description + - status + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[compliance_id] + schema: + type: string + description: Compliance ID. + required: true + - in: query + name: filter[compliance_id__icontains] + schema: + type: string + - in: query + name: filter[framework] + schema: + type: string + - in: query + name: filter[framework__icontains] + schema: + type: string + - in: query + name: filter[framework__iexact] + schema: + type: string + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan_id] + schema: + type: string + format: uuid + description: Related scan ID. + required: true + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[version] + schema: + type: string + - in: query + name: filter[version__icontains] + schema: + type: string + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - compliance_id + - -compliance_id + explode: false + tags: + - Compliance Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedComplianceOverviewDetailList' + description: Compliance requirement details obtained successfully + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: The task is in progress + '500': + description: Compliance overviews generation task failed + /api/v1/findings: + get: + operationId: findings_list + description: Retrieve a list of all findings with options for filtering by various + criteria. + summary: List all findings + parameters: + - in: query + name: fields[findings] + schema: + type: array + items: + type: string + enum: + - 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 + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[check_id] + schema: + type: string + - in: query + name: filter[check_id__icontains] + schema: + type: string + - in: query + name: filter[check_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[delta] + schema: + type: string + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + enum: + - changed + - new + description: |- + * `new` - New + * `changed` - Changed + - in: query + name: filter[delta__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[impact] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[impact__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + description: At least one of the variations of the `filter[inserted_at]` filter + must be provided. + required: true + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[muted] + schema: + type: boolean + description: If this filter is not provided, muted and non-muted findings + will be returned. + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_name] + schema: + type: string + - in: query + name: filter[resource_name__icontains] + schema: + type: string + - in: query + name: filter[resource_name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_type] + schema: + type: string + - in: query + name: filter[resource_type__icontains] + schema: + type: string + - in: query + name: filter[resource_type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_uid] + schema: + type: string + - in: query + name: filter[resource_uid__icontains] + schema: + type: string + - in: query + name: filter[resource_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resources] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan] + schema: + type: string + format: uuid + - in: query + name: filter[scan__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[severity] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[severity__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[status] + schema: + type: string + x-spec-enum-id: ce612ddbfa464789 + enum: + - FAIL + - MANUAL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - scan + - resources + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - status + - -status + - severity + - -severity + - check_id + - -check_id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedFindingList' + description: '' + /api/v1/findings/{id}: + get: + operationId: findings_retrieve + description: Fetch detailed information about a specific finding by its ID. + summary: Retrieve data from a specific finding + parameters: + - in: query + name: fields[findings] + schema: + type: array + items: + type: string + enum: + - 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 + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this finding. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - scan + - resources + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/FindingResponse' + description: '' + /api/v1/findings/findings_services_regions: + get: + operationId: findings_findings_services_regions_retrieve + description: Fetch services and regions affected in findings. + summary: Retrieve the services and regions that are impacted by findings + parameters: + - in: query + name: fields[finding-dynamic-filters] + schema: + type: array + items: + type: string + enum: + - services + - regions + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[check_id] + schema: + type: string + - in: query + name: filter[check_id__icontains] + schema: + type: string + - in: query + name: filter[check_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[delta] + schema: + type: string + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + enum: + - changed + - new + description: |- + * `new` - New + * `changed` - Changed + - in: query + name: filter[delta__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[impact] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[impact__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[muted] + schema: + type: boolean + description: If this filter is not provided, muted and non-muted findings + will be returned. + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_name] + schema: + type: string + - in: query + name: filter[resource_name__icontains] + schema: + type: string + - in: query + name: filter[resource_name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_type] + schema: + type: string + - in: query + name: filter[resource_type__icontains] + schema: + type: string + - in: query + name: filter[resource_type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_uid] + schema: + type: string + - in: query + name: filter[resource_uid__icontains] + schema: + type: string + - in: query + name: filter[resource_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resources] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan] + schema: + type: string + format: uuid + - in: query + name: filter[scan__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[severity] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[severity__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[status] + schema: + type: string + x-spec-enum-id: ce612ddbfa464789 + enum: + - FAIL + - MANUAL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - status + - -status + - severity + - -severity + - check_id + - -check_id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + deprecated: true + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/FindingDynamicFilterResponse' + description: '' + /api/v1/findings/latest: + get: + operationId: findings_latest_retrieve + description: Retrieve a list of the latest findings from the latest scans for + each provider with options for filtering by various criteria. + summary: List the latest findings + parameters: + - in: query + name: fields[findings] + schema: + type: array + items: + type: string + enum: + - 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 + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[check_id] + schema: + type: string + - in: query + name: filter[check_id__icontains] + schema: + type: string + - in: query + name: filter[check_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[delta] + schema: + type: string + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + enum: + - changed + - new + description: |- + * `new` - New + * `changed` - Changed + - in: query + name: filter[delta__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[impact] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[impact__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[muted] + schema: + type: boolean + description: If this filter is not provided, muted and non-muted findings + will be returned. + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_name] + schema: + type: string + - in: query + name: filter[resource_name__icontains] + schema: + type: string + - in: query + name: filter[resource_name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_type] + schema: + type: string + - in: query + name: filter[resource_type__icontains] + schema: + type: string + - in: query + name: filter[resource_type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_uid] + schema: + type: string + - in: query + name: filter[resource_uid__icontains] + schema: + type: string + - in: query + name: filter[resource_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resources] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[severity] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[severity__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[status] + schema: + type: string + x-spec-enum-id: ce612ddbfa464789 + enum: + - FAIL + - MANUAL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - scan + - resources + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - status + - -status + - severity + - -severity + - check_id + - -check_id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/FindingResponse' + description: '' + /api/v1/findings/metadata: + get: + operationId: findings_metadata_retrieve + description: Fetch unique metadata values from a set of findings. This is useful + for dynamic filtering. + summary: Retrieve metadata values from findings + parameters: + - in: query + name: fields[findings-metadata] + schema: + type: array + items: + type: string + enum: + - services + - regions + - resource_types + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[check_id] + schema: + type: string + - in: query + name: filter[check_id__icontains] + schema: + type: string + - in: query + name: filter[check_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[delta] + schema: + type: string + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + enum: + - changed + - new + description: |- + * `new` - New + * `changed` - Changed + - in: query + name: filter[delta__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[impact] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[impact__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + description: At least one of the variations of the `filter[inserted_at]` filter + must be provided. + required: true + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date + description: Maximum date range is 7 days. + - in: query + name: filter[muted] + schema: + type: boolean + description: If this filter is not provided, muted and non-muted findings + will be returned. + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_name] + schema: + type: string + - in: query + name: filter[resource_name__icontains] + schema: + type: string + - in: query + name: filter[resource_name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_type] + schema: + type: string + - in: query + name: filter[resource_type__icontains] + schema: + type: string + - in: query + name: filter[resource_type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_uid] + schema: + type: string + - in: query + name: filter[resource_uid__icontains] + schema: + type: string + - in: query + name: filter[resource_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resources] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan] + schema: + type: string + format: uuid + - in: query + name: filter[scan__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[severity] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[severity__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[status] + schema: + type: string + x-spec-enum-id: ce612ddbfa464789 + enum: + - FAIL + - MANUAL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - status + - -status + - severity + - -severity + - check_id + - -check_id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/FindingMetadataResponse' + description: '' + /api/v1/findings/metadata/latest: + get: + operationId: findings_metadata_latest_retrieve + description: Fetch unique metadata values from a set of findings from the latest + scans for each provider. This is useful for dynamic filtering. + summary: Retrieve metadata values from the latest findings + parameters: + - in: query + name: fields[findings-metadata] + schema: + type: array + items: + type: string + enum: + - services + - regions + - resource_types + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[check_id] + schema: + type: string + - in: query + name: filter[check_id__icontains] + schema: + type: string + - in: query + name: filter[check_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[delta] + schema: + type: string + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + enum: + - changed + - new + description: |- + * `new` - New + * `changed` - Changed + - in: query + name: filter[delta__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[impact] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[impact__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[muted] + schema: + type: boolean + description: If this filter is not provided, muted and non-muted findings + will be returned. + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_name] + schema: + type: string + - in: query + name: filter[resource_name__icontains] + schema: + type: string + - in: query + name: filter[resource_name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_type] + schema: + type: string + - in: query + name: filter[resource_type__icontains] + schema: + type: string + - in: query + name: filter[resource_type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resource_uid] + schema: + type: string + - in: query + name: filter[resource_uid__icontains] + schema: + type: string + - in: query + name: filter[resource_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[resources] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[severity] + schema: + type: string + x-spec-enum-id: c93e070ed135d9bf + enum: + - critical + - high + - informational + - low + - medium + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + - in: query + name: filter[severity__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[status] + schema: + type: string + x-spec-enum-id: ce612ddbfa464789 + enum: + - FAIL + - MANUAL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - status + - -status + - severity + - -severity + - check_id + - -check_id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Finding + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/FindingMetadataResponse' + description: '' + /api/v1/integrations: + get: + operationId: integrations_list + description: Retrieve a list of all configured integrations with options for + filtering by various criteria. + summary: List all integrations + parameters: + - in: query + name: fields[integrations] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - enabled + - connected + - connection_last_checked_at + - integration_type + - configuration + - providers + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[integration_type] + schema: + type: string + x-spec-enum-id: 6cfd0ff9cf4d6dcc + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + - in: query + name: filter[integration_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6cfd0ff9cf4d6dcc + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + description: |- + Multiple values may be separated by commas. + + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - providers + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - enabled + - -enabled + - connected + - -connected + - connection_last_checked_at + - -connection_last_checked_at + - integration_type + - -integration_type + - configuration + - -configuration + - providers + - -providers + - url + - -url + explode: false + tags: + - Integration + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedIntegrationList' + description: '' + post: + operationId: integrations_create + description: Register a new integration with the system, providing necessary + configuration details. + summary: Create a new integration + tags: + - Integration + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/IntegrationCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/IntegrationCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/IntegrationCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/IntegrationCreateResponse' + description: '' + /api/v1/integrations/{integration_pk}/jira/dispatches: + post: + operationId: integrations_jira_dispatches_create + description: Send a set of filtered findings to the given integration. At least + one finding filter must be provided. + summary: Send findings to a Jira integration + parameters: + - in: query + name: filter[finding_id] + schema: + type: string + format: uuid + - in: query + name: filter[finding_id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: path + name: integration_pk + schema: + type: string + required: true + tags: + - Integration + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/IntegrationJiraDispatchRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/IntegrationJiraDispatchRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/IntegrationJiraDispatchRequest' + required: true + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/integrations/{id}: + get: + operationId: integrations_retrieve + description: Fetch detailed information about a specific integration by its + ID. + summary: Retrieve integration details + parameters: + - in: query + name: fields[integrations] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - enabled + - connected + - connection_last_checked_at + - integration_type + - configuration + - providers + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this integration. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - providers + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Integration + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/IntegrationResponse' + description: '' + patch: + operationId: integrations_partial_update + description: Modify certain fields of an existing integration without affecting + other settings. + summary: Partially update an integration + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this integration. + required: true + tags: + - Integration + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedIntegrationUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedIntegrationUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedIntegrationUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/IntegrationUpdateResponse' + description: '' + delete: + operationId: integrations_destroy + description: Remove an integration from the system by its ID. + summary: Delete an integration + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this integration. + required: true + tags: + - Integration + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/integrations/{id}/connection: + post: + operationId: integrations_connection_create + description: Try to verify integration connection + summary: Check integration connection + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this integration. + required: true + tags: + - Integration + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/invitations/accept: + post: + operationId: invitations_accept_create + description: Accept an invitation to an existing tenant. This invitation cannot + be expired and the emails must match. + summary: Accept an invitation + tags: + - Invitation + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/InvitationAcceptRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/InvitationAcceptRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/InvitationAcceptRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OpenApiResponseResponse' + description: '' + /api/v1/lighthouse-configurations: + get: + operationId: lighthouse_configurations_list + description: Retrieve a list of all Lighthouse AI configurations. + summary: List all Lighthouse AI configurations + parameters: + - in: query + name: fields[lighthouse-configurations] + schema: + type: array + items: + type: string + enum: + - name + - api_key + - model + - temperature + - max_tokens + - business_context + - is_active + - inserted_at + - updated_at + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - is_active + - -is_active + explode: false + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + deprecated: true + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedLighthouseConfigList' + description: '' + post: + operationId: lighthouse_configurations_create + description: Create a new Lighthouse AI configuration with the specified details. + summary: Create a new Lighthouse AI configuration + tags: + - Lighthouse AI + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseConfigCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/LighthouseConfigCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/LighthouseConfigCreateRequest' + required: true + security: + - JWT or API Key: [] + deprecated: true + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseConfigCreateResponse' + description: '' + /api/v1/lighthouse-configurations/{id}: + patch: + operationId: lighthouse_configurations_partial_update + description: Update certain fields of an existing Lighthouse AI configuration. + summary: Partially update a Lighthouse AI configuration + parameters: + - in: path + name: id + schema: + type: string + required: true + tags: + - Lighthouse AI + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedLighthouseConfigUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedLighthouseConfigUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedLighthouseConfigUpdateRequest' + required: true + security: + - JWT or API Key: [] + deprecated: true + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseConfigUpdateResponse' + description: '' + delete: + operationId: lighthouse_configurations_destroy + description: Remove a Lighthouse AI configuration by its ID. + summary: Delete a Lighthouse AI configuration + parameters: + - in: path + name: id + schema: + type: string + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + deprecated: true + responses: + '204': + description: No response body + /api/v1/lighthouse-configurations/{id}/connection: + post: + operationId: lighthouse_configurations_connection_create + description: Verify the connection to the OpenAI API for a specific Lighthouse + AI configuration. + summary: Check the connection to the OpenAI API + parameters: + - in: path + name: id + schema: + type: string + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + deprecated: true + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/lighthouse/configuration: + get: + operationId: lighthouse_configuration_list + description: Retrieve current tenant-level Lighthouse AI settings. Returns a + single configuration object. + summary: Get Lighthouse AI Tenant config + parameters: + - in: query + name: fields[lighthouse-config] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - business_context + - default_provider + - default_models + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - business_context + - -business_context + - default_provider + - -default_provider + - default_models + - -default_models + - url + - -url + explode: false + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedLighthouseTenantConfigList' + description: '' + patch: + operationId: lighthouse_configuration_partial_update + description: Update tenant-level settings. Validates that the default provider + is configured and active and that default model IDs exist for the chosen providers. + Auto-creates configuration if it doesn't exist. + summary: Update Lighthouse AI Tenant config + tags: + - Lighthouse AI + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedLighthouseTenantConfigUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedLighthouseTenantConfigUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedLighthouseTenantConfigUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseTenantConfigUpdateResponse' + description: '' + /api/v1/lighthouse/models: + get: + operationId: lighthouse_models_list + description: List available LLM models per configured provider for the current + tenant. + summary: List all LLM models + parameters: + - in: query + name: fields[LighthouseProviderModels] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider_configuration + - model_id + - model_name + - default_parameters + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[model_id] + schema: + type: string + - in: query + name: filter[model_id__icontains] + schema: + type: string + - in: query + name: filter[model_id__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 80350f3ab09becd9 + enum: + - openai + description: |- + LLM provider name + + * `openai` - OpenAI + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 80350f3ab09becd9 + enum: + - openai + description: |- + Multiple values may be separated by commas. + + * `openai` - OpenAI + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - provider_configuration + - -provider_configuration + - model_id + - -model_id + - model_name + - -model_name + - default_parameters + - -default_parameters + - url + - -url + explode: false + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedLighthouseProviderModelsList' + description: '' + /api/v1/lighthouse/models/{id}: + get: + operationId: lighthouse_models_retrieve + description: Get details for a specific LLM model. + summary: Retrieve LLM model details + parameters: + - in: query + name: fields[LighthouseProviderModels] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider_configuration + - model_id + - model_name + - default_parameters + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider models. + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseProviderModelsResponse' + description: '' + /api/v1/lighthouse/providers: + get: + operationId: lighthouse_providers_list + description: Retrieve all LLM provider configurations for the current tenant + summary: List all LLM provider configs + parameters: + - in: query + name: fields[lighthouse-providers] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider_type + - base_url + - is_active + - credentials + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[is_active] + schema: + type: boolean + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 80350f3ab09becd9 + enum: + - openai + description: |- + LLM provider name + + * `openai` - OpenAI + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 80350f3ab09becd9 + enum: + - openai + description: |- + Multiple values may be separated by commas. + + * `openai` - OpenAI + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - provider_type + - -provider_type + - base_url + - -base_url + - is_active + - -is_active + - credentials + - -credentials + - url + - -url + explode: false + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedLighthouseProviderConfigList' + description: '' + post: + operationId: lighthouse_providers_create + description: Create a per-tenant configuration for an LLM provider. Only one + configuration per provider type is allowed per tenant. + summary: Create LLM provider config + tags: + - Lighthouse AI + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigCreateResponse' + description: '' + /api/v1/lighthouse/providers/{id}: + get: + operationId: lighthouse_providers_retrieve + description: Get details for a specific provider configuration in the current + tenant. + summary: Retrieve LLM provider config + parameters: + - in: query + name: fields[lighthouse-providers] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider_type + - base_url + - is_active + - credentials + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider configuration. + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigResponse' + description: '' + patch: + operationId: lighthouse_providers_partial_update + description: Partially update a provider configuration (e.g., base_url, is_active). + summary: Update LLM provider config + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider configuration. + required: true + tags: + - Lighthouse AI + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedLighthouseProviderConfigUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedLighthouseProviderConfigUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedLighthouseProviderConfigUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/LighthouseProviderConfigUpdateResponse' + description: '' + delete: + operationId: lighthouse_providers_destroy + description: Delete a provider configuration. Any tenant defaults that reference + this provider are cleared during deletion. + summary: Delete LLM provider config + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider configuration. + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/lighthouse/providers/{id}/connection: + post: + operationId: lighthouse_providers_connection_create + description: Validate provider credentials asynchronously and toggle is_active. + summary: Check LLM provider connection + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider configuration. + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/lighthouse/providers/{id}/refresh-models: + post: + operationId: lighthouse_providers_refresh_models_create + description: Fetch available models for this provider configuration and upsert + into catalog. + summary: Refresh LLM models catalog + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this lighthouse provider configuration. + required: true + tags: + - Lighthouse AI + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/overviews/findings: + get: + operationId: overviews_findings_retrieve + description: Fetch aggregated findings data across all providers, grouped by + various metrics such as passed, failed, muted, and total findings. This endpoint + calculates summary statistics based on the latest scans for each provider + and applies any provided filters, such as region, provider type, and scan + date. + summary: Get aggregated findings data + parameters: + - in: query + name: fields[findings-overview] + schema: + type: array + items: + type: string + enum: + - id + - new + - changed + - unchanged + - fail_new + - fail_changed + - pass_new + - pass_changed + - muted_new + - muted_changed + - total + - fail + - muted + - pass + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[provider_id] + schema: + type: string + format: uuid + - in: query + name: filter[provider_id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - new + - -new + - changed + - -changed + - unchanged + - -unchanged + - fail_new + - -fail_new + - fail_changed + - -fail_changed + - pass_new + - -pass_new + - pass_changed + - -pass_changed + - muted_new + - -muted_new + - muted_changed + - -muted_changed + - total + - -total + - fail + - -fail + - muted + - -muted + - pass + - -pass + explode: false + tags: + - Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OverviewFindingResponse' + description: '' + /api/v1/overviews/findings_severity: + get: + operationId: overviews_findings_severity_retrieve + description: Retrieve an aggregated summary of findings grouped by severity + levels, such as low, medium, high, and critical. The response includes the + total count of findings for each severity, considering only the latest scans + for each provider. Additional filters can be applied to narrow down results + by region, provider type, or other attributes. + summary: Get findings data by severity + parameters: + - in: query + name: fields[findings-severity-overview] + schema: + type: array + items: + type: string + enum: + - id + - critical + - high + - medium + - low + - informational + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[provider_id] + schema: + type: string + format: uuid + - in: query + name: filter[provider_id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[status] + schema: + type: string + enum: + - FAIL + - PASS + description: |- + * `FAIL` - Fail + * `PASS` - Pass + - in: query + name: filter[status__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - critical + - -critical + - high + - -high + - medium + - -medium + - low + - -low + - informational + - -informational + explode: false + tags: + - Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OverviewSeverityResponse' + description: '' + /api/v1/overviews/providers: + get: + operationId: overviews_providers_retrieve + description: Retrieve an aggregated overview of findings and resources grouped + by providers. The response includes the count of passed, failed, and manual + findings, along with the total number of resources managed by each provider. + Only the latest findings for each provider are considered in the aggregation + to ensure accurate and up-to-date insights. + summary: Get aggregated provider data + parameters: + - in: query + name: fields[providers-overview] + schema: + type: array + items: + type: string + enum: + - id + - findings + - resources + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + tags: + - Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OverviewProviderResponse' + description: '' + /api/v1/overviews/providers/count: + get: + operationId: overviews_providers_count_retrieve + description: Retrieve the number of providers grouped by provider type. This + endpoint counts every provider in the tenant, including those without completed + scans. + summary: Get provider counts grouped by type + parameters: + - in: query + name: fields[providers-count-overview] + schema: + type: array + items: + type: string + enum: + - id + - count + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + tags: + - Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OverviewProviderCountResponse' + description: '' + /api/v1/overviews/services: + get: + operationId: overviews_services_retrieve + description: Retrieve an aggregated summary of findings grouped by service. + The response includes the total count of findings for each service, as long + as there are at least one finding for that service. At least one of the `inserted_at` + filters must be provided. + summary: Get findings data by service + parameters: + - in: query + name: fields[services-overview] + schema: + type: array + items: + type: string + enum: + - id + - total + - fail + - muted + - pass + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[provider_id] + schema: + type: string + format: uuid + - in: query + name: filter[provider_id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - total + - -total + - fail + - -fail + - muted + - -muted + - pass + - -pass + explode: false + tags: + - Overview + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/OverviewServiceResponse' + description: '' + /api/v1/processors: + get: + operationId: processors_list + description: Retrieve a list of all configured processors with options for filtering + by various criteria. + summary: List all processors + parameters: + - in: query + name: fields[processors] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - processor_type + - configuration + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[processor_type] + schema: + type: string + x-spec-enum-id: 53cda4a99fe3d655 + enum: + - mutelist + description: '* `mutelist` - Mutelist' + - in: query + name: filter[processor_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 53cda4a99fe3d655 + enum: + - mutelist + description: |- + Multiple values may be separated by commas. + + * `mutelist` - Mutelist + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - processor_type + - -processor_type + - configuration + - -configuration + - url + - -url + explode: false + tags: + - Processor + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedProcessorList' + description: '' + post: + operationId: processors_create + description: Register a new processor with the system, providing necessary configuration + details. There can only be one processor of each type per tenant. + summary: Create a new processor + tags: + - Processor + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProcessorCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ProcessorCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ProcessorCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProcessorCreateResponse' + description: '' + /api/v1/processors/{id}: + get: + operationId: processors_retrieve + description: Fetch detailed information about a specific processor by its ID. + summary: Retrieve processor details + parameters: + - in: query + name: fields[processors] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - processor_type + - configuration + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this processor. + required: true + tags: + - Processor + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProcessorResponse' + description: '' + patch: + operationId: processors_partial_update + description: Modify certain fields of an existing processor without affecting + other settings. + summary: Partially update a processor + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this processor. + required: true + tags: + - Processor + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedProcessorUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedProcessorUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedProcessorUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProcessorUpdateResponse' + description: '' + delete: + operationId: processors_destroy + description: Remove a processor from the system by its ID. + summary: Delete a processor + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this processor. + required: true + tags: + - Processor + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/provider-groups: + get: + operationId: provider_groups_list + description: Retrieve a list of all provider groups with options for filtering + by various criteria. + summary: List all provider groups + parameters: + - in: query + name: fields[provider-groups] + schema: + type: array + items: + type: string + enum: + - name + - inserted_at + - updated_at + - providers + - roles + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - name + - -name + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - providers + - -providers + - roles + - -roles + - url + - -url + explode: false + tags: + - Provider Group + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedProviderGroupList' + description: '' + post: + operationId: provider_groups_create + description: Add a new provider group to the system by providing the required + provider group details. + summary: Create a new provider group + tags: + - Provider Group + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderGroupCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ProviderGroupCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ProviderGroupCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderGroupCreateResponse' + description: '' + /api/v1/provider-groups/{id}: + get: + operationId: provider_groups_retrieve + description: Fetch detailed information about a specific provider group by their + ID. + summary: Retrieve data from a provider group + parameters: + - in: query + name: fields[provider-groups] + schema: + type: array + items: + type: string + enum: + - name + - inserted_at + - updated_at + - providers + - roles + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider group. + required: true + tags: + - Provider Group + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderGroupResponse' + description: '' + patch: + operationId: provider_groups_partial_update + description: Update certain fields of an existing provider group's information + without affecting other fields. + summary: Partially update a provider group + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider group. + required: true + tags: + - Provider Group + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedProviderGroupUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedProviderGroupUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedProviderGroupUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SerializerMetaclassResponse' + description: '' + delete: + operationId: provider_groups_destroy + description: Remove a provider group from the system by their ID. + summary: Delete a provider group + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider group. + required: true + tags: + - Provider Group + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/provider-groups/{id}/relationships/providers: + post: + operationId: provider_groups_relationships_providers_create + description: Add a new provider_group-providers relationship to the system by + providing the required provider_group-providers details. + summary: Create a new provider_group-providers relationship + tags: + - Provider Group + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderGroupMembershipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ProviderGroupMembershipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ProviderGroupMembershipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship created successfully + '400': + description: Bad request (e.g., relationship already exists) + patch: + operationId: provider_groups_relationships_providers_partial_update + description: Update the provider_group-providers relationship information without + affecting other fields. + summary: Partially update a provider_group-providers relationship + tags: + - Provider Group + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedProviderGroupMembershipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedProviderGroupMembershipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedProviderGroupMembershipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship updated successfully + delete: + operationId: provider_groups_relationships_providers_destroy + description: Remove the provider_group-providers relationship from the system + by their ID. + summary: Delete a provider_group-providers relationship + tags: + - Provider Group + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship deleted successfully + /api/v1/providers: + get: + operationId: providers_list + description: Retrieve a list of all providers with options for filtering by + various criteria. + summary: List all providers + parameters: + - in: query + name: fields[providers] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider + - uid + - alias + - connection + - secret + - provider_groups + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[alias] + schema: + type: string + - in: query + name: filter[alias__icontains] + schema: + type: string + - in: query + name: filter[alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[connected] + schema: + type: boolean + description: |- + Filter by connection status. Set to True to return only + connected providers, or False to return only providers with failed + connections. If not specified, both connected and failed providers are + included. Providers with no connection attempt (status is null) are + excluded from this filter. + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + description: |- + Filter by date when the provider was added + (format: YYYY-MM-DD) + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[provider] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__icontains] + schema: + type: string + - in: query + name: filter[uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + description: |- + Filter by date when the provider was updated + (format: YYYY-MM-DD) + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - provider_groups + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - provider + - -provider + - uid + - -uid + - alias + - -alias + - connected + - -connected + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedProviderList' + description: '' + post: + operationId: providers_create + description: Add a new provider to the system by providing the required provider + details. + summary: Create a new provider + tags: + - Provider + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ProviderCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ProviderCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderCreateResponse' + description: '' + /api/v1/providers/{id}: + get: + operationId: providers_retrieve + description: Fetch detailed information about a specific provider by their ID. + summary: Retrieve data from a provider + parameters: + - in: query + name: fields[providers] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - provider + - uid + - alias + - connection + - secret + - provider_groups + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - provider_groups + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderResponse' + description: '' + patch: + operationId: providers_partial_update + description: Update certain fields of an existing provider's information without + affecting other fields. + summary: Partially update a provider + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider. + required: true + tags: + - Provider + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedProviderUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedProviderUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedProviderUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SerializerMetaclassResponse' + description: '' + delete: + operationId: providers_destroy + description: Remove a provider from the system by their ID. + summary: Delete a provider + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider. + required: true + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/providers/{id}/connection: + post: + operationId: providers_connection_create + description: Try to verify connection. For instance, Role & Credentials are + set correctly + summary: Check connection + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this provider. + required: true + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/providers/secrets: + get: + operationId: providers_secrets_list + description: Retrieve a list of all secrets with options for filtering by various + criteria. + summary: List all secrets + parameters: + - in: query + name: fields[provider-secrets] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - name + - secret_type + - provider + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + description: 'Filter by date when the secret was added (format: YYYY-MM-DD)' + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + description: 'Filter by date when the secret was updated (format: YYYY-MM-DD)' + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedProviderSecretList' + description: '' + post: + operationId: providers_secrets_create + description: Add a new secret to the system by providing the required secret + details. + summary: Create a new secret + tags: + - Provider + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderSecretCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ProviderSecretCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ProviderSecretCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderSecretCreateResponse' + description: '' + /api/v1/providers/secrets/{id}: + get: + operationId: providers_secrets_retrieve + description: Fetch detailed information about a specific secret by their ID. + summary: Retrieve data from a secret + parameters: + - in: query + name: fields[provider-secrets] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - name + - secret_type + - provider + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderSecretResponse' + description: '' + patch: + operationId: providers_secrets_partial_update + description: Update certain fields of an existing secret's information without + affecting other fields. + summary: Partially update a secret + parameters: + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Provider + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedProviderSecretUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedProviderSecretUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedProviderSecretUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ProviderSecretUpdateResponse' + description: '' + delete: + operationId: providers_secrets_destroy + description: Remove a secret from the system by their ID. + summary: Delete a secret + parameters: + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Provider + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/resources: + get: + operationId: resources_list + description: Retrieve a list of all resources with options for filtering by + various criteria. Resources are objects that are discovered by Prowler. They + can be anything from a single host to a whole VPC. + summary: List all resources + parameters: + - in: query + name: fields[resources] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - uid + - name + - region + - service + - tags + - provider + - findings + - failed_findings_count + - url + - type + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan] + schema: + type: string + format: uuid + - in: query + name: filter[scan__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[tag] + schema: + type: string + - in: query + name: filter[tag_key] + schema: + type: string + - in: query + name: filter[tag_value] + schema: + type: string + - in: query + name: filter[tags] + schema: + type: string + - in: query + name: filter[type] + schema: + type: string + - in: query + name: filter[type__icontains] + schema: + type: string + - in: query + name: filter[type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__icontains] + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + description: At least one of the variations of the `filter[updated_at]` filter + must be provided. + required: true + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - findings + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - provider_uid + - -provider_uid + - uid + - -uid + - name + - -name + - region + - -region + - service + - -service + - type + - -type + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Resource + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedResourceList' + description: '' + /api/v1/resources/{id}: + get: + operationId: resources_retrieve + description: Fetch detailed information about a specific resource by their ID. + A Resource is an object that is discovered by Prowler. It can be anything + from a single host to a whole VPC. + summary: Retrieve data for a resource + parameters: + - in: query + name: fields[resources] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - uid + - name + - region + - service + - tags + - provider + - findings + - failed_findings_count + - url + - type + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this resource. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - findings + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Resource + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ResourceResponse' + description: '' + /api/v1/resources/latest: + get: + operationId: resources_latest_retrieve + description: Retrieve a list of the latest resources from the latest scans for + each provider with options for filtering by various criteria. + summary: List the latest resources + parameters: + - in: query + name: fields[resources] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - uid + - name + - region + - service + - tags + - provider + - findings + - failed_findings_count + - url + - type + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[tag] + schema: + type: string + - in: query + name: filter[tag_key] + schema: + type: string + - in: query + name: filter[tag_value] + schema: + type: string + - in: query + name: filter[tags] + schema: + type: string + - in: query + name: filter[type] + schema: + type: string + - in: query + name: filter[type__icontains] + schema: + type: string + - in: query + name: filter[type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__icontains] + schema: + type: string + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - findings + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - provider_uid + - -provider_uid + - uid + - -uid + - name + - -name + - region + - -region + - service + - -service + - type + - -type + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Resource + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ResourceResponse' + description: '' + /api/v1/resources/metadata: + get: + operationId: resources_metadata_retrieve + description: Fetch unique metadata values from a set of resources. This is useful + for dynamic filtering. + summary: Retrieve metadata values from resources + parameters: + - in: query + name: fields[resources-metadata] + schema: + type: array + items: + type: string + enum: + - services + - regions + - types + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[scan] + schema: + type: string + format: uuid + - in: query + name: filter[scan__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[tag] + schema: + type: string + - in: query + name: filter[tag_key] + schema: + type: string + - in: query + name: filter[tag_value] + schema: + type: string + - in: query + name: filter[tags] + schema: + type: string + - in: query + name: filter[type] + schema: + type: string + - in: query + name: filter[type__icontains] + schema: + type: string + - in: query + name: filter[type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__icontains] + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + description: At least one of the variations of the `filter[updated_at]` filter + must be provided. + required: true + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - provider_uid + - -provider_uid + - uid + - -uid + - name + - -name + - region + - -region + - service + - -service + - type + - -type + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Resource + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ResourceMetadataResponse' + description: '' + /api/v1/resources/metadata/latest: + get: + operationId: resources_metadata_latest_retrieve + description: Fetch unique metadata values from a set of resources from the latest + scans for each provider. This is useful for dynamic filtering. + summary: Retrieve metadata values from the latest resources + parameters: + - in: query + name: fields[resources-metadata] + schema: + type: array + items: + type: string + enum: + - services + - regions + - types + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[region] + schema: + type: string + - in: query + name: filter[region__icontains] + schema: + type: string + - in: query + name: filter[region__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[service] + schema: + type: string + - in: query + name: filter[service__icontains] + schema: + type: string + - in: query + name: filter[service__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[tag] + schema: + type: string + - in: query + name: filter[tag_key] + schema: + type: string + - in: query + name: filter[tag_value] + schema: + type: string + - in: query + name: filter[tags] + schema: + type: string + - in: query + name: filter[type] + schema: + type: string + - in: query + name: filter[type__icontains] + schema: + type: string + - in: query + name: filter[type__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[uid] + schema: + type: string + - in: query + name: filter[uid__icontains] + schema: + type: string + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - provider_uid + - -provider_uid + - uid + - -uid + - name + - -name + - region + - -region + - service + - -service + - type + - -type + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Resource + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ResourceMetadataResponse' + description: '' + /api/v1/roles: + get: + operationId: roles_list + description: Retrieve a list of all roles with options for filtering by various + criteria. + summary: List all roles + parameters: + - in: query + name: fields[roles] + schema: + type: array + items: + type: string + enum: + - name + - manage_users + - manage_account + - manage_integrations + - manage_providers + - manage_scans + - permission_state + - unlimited_visibility + - inserted_at + - updated_at + - provider_groups + - users + - invitations + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[id] + schema: + type: string + format: uuid + - in: query + name: filter[id__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[permission_state] + schema: + type: string + enum: + - limited + - none + - unlimited + description: |- + * `unlimited` - Unlimited permissions + * `limited` - Limited permissions + * `none` - No permissions + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - name + - -name + - manage_users + - -manage_users + - manage_account + - -manage_account + - manage_integrations + - -manage_integrations + - manage_providers + - -manage_providers + - manage_scans + - -manage_scans + - permission_state + - -permission_state + - unlimited_visibility + - -unlimited_visibility + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - provider_groups + - -provider_groups + - users + - -users + - invitations + - -invitations + - url + - -url + explode: false + tags: + - Role + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedRoleList' + description: '' + post: + operationId: roles_create + description: Add a new role to the system by providing the required role details. + summary: Create a new role + tags: + - Role + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/RoleCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/RoleCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/RoleCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/RoleCreateResponse' + description: '' + /api/v1/roles/{id}: + get: + operationId: roles_retrieve + description: Fetch detailed information about a specific role by their ID. + summary: Retrieve data from a role + parameters: + - in: query + name: fields[roles] + schema: + type: array + items: + type: string + enum: + - name + - manage_users + - manage_account + - manage_integrations + - manage_providers + - manage_scans + - permission_state + - unlimited_visibility + - inserted_at + - updated_at + - provider_groups + - users + - invitations + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this role. + required: true + tags: + - Role + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/RoleResponse' + description: '' + patch: + operationId: roles_partial_update + description: Update selected fields on an existing role. When changing the `users` + relationship of a role that grants MANAGE_ACCOUNT, the API blocks attempts + that would leave the tenant without any MANAGE_ACCOUNT assignees and prevents + callers from removing their own assignment to that role. + summary: Partially update a role + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this role. + required: true + tags: + - Role + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedRoleUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedRoleUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedRoleUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SerializerMetaclassResponse' + description: '' + delete: + operationId: roles_destroy + description: Delete the specified role. The API rejects deletion of the last + role in the tenant that grants MANAGE_ACCOUNT. + summary: Delete a role + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this role. + required: true + tags: + - Role + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/roles/{id}/relationships/provider_groups: + post: + operationId: roles_relationships_provider_groups_create + description: Add a new role-provider_groups relationship to the system by providing + the required role-provider_groups details. + summary: Create a new role-provider_groups relationship + tags: + - Role + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/RoleProviderGroupRelationshipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/RoleProviderGroupRelationshipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/RoleProviderGroupRelationshipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship created successfully + '400': + description: Bad request (e.g., relationship already exists) + patch: + operationId: roles_relationships_provider_groups_partial_update + description: Update the role-provider_groups relationship information without + affecting other fields. + summary: Partially update a role-provider_groups relationship + tags: + - Role + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedRoleProviderGroupRelationshipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedRoleProviderGroupRelationshipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedRoleProviderGroupRelationshipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship updated successfully + delete: + operationId: roles_relationships_provider_groups_destroy + description: Remove the role-provider_groups relationship from the system by + their ID. + summary: Delete a role-provider_groups relationship + tags: + - Role + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship deleted successfully + /api/v1/saml-config: + get: + operationId: saml_config_list + description: Returns all the SAML-based SSO configurations associated with the + current tenant. + summary: List all SSO configurations + parameters: + - in: query + name: fields[saml-configurations] + schema: + type: array + items: + type: string + enum: + - email_domain + - metadata_xml + - created_at + - updated_at + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - email_domain + - -email_domain + - metadata_xml + - -metadata_xml + - created_at + - -created_at + - updated_at + - -updated_at + explode: false + tags: + - SAML + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedSAMLConfigurationList' + description: '' + post: + operationId: saml_config_create + description: Creates a new SAML SSO configuration for the current tenant, including + email domain and metadata XML. + summary: Create the SSO configuration + tags: + - SAML + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SAMLConfigurationRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/SAMLConfigurationRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/SAMLConfigurationRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SAMLConfigurationResponse' + description: '' + /api/v1/saml-config/{id}: + get: + operationId: saml_config_retrieve + description: Returns the details of a specific SAML configuration belonging + to the current tenant. + summary: Retrieve SSO configuration details + parameters: + - in: query + name: fields[saml-configurations] + schema: + type: array + items: + type: string + enum: + - email_domain + - metadata_xml + - created_at + - updated_at + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this saml configuration. + required: true + tags: + - SAML + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SAMLConfigurationResponse' + description: '' + patch: + operationId: saml_config_partial_update + description: Partially updates an existing SAML SSO configuration. Supports + changes to email domain and metadata XML. + summary: Update the SSO configuration + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this saml configuration. + required: true + tags: + - SAML + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedSAMLConfigurationRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedSAMLConfigurationRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedSAMLConfigurationRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/SAMLConfigurationResponse' + description: '' + delete: + operationId: saml_config_destroy + description: Deletes an existing SAML SSO configuration associated with the + current tenant. + summary: Delete the SSO configuration + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this saml configuration. + required: true + tags: + - SAML + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/scans: + get: + operationId: scans_list + description: Retrieve a list of all scans with options for filtering by various + criteria. + summary: List all scans + parameters: + - in: query + name: fields[scans] + schema: + type: array + items: + type: string + enum: + - name + - trigger + - state + - unique_resource_count + - progress + - duration + - provider + - task + - inserted_at + - started_at + - completed_at + - scheduled_at + - next_scan_at + - processor + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[completed_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - in: query + name: filter[next_scan_at] + schema: + type: string + format: date + - in: query + name: filter[next_scan_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[next_scan_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[provider] + schema: + type: string + format: uuid + - in: query + name: filter[provider__in] + schema: + type: array + items: + type: string + format: uuid + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_alias] + schema: + type: string + - in: query + name: filter[provider_alias__icontains] + schema: + type: string + - in: query + name: filter[provider_alias__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - in: query + name: filter[provider_type] + schema: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + - in: query + name: filter[provider_type__in] + schema: + type: array + items: + type: string + x-spec-enum-id: 6f034074d7104650 + enum: + - aws + - azure + - gcp + - github + - kubernetes + - m365 + - oci + description: |- + Multiple values may be separated by commas. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + explode: false + style: form + - in: query + name: filter[provider_uid] + schema: + type: string + - in: query + name: filter[provider_uid__icontains] + schema: + type: string + - in: query + name: filter[provider_uid__in] + schema: + type: array + items: + type: string + description: Multiple values may be separated by commas. + explode: false + style: form + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[started_at] + schema: + type: string + format: date + - in: query + name: filter[started_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[started_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[state] + schema: + type: string + x-spec-enum-id: d38ba07264e1ed34 + enum: + - available + - cancelled + - completed + - executing + - failed + - scheduled + description: |- + * `available` - Available + * `scheduled` - Scheduled + * `executing` - Executing + * `completed` - Completed + * `failed` - Failed + * `cancelled` - Cancelled + - in: query + name: filter[state__in] + schema: + type: array + items: + type: string + x-spec-enum-id: d38ba07264e1ed34 + enum: + - available + - cancelled + - completed + - executing + - failed + - scheduled + description: |- + Multiple values may be separated by commas. + + * `available` - Available + * `scheduled` - Scheduled + * `executing` - Executing + * `completed` - Completed + * `failed` - Failed + * `cancelled` - Cancelled + explode: false + style: form + - in: query + name: filter[trigger] + schema: + type: string + x-spec-enum-id: 2e52c981d1c89bdf + enum: + - manual + - scheduled + description: |- + * `scheduled` - Scheduled + * `manual` - Manual + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - trigger + - -trigger + - attempted_at + - -attempted_at + - scheduled_at + - -scheduled_at + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Scan + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedScanList' + description: '' + post: + operationId: scans_create + description: Trigger a manual scan by providing the required scan details. If + `scanner_args` are not provided, the system will automatically use the default + settings from the associated provider. If you do provide `scanner_args`, these + settings will be merged with the provider's defaults. This means that your + provided settings will override the defaults only where they conflict, while + the rest of the default settings will remain intact. + summary: Trigger a manual scan + tags: + - Scan + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ScanCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ScanCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ScanCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/scans/{id}: + get: + operationId: scans_retrieve + description: Fetch detailed information about a specific scan by its ID. + summary: Retrieve data from a specific scan + parameters: + - in: query + name: fields[scans] + schema: + type: array + items: + type: string + enum: + - name + - trigger + - state + - unique_resource_count + - progress + - duration + - provider + - task + - inserted_at + - started_at + - completed_at + - scheduled_at + - next_scan_at + - processor + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this scan. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Scan + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ScanResponse' + description: '' + patch: + operationId: scans_partial_update + description: Update certain fields of an existing scan without affecting other + fields. + summary: Partially update a scan + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this scan. + required: true + tags: + - Scan + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedScanUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedScanUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedScanUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ScanUpdateResponse' + description: '' + /api/v1/scans/{id}/compliance/{name}: + get: + operationId: scans_compliance_retrieve + description: Download a specific compliance report (e.g., 'cis_1.4_aws') as + a CSV file. + summary: Retrieve compliance report as CSV + parameters: + - in: query + name: fields[scan-reports] + schema: + type: array + items: + type: string + enum: + - id + - name + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this scan. + required: true + - in: path + name: name + schema: + type: string + description: The compliance report name, like 'cis_1.4_aws' + required: true + tags: + - Scan + security: + - JWT or API Key: [] + responses: + '200': + description: CSV file containing the compliance report + '404': + description: Compliance report not found + /api/v1/scans/{id}/report: + get: + operationId: scans_report_retrieve + description: Returns a ZIP file containing the requested report + summary: Download ZIP report + parameters: + - in: query + name: fields[scan-reports] + schema: + type: array + items: + type: string + enum: + - id + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this scan. + required: true + tags: + - Scan + security: + - JWT or API Key: [] + responses: + '200': + description: Report obtained successfully + '202': + description: The task is in progress + '403': + description: There is a problem with credentials + '404': + description: The scan has no reports, or the report generation task has + not started yet + /api/v1/scans/{id}/threatscore: + get: + operationId: scans_threatscore_retrieve + description: Download a specific threatscore report (e.g., 'prowler_threatscore_aws') + as a PDF file. + summary: Retrieve threatscore report + parameters: + - in: query + name: fields[scans] + schema: + type: array + items: + type: string + enum: + - name + - trigger + - state + - unique_resource_count + - progress + - duration + - provider + - task + - inserted_at + - started_at + - completed_at + - scheduled_at + - next_scan_at + - processor + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this scan. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - provider + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - Scan + security: + - JWT or API Key: [] + responses: + '200': + description: PDF file containing the threatscore report + '202': + description: The task is in progress + '401': + description: API key missing or user not Authenticated + '403': + description: There is a problem with credentials + '404': + description: The scan has no threatscore reports, or the threatscore report + generation task has not started yet + /api/v1/schedules/daily: + post: + operationId: schedules_daily_create + description: Schedules a daily scan for the specified provider. This endpoint + creates a periodic task that will execute a scan every 24 hours. + summary: Create a daily schedule scan for a given provider + tags: + - Schedule + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/ScheduleDailyCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/ScheduleDailyCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/ScheduleDailyCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/tasks: + get: + operationId: tasks_list + description: Retrieve a list of all tasks with options for filtering by name, + state, and other criteria. + summary: List all tasks + parameters: + - in: query + name: fields[tasks] + schema: + type: array + items: + type: string + enum: + - inserted_at + - completed_at + - name + - state + - result + - task_args + - metadata + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[state] + schema: + type: string + title: Task State + enum: + - available + - cancelled + - completed + - executing + - failed + - scheduled + description: |- + Current state of the task being run + + * `available` - Available + * `scheduled` - Scheduled + * `executing` - Executing + * `completed` - Completed + * `failed` - Failed + * `cancelled` - Cancelled + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - inserted_at + - -inserted_at + - completed_at + - -completed_at + - name + - -name + - state + - -state + explode: false + tags: + - Task + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedTaskList' + description: '' + /api/v1/tasks/{id}: + get: + operationId: tasks_retrieve + description: Fetch detailed information about a specific task by its ID. + summary: Retrieve data from a specific task + parameters: + - in: query + name: fields[tasks] + schema: + type: array + items: + type: string + enum: + - inserted_at + - completed_at + - name + - state + - result + - task_args + - metadata + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this task. + required: true + tags: + - Task + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + description: '' + delete: + operationId: tasks_destroy + description: Try to revoke a task using its ID. Only tasks that are not yet + in progress can be revoked. + summary: Revoke a task + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this task. + required: true + tags: + - Task + security: + - JWT or API Key: [] + responses: + '202': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TaskResponse' + examples: + Task queued: + summary: Task queued + value: + data: + type: tasks + id: 497f6eca-6276-4993-bfeb-53cbbbba6f08 + attributes: + inserted_at: '2019-08-24T14:15:22Z' + completed_at: '2019-08-24T14:15:22Z' + name: string + state: available + result: null + task_args: null + metadata: null + description: '' + /api/v1/tenants: + get: + operationId: tenants_list + description: Retrieve a list of all tenants with options for filtering by various + criteria. + summary: List all tenants + parameters: + - in: query + name: fields[tenants] + schema: + type: array + items: + type: string + enum: + - name + - memberships + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - inserted_at + - -inserted_at + - updated_at + - -updated_at + explode: false + tags: + - Tenant + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedTenantList' + description: '' + post: + operationId: tenants_create + description: Add a new tenant to the system by providing the required tenant + details. + summary: Create a new tenant + tags: + - Tenant + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/TenantRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/TenantRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantResponse' + description: '' + /api/v1/tenants/{id}: + get: + operationId: tenants_retrieve + description: Fetch detailed information about a specific tenant by their ID. + summary: Retrieve data from a tenant + parameters: + - in: query + name: fields[tenants] + schema: + type: array + items: + type: string + enum: + - name + - memberships + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant. + required: true + tags: + - Tenant + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantResponse' + description: '' + patch: + operationId: tenants_partial_update + description: Update certain fields of an existing tenant's information without + affecting other fields. + summary: Partially update a tenant + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant. + required: true + tags: + - Tenant + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedTenantRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedTenantRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedTenantRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TenantResponse' + description: '' + delete: + operationId: tenants_destroy + description: Remove a tenant from the system by their ID. + summary: Delete a tenant + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this tenant. + required: true + tags: + - Tenant + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/tenants/{tenant_pk}/memberships: + get: + operationId: tenants_memberships_list + description: List the membership details of users in a tenant you are a part + of. + summary: List tenant memberships + parameters: + - in: query + name: fields[memberships] + schema: + type: array + items: + type: string + enum: + - user + - tenant + - role + - date_joined + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - id + - -id + - user + - -user + - tenant + - -tenant + - role + - -role + - date_joined + - -date_joined + explode: false + - in: path + name: tenant_pk + schema: + type: string + format: uuid + description: Tenant ID + required: true + tags: + - Tenant + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedMembershipList' + description: '' + /api/v1/tenants/{tenant_pk}/memberships/{id}: + delete: + operationId: tenants_memberships_destroy + description: Delete the membership details of users in a tenant. You need to + be one of the owners to delete a membership that is not yours. If you are + the last owner of a tenant, you cannot delete your own membership. + summary: Delete tenant memberships + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this membership. + required: true + - in: path + name: tenant_pk + schema: + type: string + format: uuid + required: true + tags: + - Tenant + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/tenants/invitations: + get: + operationId: tenants_invitations_list + description: Retrieve a list of all tenant invitations with options for filtering + by various criteria. + summary: List all invitations + parameters: + - in: query + name: fields[invitations] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - email + - state + - token + - roles + - expires_at + - inviter + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[email] + schema: + type: string + - in: query + name: filter[email__icontains] + schema: + type: string + - in: query + name: filter[expires_at] + schema: + type: string + format: date + - in: query + name: filter[expires_at__date] + schema: + type: string + format: date + - in: query + name: filter[expires_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[expires_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__date] + schema: + type: string + format: date + - in: query + name: filter[inserted_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[inserted_at__lte] + schema: + type: string + format: date-time + - in: query + name: filter[inviter] + schema: + type: string + format: uuid + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[state] + schema: + type: string + x-spec-enum-id: 92a1c1fd12e13e25 + enum: + - accepted + - expired + - pending + - revoked + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + - in: query + name: filter[state__in] + schema: + type: array + items: + type: string + enum: + - accepted + - expired + - pending + - revoked + description: |- + Multiple values may be separated by commas. + + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + explode: false + style: form + - in: query + name: filter[updated_at] + schema: + type: string + format: date + - in: query + name: filter[updated_at__date] + schema: + type: string + format: date + - in: query + name: filter[updated_at__gte] + schema: + type: string + format: date-time + - in: query + name: filter[updated_at__lte] + schema: + type: string + format: date-time + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - inserted_at + - -inserted_at + - updated_at + - -updated_at + - expires_at + - -expires_at + - state + - -state + - inviter + - -inviter + explode: false + tags: + - Invitation + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedInvitationList' + description: '' + post: + operationId: tenants_invitations_create + description: Add a new tenant invitation to the system by providing the required + invitation details. The invited user will have to accept the invitations or + create an account using the given code. + summary: Invite a user to a tenant + tags: + - Invitation + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/InvitationCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/InvitationCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/InvitationCreateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/InvitationCreateResponse' + description: '' + /api/v1/tenants/invitations/{id}: + get: + operationId: tenants_invitations_retrieve + description: Fetch detailed information about a specific invitation by its ID. + summary: Retrieve data from a tenant invitation + parameters: + - in: query + name: fields[invitations] + schema: + type: array + items: + type: string + enum: + - inserted_at + - updated_at + - email + - state + - token + - roles + - expires_at + - inviter + - url + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Invitation + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/InvitationResponse' + description: '' + patch: + operationId: tenants_invitations_partial_update + description: Update certain fields of an existing tenant invitation's information + without affecting other fields. + summary: Partially update a tenant invitation + parameters: + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Invitation + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedInvitationUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedInvitationUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedInvitationUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/InvitationUpdateResponse' + description: '' + delete: + operationId: tenants_invitations_destroy + description: Revoke a tenant invitation from the system by their ID. + summary: Revoke a tenant invitation + parameters: + - in: path + name: id + schema: + type: string + format: uuid + required: true + tags: + - Invitation + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/tokens: + post: + operationId: tokens_create + description: Obtain a token by providing valid credentials and an optional tenant + ID. + summary: Obtain a token + tags: + - Token + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/TokenRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/TokenRequest' + required: true + security: + - JWT or API Key: [] + - {} + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenResponse' + description: '' + /api/v1/tokens/refresh: + post: + operationId: tokens_refresh_create + description: Refresh an access token by providing a valid refresh token. Former + refresh tokens are invalidated when a new one is issued. + summary: Refresh a token + tags: + - Token + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenRefreshRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/TokenRefreshRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/TokenRefreshRequest' + required: true + security: + - JWT or API Key: [] + - {} + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenRefreshResponse' + description: '' + /api/v1/tokens/switch: + post: + operationId: tokens_switch_create + description: Switch tenant by providing a valid tenant ID. The authenticated + user must belong to the tenant. + summary: Switch tenant using a valid tenant ID + tags: + - Token + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenSwitchTenantRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/TokenSwitchTenantRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/TokenSwitchTenantRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/TokenSwitchTenantResponse' + description: '' + /api/v1/users: + get: + operationId: users_list + description: Retrieve a list of all users with options for filtering by various + criteria. + summary: List all users + parameters: + - in: query + name: fields[users] + schema: + type: array + items: + type: string + enum: + - name + - email + - company_name + - date_joined + - memberships + - roles + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[company_name] + schema: + type: string + - in: query + name: filter[company_name__icontains] + schema: + type: string + - in: query + name: filter[date_joined] + schema: + type: string + format: date + - in: query + name: filter[date_joined__date] + schema: + type: string + format: date + - in: query + name: filter[date_joined__gte] + schema: + type: string + format: date-time + - in: query + name: filter[date_joined__lte] + schema: + type: string + format: date-time + - in: query + name: filter[email] + schema: + type: string + - in: query + name: filter[email__icontains] + schema: + type: string + - in: query + name: filter[is_active] + schema: + type: boolean + - in: query + name: filter[name] + schema: + type: string + - in: query + name: filter[name__icontains] + schema: + type: string + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - roles + - memberships + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - name + - -name + - email + - -email + - company_name + - -company_name + - date_joined + - -date_joined + - is_active + - -is_active + explode: false + tags: + - User + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedUserList' + description: '' + post: + operationId: users_create + description: Create a new user account by providing the necessary registration + details. + summary: Register a new user + parameters: + - in: query + name: invitation_token + schema: + type: string + example: F3NMFPNDZHR4Z9 + description: Optional invitation code for joining an existing tenant. + tags: + - User + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserCreateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UserCreateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/UserCreateRequest' + required: true + security: + - JWT or API Key: [] + - {} + responses: + '201': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserCreateResponse' + description: '' + /api/v1/users/{id}: + get: + operationId: users_retrieve + description: Fetch detailed information about an authenticated user. + summary: Retrieve a user's information + parameters: + - in: query + name: fields[users] + schema: + type: array + items: + type: string + enum: + - name + - email + - company_name + - date_joined + - memberships + - roles + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this user. + required: true + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - roles + - memberships + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - User + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserResponse' + description: '' + patch: + operationId: users_partial_update + description: Partially update information about a user. + summary: Update user information + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this user. + required: true + tags: + - User + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedUserUpdateRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedUserUpdateRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedUserUpdateRequest' + required: true + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserUpdateResponse' + description: '' + delete: + operationId: users_destroy + description: Remove the current user account from the system. + summary: Delete the user account + parameters: + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this user. + required: true + tags: + - User + security: + - JWT or API Key: [] + responses: + '204': + description: No response body + /api/v1/users/{id}/relationships/roles: + post: + operationId: users_relationships_roles_create + description: Add a new user-roles relationship to the system by providing the + required user-roles details. + summary: Create a new user-roles relationship + tags: + - User + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserRoleRelationshipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/UserRoleRelationshipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/UserRoleRelationshipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship created successfully + '400': + description: Bad request (e.g., relationship already exists) + patch: + operationId: users_relationships_roles_partial_update + description: Update the user-roles relationship information without affecting + other fields. If the update would remove MANAGE_ACCOUNT from the last remaining + user in the tenant, the API rejects the request with a 400 response. + summary: Partially update a user-roles relationship + tags: + - User + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PatchedUserRoleRelationshipRequest' + application/x-www-form-urlencoded: + schema: + $ref: '#/components/schemas/PatchedUserRoleRelationshipRequest' + multipart/form-data: + schema: + $ref: '#/components/schemas/PatchedUserRoleRelationshipRequest' + required: true + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship updated successfully + delete: + operationId: users_relationships_roles_destroy + description: Remove the user-roles relationship from the system by their ID. + If removing MANAGE_ACCOUNT would take it away from the last remaining user + in the tenant, the API rejects the request with a 400 response. Users also + cannot delete their own role assignments; attempting to do so returns a 400 + response. + summary: Delete a user-roles relationship + tags: + - User + security: + - JWT or API Key: [] + responses: + '204': + description: Relationship deleted successfully + /api/v1/users/{user_pk}/memberships: + get: + operationId: users_memberships_list + description: Retrieve a list of all user memberships with options for filtering + by various criteria. + summary: List user memberships + parameters: + - in: query + name: fields[memberships] + schema: + type: array + items: + type: string + enum: + - user + - tenant + - role + - date_joined + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: filter[date_joined] + schema: + type: string + format: date + - in: query + name: filter[date_joined__date] + schema: + type: string + format: date + - in: query + name: filter[date_joined__gte] + schema: + type: string + format: date-time + - in: query + name: filter[date_joined__lte] + schema: + type: string + format: date-time + - in: query + name: filter[role] + schema: + type: string + x-spec-enum-id: 12c359ee5dc51001 + enum: + - member + - owner + description: |- + * `owner` - Owner + * `member` - Member + - name: filter[search] + required: false + in: query + description: A search term. + schema: + type: string + - in: query + name: filter[tenant] + schema: + type: string + format: uuid + - name: page[number] + required: false + in: query + description: A page number within the paginated result set. + schema: + type: integer + - name: page[size] + required: false + in: query + description: Number of results to return per page. + schema: + type: integer + - name: sort + required: false + in: query + description: '[list of fields to sort by](https://jsonapi.org/format/#fetching-sorting)' + schema: + type: array + items: + type: string + enum: + - tenant + - -tenant + - role + - -role + - date_joined + - -date_joined + explode: false + - in: path + name: user_pk + schema: + type: string + format: uuid + required: true + tags: + - User + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/PaginatedMembershipList' + description: '' + /api/v1/users/{user_pk}/memberships/{id}: + get: + operationId: users_memberships_retrieve + description: Fetch detailed information about a specific user membership by + their ID. + summary: Retrieve membership data from the user + parameters: + - in: query + name: fields[memberships] + schema: + type: array + items: + type: string + enum: + - user + - tenant + - role + - date_joined + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: path + name: id + schema: + type: string + format: uuid + description: A UUID string identifying this membership. + required: true + - in: path + name: user_pk + schema: + type: string + format: uuid + required: true + tags: + - User + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/MembershipResponse' + description: '' + /api/v1/users/me: + get: + operationId: users_me_retrieve + description: Fetch detailed information about the authenticated user. + summary: Retrieve the current user's information + parameters: + - in: query + name: fields[users] + schema: + type: array + items: + type: string + enum: + - name + - email + - company_name + - date_joined + - memberships + - roles + description: endpoint return only specific fields in the response on a per-type + basis by including a fields[TYPE] query parameter. + explode: false + - in: query + name: include + schema: + type: array + items: + type: string + enum: + - roles + - memberships + description: include query parameter to allow the client to customize which + related resources should be returned. + explode: false + tags: + - User + security: + - JWT or API Key: [] + responses: + '200': + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/UserResponse' + description: '' +components: + schemas: + ComplianceOverview: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - compliance-overviews + id: {} + attributes: + type: object + properties: + id: + type: string + framework: + type: string + version: + type: string + requirements_passed: + type: integer + requirements_failed: + type: integer + requirements_manual: + type: integer + total_requirements: + type: integer + required: + - id + - framework + - version + - requirements_passed + - requirements_failed + - requirements_manual + - total_requirements + ComplianceOverviewAttributes: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - compliance-requirements-attributes + id: {} + attributes: + type: object + properties: + id: + type: string + compliance_name: + type: string + framework_description: + type: string + name: + type: string + framework: + type: string + version: + type: string + description: + type: string + attributes: {} + required: + - id + - compliance_name + - framework_description + - name + - framework + - version + - description + - attributes + ComplianceOverviewDetail: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - compliance-requirements-details + id: {} + attributes: + type: object + properties: + id: + type: string + framework: + type: string + version: + type: string + description: + type: string + status: + enum: + - FAIL + - PASS + - MANUAL + type: string + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + x-spec-enum-id: ce612ddbfa464789 + required: + - id + - framework + - version + - description + - status + ComplianceOverviewMetadata: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - compliance-overviews-metadata + id: {} + attributes: + type: object + properties: + regions: + type: array + items: + type: string + required: + - regions + Finding: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - findings + id: + type: string + format: uuid + attributes: + type: object + properties: + uid: + type: string + maxLength: 300 + delta: + enum: + - new + - changed + - null + type: string + description: |- + * `new` - New + * `changed` - Changed + x-spec-enum-id: fef6b0e2506af8bc + nullable: true + status: + enum: + - FAIL + - PASS + - MANUAL + type: string + description: |- + * `FAIL` - Fail + * `PASS` - Pass + * `MANUAL` - Manual + x-spec-enum-id: ce612ddbfa464789 + status_extended: + type: string + nullable: true + severity: + enum: + - critical + - high + - medium + - low + - informational + type: string + description: |- + * `critical` - Critical + * `high` - High + * `medium` - Medium + * `low` - Low + * `informational` - Informational + x-spec-enum-id: c93e070ed135d9bf + check_id: + type: string + maxLength: 100 + check_metadata: {} + raw_result: {} + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + first_seen_at: + type: string + format: date-time + readOnly: true + nullable: true + muted: + type: boolean + muted_reason: + type: string + nullable: true + minLength: 3 + maxLength: 500 + required: + - uid + - status + - severity + - check_id + relationships: + type: object + properties: + scan: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - scans + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + resources: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - resources + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type resources + title: resources + readOnly: true + required: + - scan + FindingDynamicFilter: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - finding-dynamic-filters + id: {} + attributes: + type: object + properties: + services: + type: array + items: + type: string + regions: + type: array + items: + type: string + required: + - services + - regions + FindingDynamicFilterResponse: + type: object + properties: + data: + $ref: '#/components/schemas/FindingDynamicFilter' + required: + - data + FindingMetadata: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - findings-metadata + id: {} + attributes: + type: object + properties: + services: + type: array + items: + type: string + regions: + type: array + items: + type: string + resource_types: + type: array + items: + type: string + required: + - services + - regions + - resource_types + FindingMetadataResponse: + type: object + properties: + data: + $ref: '#/components/schemas/FindingMetadata' + required: + - data + FindingResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Finding' + required: + - data + Integration: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + enabled: + type: boolean + connected: + type: boolean + nullable: true + connection_last_checked_at: + type: string + format: date-time + nullable: true + integration_type: + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + type: string + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + x-spec-enum-id: 6cfd0ff9cf4d6dcc + configuration: {} + required: + - integration_type + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + required: + - providers + IntegrationCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + enabled: + type: boolean + connected: + type: boolean + readOnly: true + nullable: true + connection_last_checked_at: + type: string + format: date-time + readOnly: true + nullable: true + integration_type: + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + type: string + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + x-spec-enum-id: 6cfd0ff9cf4d6dcc + configuration: + oneOf: + - type: object + title: Amazon S3 + properties: + bucket_name: + type: string + description: The name of the S3 bucket where files will be stored. + output_directory: + type: string + description: 'The directory path within the bucket where files + will be saved. Optional - defaults to "output" if not provided. + Path will be normalized to remove excessive slashes and invalid + characters are not allowed (< > : " | ? *). Maximum length is + 900 characters.' + maxLength: 900 + pattern: ^[^<>:"|?*]+$ + default: output + required: + - bucket_name + - type: object + title: AWS Security Hub + properties: + send_only_fails: + type: boolean + default: false + description: If true, only findings with status 'FAIL' will be + sent to Security Hub. + archive_previous_findings: + type: boolean + default: false + description: If true, archives findings that are not present in + the current execution. + - type: object + title: JIRA + description: JIRA integration does not accept any configuration in + the payload. Leave it as an empty JSON object (`{}`). + properties: {} + additionalProperties: false + credentials: + oneOf: + - type: object + title: AWS Credentials + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to assume. + Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + - type: object + title: JIRA Credentials + properties: + user_mail: + type: string + format: email + description: The email address of the JIRA user account. + api_token: + type: string + description: The API token for authentication with JIRA. This + can be generated from your Atlassian account settings. + domain: + type: string + description: The JIRA domain/instance URL (e.g., 'your-domain.atlassian.net'). + required: + - user_mail + - api_token + - domain + writeOnly: true + required: + - integration_type + - configuration + - credentials + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + IntegrationCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + enabled: + type: boolean + connected: + type: boolean + readOnly: true + nullable: true + connection_last_checked_at: + type: string + format: date-time + readOnly: true + nullable: true + integration_type: + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + type: string + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + x-spec-enum-id: 6cfd0ff9cf4d6dcc + configuration: + oneOf: + - type: object + title: Amazon S3 + properties: + bucket_name: + type: string + description: The name of the S3 bucket where files will be + stored. + output_directory: + type: string + description: 'The directory path within the bucket where files + will be saved. Optional - defaults to "output" if not provided. + Path will be normalized to remove excessive slashes and + invalid characters are not allowed (< > : " | ? *). Maximum + length is 900 characters.' + maxLength: 900 + pattern: ^[^<>:"|?*]+$ + default: output + required: + - bucket_name + - type: object + title: AWS Security Hub + properties: + send_only_fails: + type: boolean + default: false + description: If true, only findings with status 'FAIL' will + be sent to Security Hub. + archive_previous_findings: + type: boolean + default: false + description: If true, archives findings that are not present + in the current execution. + - type: object + title: JIRA + description: JIRA integration does not accept any configuration + in the payload. Leave it as an empty JSON object (`{}`). + properties: {} + additionalProperties: false + credentials: + oneOf: + - type: object + title: AWS Credentials + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to + assume. Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, + if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + - type: object + title: JIRA Credentials + properties: + user_mail: + type: string + format: email + description: The email address of the JIRA user account. + api_token: + type: string + description: The API token for authentication with JIRA. This + can be generated from your Atlassian account settings. + domain: + type: string + description: The JIRA domain/instance URL (e.g., 'your-domain.atlassian.net'). + required: + - user_mail + - api_token + - domain + writeOnly: true + required: + - integration_type + - configuration + - credentials + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + required: + - data + IntegrationCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/IntegrationCreate' + required: + - data + IntegrationJiraDispatchRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations-jira-dispatches + attributes: + type: object + properties: + project_key: + type: string + minLength: 1 + issue_type: + enum: + - Task + type: string + description: '* `Task` - Task' + x-spec-enum-id: b527b0cec62087c1 + required: + - project_key + - issue_type + required: + - data + IntegrationResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Integration' + required: + - data + IntegrationUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations + id: {} + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + enabled: + type: boolean + connected: + type: boolean + readOnly: true + nullable: true + connection_last_checked_at: + type: string + format: date-time + readOnly: true + nullable: true + integration_type: + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + type: string + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + x-spec-enum-id: 6cfd0ff9cf4d6dcc + readOnly: true + configuration: + oneOf: + - type: object + title: Amazon S3 + properties: + bucket_name: + type: string + description: The name of the S3 bucket where files will be stored. + output_directory: + type: string + description: 'The directory path within the bucket where files + will be saved. Optional - defaults to "output" if not provided. + Path will be normalized to remove excessive slashes and invalid + characters are not allowed (< > : " | ? *). Maximum length is + 900 characters.' + maxLength: 900 + pattern: ^[^<>:"|?*]+$ + default: output + required: + - bucket_name + - type: object + title: AWS Security Hub + properties: + send_only_fails: + type: boolean + default: false + description: If true, only findings with status 'FAIL' will be + sent to Security Hub. + archive_previous_findings: + type: boolean + default: false + description: If true, archives findings that are not present in + the current execution. + - type: object + title: JIRA + description: JIRA integration does not accept any configuration in + the payload. Leave it as an empty JSON object (`{}`). + properties: {} + additionalProperties: false + credentials: + oneOf: + - type: object + title: AWS Credentials + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to assume. + Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + - type: object + title: JIRA Credentials + properties: + user_mail: + type: string + format: email + description: The email address of the JIRA user account. + api_token: + type: string + description: The API token for authentication with JIRA. This + can be generated from your Atlassian account settings. + domain: + type: string + description: The JIRA domain/instance URL (e.g., 'your-domain.atlassian.net'). + required: + - user_mail + - api_token + - domain + writeOnly: true + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + IntegrationUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/IntegrationUpdate' + required: + - data + Invitation: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + email: + type: string + format: email + maxLength: 254 + state: + enum: + - pending + - accepted + - expired + - revoked + type: string + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + x-spec-enum-id: 92a1c1fd12e13e25 + token: + type: string + readOnly: true + expires_at: + type: string + format: date-time + required: + - email + relationships: + type: object + properties: + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + inviter: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + nullable: true + required: + - roles + InvitationAcceptRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + attributes: + type: object + properties: + invitation_token: + type: string + writeOnly: true + minLength: 1 + required: + - invitation_token + required: + - data + InvitationCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + attributes: + type: object + properties: + email: + type: string + format: email + maxLength: 254 + expires_at: + type: string + format: date-time + description: UTC. Default 7 days. If this attribute is provided, it + must be at least 24 hours in the future. + state: + enum: + - pending + - accepted + - expired + - revoked + type: string + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + x-spec-enum-id: 92a1c1fd12e13e25 + readOnly: true + token: + type: string + readOnly: true + required: + - email + relationships: + type: object + properties: + inviter: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + required: + - roles + InvitationCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + attributes: + type: object + properties: + email: + type: string + format: email + minLength: 1 + maxLength: 254 + expires_at: + type: string + format: date-time + description: UTC. Default 7 days. If this attribute is provided, + it must be at least 24 hours in the future. + state: + enum: + - pending + - accepted + - expired + - revoked + type: string + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + x-spec-enum-id: 92a1c1fd12e13e25 + readOnly: true + token: + type: string + readOnly: true + minLength: 1 + required: + - email + relationships: + type: object + properties: + inviter: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + required: + - roles + required: + - data + InvitationCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/InvitationCreate' + required: + - data + InvitationResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Invitation' + required: + - data + InvitationUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + id: + type: string + format: uuid + attributes: + type: object + properties: + email: + type: string + format: email + maxLength: 254 + expires_at: + type: string + format: date-time + state: + enum: + - pending + - accepted + - expired + - revoked + type: string + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + x-spec-enum-id: 92a1c1fd12e13e25 + readOnly: true + token: + type: string + readOnly: true + relationships: + type: object + properties: + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + InvitationUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/InvitationUpdate' + required: + - data + LighthouseConfig: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-configurations + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + description: Name of the configuration + maxLength: 100 + minLength: 3 + api_key: + type: string + model: + enum: + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o + - gpt-4o-mini-2024-07-18 + - gpt-4o-mini + - gpt-5-2025-08-07 + - gpt-5 + - gpt-5-mini-2025-08-07 + - gpt-5-mini + type: string + x-spec-enum-id: bd2108eb25b2d472 + description: |- + Must be one of the supported model names + + * `gpt-4o-2024-11-20` - GPT-4o v2024-11-20 + * `gpt-4o-2024-08-06` - GPT-4o v2024-08-06 + * `gpt-4o-2024-05-13` - GPT-4o v2024-05-13 + * `gpt-4o` - GPT-4o Default + * `gpt-4o-mini-2024-07-18` - GPT-4o Mini v2024-07-18 + * `gpt-4o-mini` - GPT-4o Mini Default + * `gpt-5-2025-08-07` - GPT-5 v2025-08-07 + * `gpt-5` - GPT-5 Default + * `gpt-5-mini-2025-08-07` - GPT-5 Mini v2025-08-07 + * `gpt-5-mini` - GPT-5 Mini Default + temperature: + type: number + format: double + description: Must be between 0 and 1 + max_tokens: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: Must be between 500 and 5000 + business_context: + type: string + description: Additional business context for this AI model configuration + is_active: + type: boolean + readOnly: true + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + LighthouseConfigCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-configurations + attributes: + type: object + properties: + name: + type: string + description: Name of the configuration + maxLength: 100 + minLength: 3 + api_key: + type: string + writeOnly: true + model: + enum: + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o + - gpt-4o-mini-2024-07-18 + - gpt-4o-mini + - gpt-5-2025-08-07 + - gpt-5 + - gpt-5-mini-2025-08-07 + - gpt-5-mini + type: string + x-spec-enum-id: bd2108eb25b2d472 + description: |- + Must be one of the supported model names + + * `gpt-4o-2024-11-20` - GPT-4o v2024-11-20 + * `gpt-4o-2024-08-06` - GPT-4o v2024-08-06 + * `gpt-4o-2024-05-13` - GPT-4o v2024-05-13 + * `gpt-4o` - GPT-4o Default + * `gpt-4o-mini-2024-07-18` - GPT-4o Mini v2024-07-18 + * `gpt-4o-mini` - GPT-4o Mini Default + * `gpt-5-2025-08-07` - GPT-5 v2025-08-07 + * `gpt-5` - GPT-5 Default + * `gpt-5-mini-2025-08-07` - GPT-5 Mini v2025-08-07 + * `gpt-5-mini` - GPT-5 Mini Default + temperature: + type: number + format: double + description: Must be between 0 and 1 + max_tokens: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: Must be between 500 and 5000 + business_context: + type: string + description: Additional business context for this AI model configuration + is_active: + type: boolean + readOnly: true + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + - api_key + LighthouseConfigCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-configurations + attributes: + type: object + properties: + name: + type: string + minLength: 3 + description: Name of the configuration + maxLength: 100 + api_key: + type: string + writeOnly: true + minLength: 1 + model: + enum: + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o + - gpt-4o-mini-2024-07-18 + - gpt-4o-mini + - gpt-5-2025-08-07 + - gpt-5 + - gpt-5-mini-2025-08-07 + - gpt-5-mini + type: string + x-spec-enum-id: bd2108eb25b2d472 + description: |- + Must be one of the supported model names + + * `gpt-4o-2024-11-20` - GPT-4o v2024-11-20 + * `gpt-4o-2024-08-06` - GPT-4o v2024-08-06 + * `gpt-4o-2024-05-13` - GPT-4o v2024-05-13 + * `gpt-4o` - GPT-4o Default + * `gpt-4o-mini-2024-07-18` - GPT-4o Mini v2024-07-18 + * `gpt-4o-mini` - GPT-4o Mini Default + * `gpt-5-2025-08-07` - GPT-5 v2025-08-07 + * `gpt-5` - GPT-5 Default + * `gpt-5-mini-2025-08-07` - GPT-5 Mini v2025-08-07 + * `gpt-5-mini` - GPT-5 Mini Default + temperature: + type: number + format: double + description: Must be between 0 and 1 + max_tokens: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: Must be between 500 and 5000 + business_context: + type: string + description: Additional business context for this AI model configuration + is_active: + type: boolean + readOnly: true + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + - api_key + required: + - data + LighthouseConfigCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseConfigCreate' + required: + - data + LighthouseConfigUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-configurations + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + description: Name of the configuration + maxLength: 100 + minLength: 3 + api_key: + type: string + writeOnly: true + model: + enum: + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o + - gpt-4o-mini-2024-07-18 + - gpt-4o-mini + - gpt-5-2025-08-07 + - gpt-5 + - gpt-5-mini-2025-08-07 + - gpt-5-mini + type: string + x-spec-enum-id: bd2108eb25b2d472 + description: |- + Must be one of the supported model names + + * `gpt-4o-2024-11-20` - GPT-4o v2024-11-20 + * `gpt-4o-2024-08-06` - GPT-4o v2024-08-06 + * `gpt-4o-2024-05-13` - GPT-4o v2024-05-13 + * `gpt-4o` - GPT-4o Default + * `gpt-4o-mini-2024-07-18` - GPT-4o Mini v2024-07-18 + * `gpt-4o-mini` - GPT-4o Mini Default + * `gpt-5-2025-08-07` - GPT-5 v2025-08-07 + * `gpt-5` - GPT-5 Default + * `gpt-5-mini-2025-08-07` - GPT-5 Mini v2025-08-07 + * `gpt-5-mini` - GPT-5 Mini Default + temperature: + type: number + format: double + description: Must be between 0 and 1 + max_tokens: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: Must be between 500 and 5000 + business_context: + type: string + description: Additional business context for this AI model configuration + is_active: + type: boolean + readOnly: true + LighthouseConfigUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseConfigUpdate' + required: + - data + LighthouseProviderConfig: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-providers + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + provider_type: + enum: + - openai + type: string + x-spec-enum-id: 80350f3ab09becd9 + description: |- + LLM provider name + + * `openai` - OpenAI + base_url: + type: string + format: uri + nullable: true + maxLength: 200 + is_active: + type: boolean + readOnly: true + credentials: + readOnly: true + required: + - provider_type + LighthouseProviderConfigCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-providers + attributes: + type: object + properties: + provider_type: + enum: + - openai + type: string + x-spec-enum-id: 80350f3ab09becd9 + description: |- + LLM provider name + + * `openai` - OpenAI + base_url: + type: string + format: uri + nullable: true + maxLength: 200 + credentials: + writeOnly: true + is_active: + type: boolean + required: + - provider_type + - credentials + LighthouseProviderConfigCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-providers + attributes: + type: object + properties: + provider_type: + enum: + - openai + type: string + x-spec-enum-id: 80350f3ab09becd9 + description: |- + LLM provider name + + * `openai` - OpenAI + base_url: + type: string + format: uri + nullable: true + maxLength: 200 + credentials: + writeOnly: true + is_active: + type: boolean + required: + - provider_type + - credentials + required: + - data + LighthouseProviderConfigCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseProviderConfigCreate' + required: + - data + LighthouseProviderConfigResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseProviderConfig' + required: + - data + LighthouseProviderConfigUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-providers + id: + type: string + format: uuid + attributes: + type: object + properties: + provider_type: + enum: + - openai + type: string + x-spec-enum-id: 80350f3ab09becd9 + readOnly: true + description: |- + LLM provider name + + * `openai` - OpenAI + base_url: + type: string + format: uri + nullable: true + maxLength: 200 + credentials: + writeOnly: true + is_active: + type: boolean + LighthouseProviderConfigUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseProviderConfigUpdate' + required: + - data + LighthouseProviderModels: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - LighthouseProviderModels + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + model_id: + type: string + maxLength: 100 + model_name: + type: string + maxLength: 100 + default_parameters: {} + required: + - model_id + - model_name + relationships: + type: object + properties: + provider_configuration: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - lighthouse-providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + LighthouseProviderModelsResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseProviderModels' + required: + - data + LighthouseTenantConfig: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-config + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + business_context: + type: string + default_provider: + type: string + maxLength: 50 + default_models: {} + url: + type: string + readOnly: true + LighthouseTenantConfigUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-config + id: + type: string + format: uuid + attributes: + type: object + properties: + business_context: + type: string + default_provider: + type: string + maxLength: 50 + default_models: {} + LighthouseTenantConfigUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/LighthouseTenantConfigUpdate' + required: + - data + Membership: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - memberships + attributes: + type: object + properties: + role: + enum: + - owner + - member + type: string + description: |- + * `owner` - Owner + * `member` - Member + x-spec-enum-id: 12c359ee5dc51001 + date_joined: + type: string + format: date-time + readOnly: true + required: + - role + relationships: + type: object + properties: + user: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uri + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + tenant: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uri + type: + type: string + enum: + - tenants + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + MembershipResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Membership' + required: + - data + OpenApiResponseResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TenantApiKey' + required: + - data + OverviewFinding: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - findings-overview + id: {} + attributes: + type: object + properties: + id: + type: string + default: n/a + new: + type: integer + changed: + type: integer + unchanged: + type: integer + fail_new: + type: integer + fail_changed: + type: integer + pass_new: + type: integer + pass_changed: + type: integer + muted_new: + type: integer + muted_changed: + type: integer + total: + type: integer + fail: + type: integer + muted: + type: integer + pass: + type: integer + required: + - new + - changed + - unchanged + - fail_new + - fail_changed + - pass_new + - pass_changed + - muted_new + - muted_changed + - total + - fail + - muted + - pass + OverviewFindingResponse: + type: object + properties: + data: + $ref: '#/components/schemas/OverviewFinding' + required: + - data + OverviewProvider: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers-overview + id: {} + attributes: + type: object + properties: + id: + type: string + findings: + type: object + properties: + pass: + type: integer + fail: + type: integer + muted: + type: integer + total: + type: integer + readOnly: true + resources: + type: object + properties: + total: + type: integer + readOnly: true + required: + - id + OverviewProviderCount: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers-count-overview + id: {} + attributes: + type: object + properties: + id: + type: string + count: + type: integer + required: + - id + - count + OverviewProviderCountResponse: + type: object + properties: + data: + $ref: '#/components/schemas/OverviewProviderCount' + required: + - data + OverviewProviderResponse: + type: object + properties: + data: + $ref: '#/components/schemas/OverviewProvider' + required: + - data + OverviewService: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - services-overview + id: {} + attributes: + type: object + properties: + id: + type: string + total: + type: integer + fail: + type: integer + muted: + type: integer + pass: + type: integer + required: + - id + - total + - fail + - muted + - pass + OverviewServiceResponse: + type: object + properties: + data: + $ref: '#/components/schemas/OverviewService' + required: + - data + OverviewSeverity: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - findings-severity-overview + id: {} + attributes: + type: object + properties: + id: + type: string + default: n/a + critical: + type: integer + high: + type: integer + medium: + type: integer + low: + type: integer + informational: + type: integer + required: + - critical + - high + - medium + - low + - informational + OverviewSeverityResponse: + type: object + properties: + data: + $ref: '#/components/schemas/OverviewSeverity' + required: + - data + PaginatedComplianceOverviewAttributesList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ComplianceOverviewAttributes' + required: + - data + PaginatedComplianceOverviewDetailList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ComplianceOverviewDetail' + required: + - data + PaginatedComplianceOverviewList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ComplianceOverview' + required: + - data + PaginatedFindingList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Finding' + required: + - data + PaginatedIntegrationList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Integration' + required: + - data + PaginatedInvitationList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Invitation' + required: + - data + PaginatedLighthouseConfigList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LighthouseConfig' + required: + - data + PaginatedLighthouseProviderConfigList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LighthouseProviderConfig' + required: + - data + PaginatedLighthouseProviderModelsList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LighthouseProviderModels' + required: + - data + PaginatedLighthouseTenantConfigList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LighthouseTenantConfig' + required: + - data + PaginatedMembershipList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Membership' + required: + - data + PaginatedProcessorList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Processor' + required: + - data + PaginatedProviderGroupList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProviderGroup' + required: + - data + PaginatedProviderList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Provider' + required: + - data + PaginatedProviderSecretList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProviderSecret' + required: + - data + PaginatedResourceList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Resource' + required: + - data + PaginatedRoleList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Role' + required: + - data + PaginatedSAMLConfigurationList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/SAMLConfiguration' + required: + - data + PaginatedScanList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Scan' + required: + - data + PaginatedTaskList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Task' + required: + - data + PaginatedTenantApiKeyList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/TenantApiKey' + required: + - data + PaginatedTenantList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Tenant' + required: + - data + PaginatedUserList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/User' + required: + - data + PatchedIntegrationUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - integrations + id: {} + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + enabled: + type: boolean + connected: + type: boolean + readOnly: true + nullable: true + connection_last_checked_at: + type: string + format: date-time + readOnly: true + nullable: true + integration_type: + enum: + - amazon_s3 + - aws_security_hub + - jira + - slack + type: string + description: |- + * `amazon_s3` - Amazon S3 + * `aws_security_hub` - AWS Security Hub + * `jira` - JIRA + * `slack` - Slack + x-spec-enum-id: 6cfd0ff9cf4d6dcc + readOnly: true + configuration: + oneOf: + - type: object + title: Amazon S3 + properties: + bucket_name: + type: string + description: The name of the S3 bucket where files will be + stored. + output_directory: + type: string + description: 'The directory path within the bucket where files + will be saved. Optional - defaults to "output" if not provided. + Path will be normalized to remove excessive slashes and + invalid characters are not allowed (< > : " | ? *). Maximum + length is 900 characters.' + maxLength: 900 + pattern: ^[^<>:"|?*]+$ + default: output + required: + - bucket_name + - type: object + title: AWS Security Hub + properties: + send_only_fails: + type: boolean + default: false + description: If true, only findings with status 'FAIL' will + be sent to Security Hub. + archive_previous_findings: + type: boolean + default: false + description: If true, archives findings that are not present + in the current execution. + - type: object + title: JIRA + description: JIRA integration does not accept any configuration + in the payload. Leave it as an empty JSON object (`{}`). + properties: {} + additionalProperties: false + credentials: + oneOf: + - type: object + title: AWS Credentials + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to + assume. Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, + if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + - type: object + title: JIRA Credentials + properties: + user_mail: + type: string + format: email + description: The email address of the JIRA user account. + api_token: + type: string + description: The API token for authentication with JIRA. This + can be generated from your Atlassian account settings. + domain: + type: string + description: The JIRA domain/instance URL (e.g., 'your-domain.atlassian.net'). + required: + - user_mail + - api_token + - domain + writeOnly: true + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + required: + - data + PatchedInvitationUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - invitations + id: + type: string + format: uuid + attributes: + type: object + properties: + email: + type: string + format: email + minLength: 1 + maxLength: 254 + expires_at: + type: string + format: date-time + state: + enum: + - pending + - accepted + - expired + - revoked + type: string + description: |- + * `pending` - Invitation is pending + * `accepted` - Invitation was accepted by a user + * `expired` - Invitation expired after the configured time + * `revoked` - Invitation was revoked by a user + x-spec-enum-id: 92a1c1fd12e13e25 + readOnly: true + token: + type: string + readOnly: true + minLength: 1 + relationships: + type: object + properties: + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + required: + - data + PatchedLighthouseConfigUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-configurations + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 3 + description: Name of the configuration + maxLength: 100 + api_key: + type: string + writeOnly: true + minLength: 1 + model: + enum: + - gpt-4o-2024-11-20 + - gpt-4o-2024-08-06 + - gpt-4o-2024-05-13 + - gpt-4o + - gpt-4o-mini-2024-07-18 + - gpt-4o-mini + - gpt-5-2025-08-07 + - gpt-5 + - gpt-5-mini-2025-08-07 + - gpt-5-mini + type: string + x-spec-enum-id: bd2108eb25b2d472 + description: |- + Must be one of the supported model names + + * `gpt-4o-2024-11-20` - GPT-4o v2024-11-20 + * `gpt-4o-2024-08-06` - GPT-4o v2024-08-06 + * `gpt-4o-2024-05-13` - GPT-4o v2024-05-13 + * `gpt-4o` - GPT-4o Default + * `gpt-4o-mini-2024-07-18` - GPT-4o Mini v2024-07-18 + * `gpt-4o-mini` - GPT-4o Mini Default + * `gpt-5-2025-08-07` - GPT-5 v2025-08-07 + * `gpt-5` - GPT-5 Default + * `gpt-5-mini-2025-08-07` - GPT-5 Mini v2025-08-07 + * `gpt-5-mini` - GPT-5 Mini Default + temperature: + type: number + format: double + description: Must be between 0 and 1 + max_tokens: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: Must be between 500 and 5000 + business_context: + type: string + description: Additional business context for this AI model configuration + is_active: + type: boolean + readOnly: true + required: + - data + PatchedLighthouseProviderConfigUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-providers + id: + type: string + format: uuid + attributes: + type: object + properties: + provider_type: + enum: + - openai + type: string + x-spec-enum-id: 80350f3ab09becd9 + readOnly: true + description: |- + LLM provider name + + * `openai` - OpenAI + base_url: + type: string + format: uri + nullable: true + maxLength: 200 + credentials: + writeOnly: true + is_active: + type: boolean + required: + - data + PatchedLighthouseTenantConfigUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - lighthouse-config + id: + type: string + format: uuid + attributes: + type: object + properties: + business_context: + type: string + default_provider: + type: string + maxLength: 50 + default_models: {} + required: + - data + PatchedProcessorUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - processors + id: {} + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + configuration: + oneOf: + - type: object + title: Mutelist + properties: + Mutelist: + type: object + properties: + Accounts: + type: object + patternProperties: + .*: + type: object + properties: + Checks: + type: object + patternProperties: + .*: + type: object + properties: + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + Exceptions: + type: object + properties: + Accounts: + type: array + items: + type: string + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + additionalProperties: false + Description: + type: string + required: + - Regions + - Resources + additionalProperties: false + additionalProperties: false + required: + - Checks + additionalProperties: false + additionalProperties: false + required: + - Accounts + additionalProperties: false + additionalProperties: false + required: + - configuration + required: + - data + PatchedProviderGroupMembershipRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider_groups-provider + id: + type: string + format: uuid + attributes: + type: object + properties: + providers: + type: array + items: + $ref: '#/components/schemas/ProviderResourceIdentifierRequest' + description: List of resource identifier objects representing providers. + required: + - providers + required: + - data + PatchedProviderGroupUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-groups + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + required: + - data + PatchedProviderSecretUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-secrets + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + secret_type: + enum: + - static + - role + - service_account + type: string + description: |- + * `static` - Key-value pairs + * `role` - Role assumption + * `service_account` - GCP Service Account Key + x-spec-enum-id: 20c74ebcd6671497 + secret: + oneOf: + - type: object + title: AWS Static Credentials + properties: + aws_access_key_id: + type: string + description: The AWS access key ID. Required for environments + where no IAM role is being assumed and direct AWS access + is needed. + aws_secret_access_key: + type: string + description: The AWS secret access key. Must accompany 'aws_access_key_id' + to authorize access to AWS resources. + aws_session_token: + type: string + description: The session token associated with temporary credentials. + Only needed for session-based or temporary AWS access. + required: + - aws_access_key_id + - aws_secret_access_key + - type: object + title: AWS Assume Role + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to + assume. Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, + if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + required: + - role_arn + - external_id + - type: object + title: Azure Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + required: + - client_id + - client_secret + - tenant_id + - type: object + title: M365 Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + user: + type: email + description: User microsoft email address. + deprecated: true + password: + type: string + description: User password. + deprecated: true + required: + - client_id + - client_secret + - tenant_id + - user + - password + - type: object + title: M365 Certificate Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + certificate_content: + type: string + description: The certificate content in base64 format for + certificate-based authentication. + required: + - client_id + - tenant_id + - certificate_content + - type: object + title: GCP Static Credentials + properties: + client_id: + type: string + description: The client ID from Google Cloud, used to identify + the application for GCP access. + client_secret: + type: string + description: The client secret associated with the GCP client + ID, required for secure access. + refresh_token: + type: string + description: A refresh token that allows the application to + obtain new access tokens for extended use. + required: + - client_id + - client_secret + - refresh_token + - type: object + title: GCP Service Account Key + properties: + service_account_key: + type: object + description: The service account key for GCP. + required: + - service_account_key + - type: object + title: Kubernetes Static Credentials + properties: + kubeconfig_content: + type: string + description: The content of the Kubernetes kubeconfig file, + encoded as a string. + required: + - kubeconfig_content + - type: object + title: GitHub Personal Access Token + properties: + personal_access_token: + type: string + description: GitHub personal access token for authentication. + required: + - personal_access_token + - type: object + title: GitHub OAuth App Token + properties: + oauth_app_token: + type: string + description: GitHub OAuth App token for authentication. + required: + - oauth_app_token + - type: object + title: GitHub App Credentials + properties: + github_app_id: + type: integer + description: GitHub App ID for authentication. + github_app_key: + type: string + description: Path to the GitHub App private key file. + required: + - github_app_id + - github_app_key + - type: object + title: Oracle Cloud Infrastructure (OCI) API Key Credentials + properties: + user: + type: string + description: The OCID of the user to authenticate with. + fingerprint: + type: string + description: The fingerprint of the API signing key. + key_file: + type: string + description: The path to the private key file for API signing. + Either key_file or key_content must be provided. + key_content: + type: string + description: The content of the private key for API signing + (base64 encoded). Either key_file or key_content must be + provided. + tenancy: + type: string + description: The OCID of the tenancy. + region: + type: string + description: The OCI region identifier (e.g., us-ashburn-1, + us-phoenix-1). + pass_phrase: + type: string + description: The passphrase for the private key, if encrypted. + required: + - user + - fingerprint + - tenancy + - region + writeOnly: true + required: + - secret + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + required: + - data + PatchedProviderUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers + id: {} + attributes: + type: object + properties: + alias: + type: string + nullable: true + description: Human readable name to identify the provider, e.g. + 'Production AWS Account', 'Dev Environment' + maxLength: 100 + minLength: 3 + required: + - data + PatchedRoleProviderGroupRelationshipRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - role-provider_groups + id: + type: string + format: uuid + attributes: + type: object + properties: + provider_groups: + type: array + items: + $ref: '#/components/schemas/ProviderGroupResourceIdentifierRequest' + description: List of resource identifier objects representing provider + groups. + required: + - provider_groups + required: + - data + PatchedRoleUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - roles + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + manage_users: + type: boolean + manage_account: + type: boolean + manage_integrations: + type: boolean + manage_providers: + type: boolean + manage_scans: + type: boolean + permission_state: + type: string + readOnly: true + unlimited_visibility: + type: boolean + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + provider_groups: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - provider-groups + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type provider-groups + title: provider-groups + users: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type users + title: users + invitations: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - invitations + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type invitations + title: invitations + readOnly: true + required: + - data + PatchedSAMLConfigurationRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - saml-configurations + id: + type: string + format: uuid + attributes: + type: object + properties: + email_domain: + type: string + minLength: 1 + description: Email domain used to identify the tenant, e.g. prowlerdemo.com + maxLength: 254 + metadata_xml: + type: string + minLength: 1 + description: Raw IdP metadata XML to configure SingleSignOnService, + certificates, etc. + created_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - email_domain + - metadata_xml + required: + - data + PatchedScanUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - scans + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + required: + - data + PatchedTenantApiKeyUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - api-keys + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 3 + maxLength: 100 + prefix: + type: string + readOnly: true + minLength: 1 + description: Unique prefix to identify the API key + expires_at: + type: string + format: date-time + readOnly: true + inserted_at: + type: string + format: date-time + readOnly: true + last_used_at: + type: string + format: date-time + readOnly: true + nullable: true + description: Last time this API key was used for authentication + required: + - name + relationships: + type: object + properties: + entity: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + required: + - data + PatchedTenantRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tenants + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + required: + - name + relationships: + type: object + properties: + memberships: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - memberships + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type memberships + title: memberships + readOnly: true + required: + - data + PatchedUserRoleRelationshipRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - user-roles + id: + type: string + format: uuid + attributes: + type: object + properties: + roles: + type: array + items: + $ref: '#/components/schemas/RoleResourceIdentifierRequest' + description: List of resource identifier objects representing roles. + required: + - roles + required: + - data + PatchedUserUpdateRequest: + type: object + properties: + data: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - users + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + minLength: 3 + maxLength: 150 + password: + type: string + writeOnly: true + minLength: 1 + email: + type: string + format: email + minLength: 1 + description: Case insensitive + maxLength: 254 + company_name: + type: string + maxLength: 150 + required: + - name + - email + required: + - data + Processor: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - processors + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + processor_type: + enum: + - mutelist + type: string + description: '* `mutelist` - Mutelist' + x-spec-enum-id: 53cda4a99fe3d655 + configuration: + oneOf: + - type: object + title: Mutelist + properties: + Mutelist: + type: object + properties: + Accounts: + type: object + patternProperties: + .*: + type: object + properties: + Checks: + type: object + patternProperties: + .*: + type: object + properties: + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + Exceptions: + type: object + properties: + Accounts: + type: array + items: + type: string + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + additionalProperties: false + Description: + type: string + required: + - Regions + - Resources + additionalProperties: false + additionalProperties: false + required: + - Checks + additionalProperties: false + additionalProperties: false + required: + - Accounts + additionalProperties: false + additionalProperties: false + required: + - processor_type + - configuration + ProcessorCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - processors + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + processor_type: + enum: + - mutelist + type: string + description: '* `mutelist` - Mutelist' + x-spec-enum-id: 53cda4a99fe3d655 + configuration: + oneOf: + - type: object + title: Mutelist + properties: + Mutelist: + type: object + properties: + Accounts: + type: object + patternProperties: + .*: + type: object + properties: + Checks: + type: object + patternProperties: + .*: + type: object + properties: + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + Exceptions: + type: object + properties: + Accounts: + type: array + items: + type: string + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + additionalProperties: false + Description: + type: string + required: + - Regions + - Resources + additionalProperties: false + additionalProperties: false + required: + - Checks + additionalProperties: false + additionalProperties: false + required: + - Accounts + additionalProperties: false + additionalProperties: false + required: + - processor_type + - configuration + ProcessorCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - processors + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + processor_type: + enum: + - mutelist + type: string + description: '* `mutelist` - Mutelist' + x-spec-enum-id: 53cda4a99fe3d655 + configuration: + oneOf: + - type: object + title: Mutelist + properties: + Mutelist: + type: object + properties: + Accounts: + type: object + patternProperties: + .*: + type: object + properties: + Checks: + type: object + patternProperties: + .*: + type: object + properties: + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + Exceptions: + type: object + properties: + Accounts: + type: array + items: + type: string + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + additionalProperties: false + Description: + type: string + required: + - Regions + - Resources + additionalProperties: false + additionalProperties: false + required: + - Checks + additionalProperties: false + additionalProperties: false + required: + - Accounts + additionalProperties: false + additionalProperties: false + required: + - processor_type + - configuration + required: + - data + ProcessorCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProcessorCreate' + required: + - data + ProcessorResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Processor' + required: + - data + ProcessorUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - processors + id: {} + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + configuration: + oneOf: + - type: object + title: Mutelist + properties: + Mutelist: + type: object + properties: + Accounts: + type: object + patternProperties: + .*: + type: object + properties: + Checks: + type: object + patternProperties: + .*: + type: object + properties: + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + Exceptions: + type: object + properties: + Accounts: + type: array + items: + type: string + Regions: + type: array + items: + type: string + Resources: + type: array + items: + type: string + Tags: + type: array + items: + type: string + additionalProperties: false + Description: + type: string + required: + - Regions + - Resources + additionalProperties: false + additionalProperties: false + required: + - Checks + additionalProperties: false + additionalProperties: false + required: + - Accounts + additionalProperties: false + additionalProperties: false + required: + - configuration + ProcessorUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProcessorUpdate' + required: + - data + Provider: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + provider: + enum: + - aws + - azure + - gcp + - kubernetes + - m365 + - github + - oci + type: string + description: |- + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + x-spec-enum-id: 6f034074d7104650 + uid: + type: string + title: Unique identifier for the provider, set by the provider + maxLength: 250 + minLength: 3 + alias: + type: string + nullable: true + maxLength: 100 + minLength: 3 + connection: + type: object + properties: + connected: + type: boolean + last_checked_at: + type: string + format: date-time + readOnly: true + required: + - provider + - uid + relationships: + type: object + properties: + secret: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - provider-secrets + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + provider_groups: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - provider-groups + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type provider-groups + title: provider-groups + readOnly: true + required: + - secret + ProviderCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers + attributes: + type: object + properties: + alias: + type: string + nullable: true + description: Human readable name to identify the provider, e.g. 'Production + AWS Account', 'Dev Environment' + maxLength: 100 + minLength: 3 + provider: + enum: + - aws + - azure + - gcp + - kubernetes + - m365 + - github + - oci + type: string + x-spec-enum-id: 6f034074d7104650 + description: |- + Type of provider to create. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + uid: + type: string + title: Unique identifier for the provider, set by the provider + description: Unique identifier for the provider, set by the provider, + e.g. AWS account ID, Azure subscription ID, GCP project ID, etc. + maxLength: 250 + minLength: 3 + required: + - uid + ProviderCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - providers + attributes: + type: object + properties: + alias: + type: string + nullable: true + description: Human readable name to identify the provider, e.g. + 'Production AWS Account', 'Dev Environment' + maxLength: 100 + minLength: 3 + provider: + enum: + - aws + - azure + - gcp + - kubernetes + - m365 + - github + - oci + type: string + x-spec-enum-id: 6f034074d7104650 + description: |- + Type of provider to create. + + * `aws` - AWS + * `azure` - Azure + * `gcp` - GCP + * `kubernetes` - Kubernetes + * `m365` - M365 + * `github` - GitHub + * `oci` - Oracle Cloud Infrastructure + uid: + type: string + minLength: 3 + title: Unique identifier for the provider, set by the provider + description: Unique identifier for the provider, set by the provider, + e.g. AWS account ID, Azure subscription ID, GCP project ID, etc. + maxLength: 250 + required: + - uid + required: + - data + ProviderCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderCreate' + required: + - data + ProviderGroup: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-groups + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 255 + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + ProviderGroupCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-groups + attributes: + type: object + properties: + name: + type: string + maxLength: 255 + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + ProviderGroupCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-groups + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + providers: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type providers + title: providers + roles: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type roles + title: roles + required: + - data + ProviderGroupCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderGroupCreate' + required: + - data + ProviderGroupMembershipRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider_groups-provider + attributes: + type: object + properties: + providers: + type: array + items: + $ref: '#/components/schemas/ProviderResourceIdentifierRequest' + description: List of resource identifier objects representing providers. + required: + - providers + required: + - data + ProviderGroupResourceIdentifierRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-group-identifier + attributes: + type: object + properties: + resource_type: + type: string + minLength: 1 + id: + type: string + format: uuid + required: + - resource_type + - id + required: + - data + ProviderGroupResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderGroup' + required: + - data + ProviderResourceIdentifierRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-identifier + attributes: + type: object + properties: + resource_type: + type: string + minLength: 1 + id: + type: string + format: uuid + required: + - resource_type + - id + required: + - data + ProviderResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Provider' + required: + - data + ProviderSecret: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-secrets + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + secret_type: + enum: + - static + - role + - service_account + type: string + description: |- + * `static` - Key-value pairs + * `role` - Role assumption + * `service_account` - GCP Service Account Key + x-spec-enum-id: 20c74ebcd6671497 + required: + - secret_type + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + required: + - provider + ProviderSecretCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-secrets + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + secret_type: + enum: + - static + - role + - service_account + type: string + description: |- + * `static` - Key-value pairs + * `role` - Role assumption + * `service_account` - GCP Service Account Key + x-spec-enum-id: 20c74ebcd6671497 + secret: + oneOf: + - type: object + title: AWS Static Credentials + properties: + aws_access_key_id: + type: string + description: The AWS access key ID. Required for environments + where no IAM role is being assumed and direct AWS access is + needed. + aws_secret_access_key: + type: string + description: The AWS secret access key. Must accompany 'aws_access_key_id' + to authorize access to AWS resources. + aws_session_token: + type: string + description: The session token associated with temporary credentials. + Only needed for session-based or temporary AWS access. + required: + - aws_access_key_id + - aws_secret_access_key + - type: object + title: AWS Assume Role + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to assume. + Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + required: + - role_arn + - external_id + - type: object + title: Azure Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + required: + - client_id + - client_secret + - tenant_id + - type: object + title: M365 Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + user: + type: email + description: User microsoft email address. + deprecated: true + password: + type: string + description: User password. + deprecated: true + required: + - client_id + - client_secret + - tenant_id + - user + - password + - type: object + title: M365 Certificate Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + certificate_content: + type: string + description: The certificate content in base64 format for certificate-based + authentication. + required: + - client_id + - tenant_id + - certificate_content + - type: object + title: GCP Static Credentials + properties: + client_id: + type: string + description: The client ID from Google Cloud, used to identify + the application for GCP access. + client_secret: + type: string + description: The client secret associated with the GCP client + ID, required for secure access. + refresh_token: + type: string + description: A refresh token that allows the application to obtain + new access tokens for extended use. + required: + - client_id + - client_secret + - refresh_token + - type: object + title: GCP Service Account Key + properties: + service_account_key: + type: object + description: The service account key for GCP. + required: + - service_account_key + - type: object + title: Kubernetes Static Credentials + properties: + kubeconfig_content: + type: string + description: The content of the Kubernetes kubeconfig file, encoded + as a string. + required: + - kubeconfig_content + - type: object + title: GitHub Personal Access Token + properties: + personal_access_token: + type: string + description: GitHub personal access token for authentication. + required: + - personal_access_token + - type: object + title: GitHub OAuth App Token + properties: + oauth_app_token: + type: string + description: GitHub OAuth App token for authentication. + required: + - oauth_app_token + - type: object + title: GitHub App Credentials + properties: + github_app_id: + type: integer + description: GitHub App ID for authentication. + github_app_key: + type: string + description: Path to the GitHub App private key file. + required: + - github_app_id + - github_app_key + - type: object + title: Oracle Cloud Infrastructure (OCI) API Key Credentials + properties: + user: + type: string + description: The OCID of the user to authenticate with. + fingerprint: + type: string + description: The fingerprint of the API signing key. + key_file: + type: string + description: The path to the private key file for API signing. + Either key_file or key_content must be provided. + key_content: + type: string + description: The content of the private key for API signing (base64 + encoded). Either key_file or key_content must be provided. + tenancy: + type: string + description: The OCID of the tenancy. + region: + type: string + description: The OCI region identifier (e.g., us-ashburn-1, us-phoenix-1). + pass_phrase: + type: string + description: The passphrase for the private key, if encrypted. + required: + - user + - fingerprint + - tenancy + - region + writeOnly: true + required: + - secret_type + - secret + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + required: + - provider + ProviderSecretCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-secrets + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + secret_type: + enum: + - static + - role + - service_account + type: string + description: |- + * `static` - Key-value pairs + * `role` - Role assumption + * `service_account` - GCP Service Account Key + x-spec-enum-id: 20c74ebcd6671497 + secret: + oneOf: + - type: object + title: AWS Static Credentials + properties: + aws_access_key_id: + type: string + description: The AWS access key ID. Required for environments + where no IAM role is being assumed and direct AWS access + is needed. + aws_secret_access_key: + type: string + description: The AWS secret access key. Must accompany 'aws_access_key_id' + to authorize access to AWS resources. + aws_session_token: + type: string + description: The session token associated with temporary credentials. + Only needed for session-based or temporary AWS access. + required: + - aws_access_key_id + - aws_secret_access_key + - type: object + title: AWS Assume Role + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to + assume. Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, + if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + required: + - role_arn + - external_id + - type: object + title: Azure Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + required: + - client_id + - client_secret + - tenant_id + - type: object + title: M365 Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + user: + type: email + description: User microsoft email address. + deprecated: true + password: + type: string + description: User password. + deprecated: true + required: + - client_id + - client_secret + - tenant_id + - user + - password + - type: object + title: M365 Certificate Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory + where the application is registered. + certificate_content: + type: string + description: The certificate content in base64 format for + certificate-based authentication. + required: + - client_id + - tenant_id + - certificate_content + - type: object + title: GCP Static Credentials + properties: + client_id: + type: string + description: The client ID from Google Cloud, used to identify + the application for GCP access. + client_secret: + type: string + description: The client secret associated with the GCP client + ID, required for secure access. + refresh_token: + type: string + description: A refresh token that allows the application to + obtain new access tokens for extended use. + required: + - client_id + - client_secret + - refresh_token + - type: object + title: GCP Service Account Key + properties: + service_account_key: + type: object + description: The service account key for GCP. + required: + - service_account_key + - type: object + title: Kubernetes Static Credentials + properties: + kubeconfig_content: + type: string + description: The content of the Kubernetes kubeconfig file, + encoded as a string. + required: + - kubeconfig_content + - type: object + title: GitHub Personal Access Token + properties: + personal_access_token: + type: string + description: GitHub personal access token for authentication. + required: + - personal_access_token + - type: object + title: GitHub OAuth App Token + properties: + oauth_app_token: + type: string + description: GitHub OAuth App token for authentication. + required: + - oauth_app_token + - type: object + title: GitHub App Credentials + properties: + github_app_id: + type: integer + description: GitHub App ID for authentication. + github_app_key: + type: string + description: Path to the GitHub App private key file. + required: + - github_app_id + - github_app_key + - type: object + title: Oracle Cloud Infrastructure (OCI) API Key Credentials + properties: + user: + type: string + description: The OCID of the user to authenticate with. + fingerprint: + type: string + description: The fingerprint of the API signing key. + key_file: + type: string + description: The path to the private key file for API signing. + Either key_file or key_content must be provided. + key_content: + type: string + description: The content of the private key for API signing + (base64 encoded). Either key_file or key_content must be + provided. + tenancy: + type: string + description: The OCID of the tenancy. + region: + type: string + description: The OCI region identifier (e.g., us-ashburn-1, + us-phoenix-1). + pass_phrase: + type: string + description: The passphrase for the private key, if encrypted. + required: + - user + - fingerprint + - tenancy + - region + writeOnly: true + required: + - secret_type + - secret + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + required: + - provider + required: + - data + ProviderSecretCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderSecretCreate' + required: + - data + ProviderSecretResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderSecret' + required: + - data + ProviderSecretUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - provider-secrets + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + secret_type: + enum: + - static + - role + - service_account + type: string + description: |- + * `static` - Key-value pairs + * `role` - Role assumption + * `service_account` - GCP Service Account Key + x-spec-enum-id: 20c74ebcd6671497 + secret: + oneOf: + - type: object + title: AWS Static Credentials + properties: + aws_access_key_id: + type: string + description: The AWS access key ID. Required for environments + where no IAM role is being assumed and direct AWS access is + needed. + aws_secret_access_key: + type: string + description: The AWS secret access key. Must accompany 'aws_access_key_id' + to authorize access to AWS resources. + aws_session_token: + type: string + description: The session token associated with temporary credentials. + Only needed for session-based or temporary AWS access. + required: + - aws_access_key_id + - aws_secret_access_key + - type: object + title: AWS Assume Role + properties: + role_arn: + type: string + description: The Amazon Resource Name (ARN) of the role to assume. + Required for AWS role assumption. + external_id: + type: string + description: An identifier to enhance security for role assumption. + aws_access_key_id: + type: string + description: The AWS access key ID. Only required if the environment + lacks pre-configured AWS credentials. + aws_secret_access_key: + type: string + description: The AWS secret access key. Required if 'aws_access_key_id' + is provided or if no AWS credentials are pre-configured. + aws_session_token: + type: string + description: The session token for temporary credentials, if applicable. + session_duration: + type: integer + minimum: 900 + maximum: 43200 + default: 3600 + description: The duration (in seconds) for the role session. + role_session_name: + type: string + description: |- + An identifier for the role session, useful for tracking sessions in AWS logs. The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric characters with no spaces. You can also include underscores or any of the following characters: =,.@- + + Examples: + - MySession123 + - User_Session-1 + - Test.Session@2 + pattern: ^[a-zA-Z0-9=,.@_-]+$ + required: + - role_arn + - external_id + - type: object + title: Azure Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + required: + - client_id + - client_secret + - tenant_id + - type: object + title: M365 Static Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + client_secret: + type: string + description: The client secret associated with the application + (client) ID, providing secure access. + user: + type: email + description: User microsoft email address. + deprecated: true + password: + type: string + description: User password. + deprecated: true + required: + - client_id + - client_secret + - tenant_id + - user + - password + - type: object + title: M365 Certificate Credentials + properties: + client_id: + type: string + description: The Azure application (client) ID for authentication + in Azure AD. + tenant_id: + type: string + description: The Azure tenant ID, representing the directory where + the application is registered. + certificate_content: + type: string + description: The certificate content in base64 format for certificate-based + authentication. + required: + - client_id + - tenant_id + - certificate_content + - type: object + title: GCP Static Credentials + properties: + client_id: + type: string + description: The client ID from Google Cloud, used to identify + the application for GCP access. + client_secret: + type: string + description: The client secret associated with the GCP client + ID, required for secure access. + refresh_token: + type: string + description: A refresh token that allows the application to obtain + new access tokens for extended use. + required: + - client_id + - client_secret + - refresh_token + - type: object + title: GCP Service Account Key + properties: + service_account_key: + type: object + description: The service account key for GCP. + required: + - service_account_key + - type: object + title: Kubernetes Static Credentials + properties: + kubeconfig_content: + type: string + description: The content of the Kubernetes kubeconfig file, encoded + as a string. + required: + - kubeconfig_content + - type: object + title: GitHub Personal Access Token + properties: + personal_access_token: + type: string + description: GitHub personal access token for authentication. + required: + - personal_access_token + - type: object + title: GitHub OAuth App Token + properties: + oauth_app_token: + type: string + description: GitHub OAuth App token for authentication. + required: + - oauth_app_token + - type: object + title: GitHub App Credentials + properties: + github_app_id: + type: integer + description: GitHub App ID for authentication. + github_app_key: + type: string + description: Path to the GitHub App private key file. + required: + - github_app_id + - github_app_key + - type: object + title: Oracle Cloud Infrastructure (OCI) API Key Credentials + properties: + user: + type: string + description: The OCID of the user to authenticate with. + fingerprint: + type: string + description: The fingerprint of the API signing key. + key_file: + type: string + description: The path to the private key file for API signing. + Either key_file or key_content must be provided. + key_content: + type: string + description: The content of the private key for API signing (base64 + encoded). Either key_file or key_content must be provided. + tenancy: + type: string + description: The OCID of the tenancy. + region: + type: string + description: The OCI region identifier (e.g., us-ashburn-1, us-phoenix-1). + pass_phrase: + type: string + description: The passphrase for the private key, if encrypted. + required: + - user + - fingerprint + - tenancy + - region + writeOnly: true + required: + - secret + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + ProviderSecretUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderSecretUpdate' + required: + - data + Resource: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - resources + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + uid: + type: string + title: Unique identifier for the resource, set by the provider + name: + type: string + title: Name of the resource, as set in the provider + region: + type: string + title: Location of the resource, as set by the provider + service: + type: string + title: Service of the resource, as set by the provider + tags: + type: object + description: Tags associated with the resource + example: + env: prod + owner: johndoe + readOnly: true + failed_findings_count: + type: integer + readOnly: true + type: + type: string + readOnly: true + required: + - uid + - name + - region + - service + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + findings: + type: object + properties: + data: + type: object + properties: + id: + type: string + type: + type: string + enum: + - findings + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + required: + - provider + ResourceMetadata: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - resources-metadata + id: {} + attributes: + type: object + properties: + services: + type: array + items: + type: string + regions: + type: array + items: + type: string + types: + type: array + items: + type: string + required: + - services + - regions + - types + ResourceMetadataResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ResourceMetadata' + required: + - data + ResourceResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Resource' + required: + - data + Role: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - roles + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 255 + manage_users: + type: boolean + manage_account: + type: boolean + manage_integrations: + type: boolean + manage_providers: + type: boolean + manage_scans: + type: boolean + permission_state: + type: string + readOnly: true + unlimited_visibility: + type: boolean + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + provider_groups: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - provider-groups + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type provider-groups + title: provider-groups + users: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type users + title: users + invitations: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - invitations + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type invitations + title: invitations + readOnly: true + RoleCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - roles + attributes: + type: object + properties: + name: + type: string + maxLength: 255 + manage_users: + type: boolean + manage_account: + type: boolean + manage_integrations: + type: boolean + manage_providers: + type: boolean + manage_scans: + type: boolean + permission_state: + type: string + readOnly: true + unlimited_visibility: + type: boolean + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + provider_groups: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - provider-groups + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type provider-groups + title: provider-groups + users: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type users + title: users + invitations: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - invitations + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type invitations + title: invitations + readOnly: true + RoleCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - roles + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 255 + manage_users: + type: boolean + manage_account: + type: boolean + manage_integrations: + type: boolean + manage_providers: + type: boolean + manage_scans: + type: boolean + permission_state: + type: string + readOnly: true + unlimited_visibility: + type: boolean + inserted_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - name + relationships: + type: object + properties: + provider_groups: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - provider-groups + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type provider-groups + title: provider-groups + users: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type users + title: users + invitations: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - invitations + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type invitations + title: invitations + readOnly: true + required: + - data + RoleCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/RoleCreate' + required: + - data + RoleProviderGroupRelationshipRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - role-provider_groups + attributes: + type: object + properties: + provider_groups: + type: array + items: + $ref: '#/components/schemas/ProviderGroupResourceIdentifierRequest' + description: List of resource identifier objects representing provider + groups. + required: + - provider_groups + required: + - data + RoleResourceIdentifierRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - role-identifier + attributes: + type: object + properties: + resource_type: + type: string + minLength: 1 + id: + type: string + format: uuid + required: + - resource_type + - id + required: + - data + RoleResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Role' + required: + - data + SAMLConfiguration: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - saml-configurations + id: + type: string + format: uuid + attributes: + type: object + properties: + email_domain: + type: string + description: Email domain used to identify the tenant, e.g. prowlerdemo.com + maxLength: 254 + metadata_xml: + type: string + description: Raw IdP metadata XML to configure SingleSignOnService, + certificates, etc. + created_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - email_domain + - metadata_xml + SAMLConfigurationRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - saml-configurations + attributes: + type: object + properties: + email_domain: + type: string + minLength: 1 + description: Email domain used to identify the tenant, e.g. prowlerdemo.com + maxLength: 254 + metadata_xml: + type: string + minLength: 1 + description: Raw IdP metadata XML to configure SingleSignOnService, + certificates, etc. + created_at: + type: string + format: date-time + readOnly: true + updated_at: + type: string + format: date-time + readOnly: true + required: + - email_domain + - metadata_xml + required: + - data + SAMLConfigurationResponse: + type: object + properties: + data: + $ref: '#/components/schemas/SAMLConfiguration' + required: + - data + Scan: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - scans + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + trigger: + enum: + - scheduled + - manual + type: string + description: |- + * `scheduled` - Scheduled + * `manual` - Manual + x-spec-enum-id: 2e52c981d1c89bdf + readOnly: true + state: + enum: + - available + - scheduled + - executing + - completed + - failed + - cancelled + type: string + description: |- + * `available` - Available + * `scheduled` - Scheduled + * `executing` - Executing + * `completed` - Completed + * `failed` - Failed + * `cancelled` - Cancelled + x-spec-enum-id: d38ba07264e1ed34 + readOnly: true + unique_resource_count: + type: integer + maximum: 2147483647 + minimum: -2147483648 + progress: + type: integer + maximum: 2147483647 + minimum: -2147483648 + duration: + type: integer + maximum: 2147483647 + minimum: -2147483648 + nullable: true + inserted_at: + type: string + format: date-time + readOnly: true + started_at: + type: string + format: date-time + nullable: true + completed_at: + type: string + format: date-time + nullable: true + scheduled_at: + type: string + format: date-time + nullable: true + next_scan_at: + type: string + format: date-time + nullable: true + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + task: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - tasks + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + nullable: true + processor: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - processors + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + nullable: true + required: + - provider + ScanCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - scans + attributes: + type: object + properties: + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + relationships: + type: object + properties: + provider: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - providers + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + required: + - provider + required: + - data + ScanResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Scan' + required: + - data + ScanUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - scans + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + nullable: true + maxLength: 100 + minLength: 3 + ScanUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ScanUpdate' + required: + - data + ScheduleDailyCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - daily-schedules + attributes: + type: object + properties: + provider_id: + type: string + format: uuid + required: + - provider_id + required: + - data + SerializerMetaclassResponse: + type: object + properties: + data: + $ref: '#/components/schemas/ProviderGroup' + required: + - data + Task: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tasks + id: + type: string + format: uuid + attributes: + type: object + properties: + inserted_at: + type: string + format: date-time + readOnly: true + completed_at: + type: string + format: date-time + readOnly: true + name: + type: string + readOnly: true + state: + type: string + enum: + - available + - scheduled + - executing + - completed + - failed + - cancelled + readOnly: true + result: + readOnly: true + task_args: + readOnly: true + metadata: + readOnly: true + TaskResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Task' + required: + - data + Tenant: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tenants + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 100 + required: + - name + relationships: + type: object + properties: + memberships: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - memberships + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type memberships + title: memberships + readOnly: true + TenantApiKey: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - api-keys + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 100 + minLength: 3 + prefix: + type: string + readOnly: true + description: Unique prefix to identify the API key + expires_at: + type: string + format: date-time + readOnly: true + revoked: + type: boolean + description: If the API key is revoked, entities cannot use it anymore. + (This cannot be undone.) + inserted_at: + type: string + format: date-time + readOnly: true + last_used_at: + type: string + format: date-time + nullable: true + description: Last time this API key was used for authentication + required: + - name + relationships: + type: object + properties: + entity: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + nullable: true + TenantApiKeyCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - api-keys + attributes: + type: object + properties: + name: + type: string + maxLength: 100 + minLength: 3 + prefix: + type: string + readOnly: true + description: Unique prefix to identify the API key + expires_at: + type: string + format: date-time + revoked: + type: boolean + readOnly: true + description: If the API key is revoked, entities cannot use it anymore. + (This cannot be undone.) + inserted_at: + type: string + format: date-time + readOnly: true + last_used_at: + type: string + format: date-time + readOnly: true + nullable: true + description: Last time this API key was used for authentication + api_key: + type: string + readOnly: true + required: + - name + relationships: + type: object + properties: + entity: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + TenantApiKeyCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - api-keys + attributes: + type: object + properties: + name: + type: string + minLength: 3 + maxLength: 100 + prefix: + type: string + readOnly: true + minLength: 1 + description: Unique prefix to identify the API key + expires_at: + type: string + format: date-time + revoked: + type: boolean + readOnly: true + description: If the API key is revoked, entities cannot use it anymore. + (This cannot be undone.) + inserted_at: + type: string + format: date-time + readOnly: true + last_used_at: + type: string + format: date-time + readOnly: true + nullable: true + description: Last time this API key was used for authentication + api_key: + type: string + readOnly: true + required: + - name + relationships: + type: object + properties: + entity: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + required: + - data + TenantApiKeyCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TenantApiKeyCreate' + required: + - data + TenantApiKeyResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TenantApiKey' + required: + - data + TenantApiKeyUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - api-keys + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 100 + minLength: 3 + prefix: + type: string + readOnly: true + description: Unique prefix to identify the API key + expires_at: + type: string + format: date-time + readOnly: true + inserted_at: + type: string + format: date-time + readOnly: true + last_used_at: + type: string + format: date-time + readOnly: true + nullable: true + description: Last time this API key was used for authentication + required: + - name + relationships: + type: object + properties: + entity: + type: object + properties: + data: + type: object + properties: + id: + type: string + format: uuid + type: + type: string + enum: + - users + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + nullable: true + TenantApiKeyUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TenantApiKeyUpdate' + required: + - data + TenantRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tenants + attributes: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + required: + - name + relationships: + type: object + properties: + memberships: + type: object + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + format: uuid + title: Resource Identifier + description: The identifier of the related object. + type: + type: string + enum: + - memberships + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share + common attributes and relationships. + required: + - id + - type + required: + - data + description: A related resource object from type memberships + title: memberships + readOnly: true + required: + - data + TenantResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Tenant' + required: + - data + Token: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens + attributes: + type: object + properties: + email: + type: string + writeOnly: true + password: + type: string + writeOnly: true + tenant_id: + type: string + format: uuid + writeOnly: true + description: If not provided, the tenant ID of the first membership + that was added to the user will be used. + refresh: + type: string + readOnly: true + access: + type: string + readOnly: true + required: + - email + - password + TokenRefresh: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens-refresh + attributes: + type: object + properties: + refresh: + type: string + access: + type: string + readOnly: true + required: + - refresh + TokenRefreshRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens-refresh + attributes: + type: object + properties: + refresh: + type: string + minLength: 1 + access: + type: string + readOnly: true + minLength: 1 + required: + - refresh + required: + - data + TokenRefreshResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TokenRefresh' + required: + - data + TokenRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens + attributes: + type: object + properties: + email: + type: string + writeOnly: true + minLength: 1 + password: + type: string + writeOnly: true + minLength: 1 + tenant_id: + type: string + format: uuid + writeOnly: true + description: If not provided, the tenant ID of the first membership + that was added to the user will be used. + refresh: + type: string + readOnly: true + minLength: 1 + access: + type: string + readOnly: true + minLength: 1 + required: + - email + - password + required: + - data + TokenResponse: + type: object + properties: + data: + $ref: '#/components/schemas/Token' + required: + - data + TokenSwitchTenant: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens-switch-tenant + attributes: + type: object + properties: + tenant_id: + type: string + format: uuid + writeOnly: true + description: The tenant ID for which to request a new token. + access: + type: string + readOnly: true + refresh: + type: string + readOnly: true + required: + - tenant_id + TokenSwitchTenantRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - tokens-switch-tenant + attributes: + type: object + properties: + tenant_id: + type: string + format: uuid + writeOnly: true + description: The tenant ID for which to request a new token. + access: + type: string + readOnly: true + minLength: 1 + refresh: + type: string + readOnly: true + minLength: 1 + required: + - tenant_id + required: + - data + TokenSwitchTenantResponse: + type: object + properties: + data: + $ref: '#/components/schemas/TokenSwitchTenant' + required: + - data + User: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - users + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 150 + minLength: 3 + email: + type: string + format: email + description: Case insensitive + maxLength: 254 + company_name: + type: string + maxLength: 150 + date_joined: + type: string + format: date-time + readOnly: true + required: + - name + - email + relationships: + type: object + properties: + memberships: + type: object + properties: + data: + type: object + properties: + id: + type: string + type: + type: string + enum: + - memberships + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + roles: + type: object + properties: + data: + type: object + properties: + id: + type: string + type: + type: string + enum: + - roles + title: Resource Type Name + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common + attributes and relationships. + required: + - id + - type + required: + - data + description: The identifier of the related object. + title: Resource Identifier + readOnly: true + UserCreate: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - users + attributes: + type: object + properties: + name: + type: string + maxLength: 150 + minLength: 3 + password: + type: string + writeOnly: true + email: + type: string + format: email + description: Case insensitive + maxLength: 254 + company_name: + type: string + required: + - name + - password + - email + UserCreateRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - users + attributes: + type: object + properties: + name: + type: string + minLength: 3 + maxLength: 150 + password: + type: string + writeOnly: true + minLength: 1 + email: + type: string + format: email + minLength: 1 + description: Case insensitive + maxLength: 254 + company_name: + type: string + minLength: 1 + required: + - name + - password + - email + required: + - data + UserCreateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/UserCreate' + required: + - data + UserResponse: + type: object + properties: + data: + $ref: '#/components/schemas/User' + required: + - data + UserRoleRelationshipRequest: + type: object + properties: + data: + type: object + required: + - type + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - user-roles + attributes: + type: object + properties: + roles: + type: array + items: + $ref: '#/components/schemas/RoleResourceIdentifierRequest' + description: List of resource identifier objects representing roles. + required: + - roles + required: + - data + UserUpdate: + type: object + required: + - type + - id + additionalProperties: false + properties: + type: + type: string + description: The [type](https://jsonapi.org/format/#document-resource-object-identification) + member is used to describe resource objects that share common attributes + and relationships. + enum: + - users + id: + type: string + format: uuid + attributes: + type: object + properties: + name: + type: string + maxLength: 150 + minLength: 3 + password: + type: string + writeOnly: true + email: + type: string + format: email + description: Case insensitive + maxLength: 254 + company_name: + type: string + maxLength: 150 + required: + - name + - email + UserUpdateResponse: + type: object + properties: + data: + $ref: '#/components/schemas/UserUpdate' + required: + - data + securitySchemes: + JWT or API Key: + type: http + scheme: bearer + bearerFormat: JWT + description: Supports both JWT Bearer tokens and API Key authentication. Use + `Bearer ` for JWT or `Api-Key ` for API keys. +tags: +- name: User + description: Endpoints for managing user accounts. +- name: Token + description: Endpoints for token management, including obtaining a new token and + refreshing an existing token for authentication purposes. +- name: Tenant + description: Endpoints for managing tenants, along with their memberships. +- name: Invitation + description: Endpoints for tenant invitations management, allowing retrieval and + filtering of invitations, creating new invitations, accepting and revoking them. +- name: Role + description: Endpoints for managing RBAC roles within tenants, allowing creation, + retrieval, updating, and deletion of role configurations and permissions. +- name: Provider + description: Endpoints for managing providers (AWS, GCP, Azure, etc...). +- name: Provider Group + description: Endpoints for managing provider groups. +- name: Task + description: Endpoints for task management, allowing retrieval of task status and + revoking tasks that have not started. +- name: Scan + description: Endpoints for triggering manual scans and viewing scan results. +- name: Schedule + description: Endpoints for managing scan schedules, allowing configuration of automated + scans with different scheduling options. +- name: Resource + description: Endpoints for managing resources discovered by scans, allowing retrieval + and filtering of resource information. +- name: Finding + description: Endpoints for managing findings, allowing retrieval and filtering of + findings that result from scans. +- name: Processor + description: Endpoints for managing post-processors used to process Prowler findings, + including registration, configuration, and deletion of post-processing actions. +- name: Compliance Overview + description: Endpoints for checking the compliance overview, allowing filtering + by scan, provider or compliance framework ID. +- name: Overview + description: Endpoints for retrieving aggregated summaries of resources from the + system. +- name: Integration + description: Endpoints for managing third-party integrations, including registration, + configuration, retrieval, and deletion of integrations such as S3, JIRA, or other + services. +- name: Lighthouse AI + description: Endpoints for managing Lighthouse AI configurations, including creation, + retrieval, updating, and deletion of configurations such as OpenAI keys, models, + and business context. +- name: SAML + description: Endpoints for Single Sign-On authentication management via SAML for + seamless user authentication. +- name: API Keys + description: Endpoints for API keys management. These can be used as an alternative + to JWT authorization. diff --git a/docs/api-reference/overviews/findings-severity.mdx b/docs/api-reference/overviews/findings-severity.mdx new file mode 100644 index 0000000000..1af5981ad0 --- /dev/null +++ b/docs/api-reference/overviews/findings-severity.mdx @@ -0,0 +1,7 @@ +--- +title: "Findings Severity Overview" +api: "GET /api/v1/overviews/findings-severity" +description: "Get overview statistics for findings-severity." +--- + +Retrieve aggregated statistics and metrics. diff --git a/docs/api-reference/overviews/findings.mdx b/docs/api-reference/overviews/findings.mdx new file mode 100644 index 0000000000..26831a9860 --- /dev/null +++ b/docs/api-reference/overviews/findings.mdx @@ -0,0 +1,7 @@ +--- +title: "Findings Overview" +api: "GET /api/v1/overviews/findings" +description: "Get overview statistics for findings." +--- + +Retrieve aggregated statistics and metrics. diff --git a/docs/api-reference/overviews/providers-count.mdx b/docs/api-reference/overviews/providers-count.mdx new file mode 100644 index 0000000000..e95b0b4d67 --- /dev/null +++ b/docs/api-reference/overviews/providers-count.mdx @@ -0,0 +1,7 @@ +--- +title: "Providers Count Overview" +api: "GET /api/v1/overviews/providers-count" +description: "Get overview statistics for providers-count." +--- + +Retrieve aggregated statistics and metrics. diff --git a/docs/api-reference/overviews/providers.mdx b/docs/api-reference/overviews/providers.mdx new file mode 100644 index 0000000000..be65a783db --- /dev/null +++ b/docs/api-reference/overviews/providers.mdx @@ -0,0 +1,7 @@ +--- +title: "Providers Overview" +api: "GET /api/v1/overviews/providers" +description: "Get overview statistics for providers." +--- + +Retrieve aggregated statistics and metrics. diff --git a/docs/api-reference/overviews/services.mdx b/docs/api-reference/overviews/services.mdx new file mode 100644 index 0000000000..d376098b01 --- /dev/null +++ b/docs/api-reference/overviews/services.mdx @@ -0,0 +1,7 @@ +--- +title: "Services Overview" +api: "GET /api/v1/overviews/services" +description: "Get overview statistics for services." +--- + +Retrieve aggregated statistics and metrics. diff --git a/docs/api-reference/processors/create.mdx b/docs/api-reference/processors/create.mdx new file mode 100644 index 0000000000..0d070c21b3 --- /dev/null +++ b/docs/api-reference/processors/create.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Processor" +api: "POST /api/v1/processors" +description: "create processor configuration." +--- + +Processor operations for result processing. diff --git a/docs/api-reference/processors/delete.mdx b/docs/api-reference/processors/delete.mdx new file mode 100644 index 0000000000..18f5f456b3 --- /dev/null +++ b/docs/api-reference/processors/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Processor" +api: "DELETE /api/v1/processors/{id}" +description: "delete processor configuration." +--- + +Processor operations for result processing. diff --git a/docs/api-reference/processors/list.mdx b/docs/api-reference/processors/list.mdx new file mode 100644 index 0000000000..f660849077 --- /dev/null +++ b/docs/api-reference/processors/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Processor" +api: "GET /api/v1/processors" +description: "list processor configuration." +--- + +Processor operations for result processing. diff --git a/docs/api-reference/processors/retrieve.mdx b/docs/api-reference/processors/retrieve.mdx new file mode 100644 index 0000000000..7f725be2a0 --- /dev/null +++ b/docs/api-reference/processors/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Processor" +api: "PATCH /api/v1/processors/{id}" +description: "retrieve processor configuration." +--- + +Processor operations for result processing. diff --git a/docs/api-reference/processors/update.mdx b/docs/api-reference/processors/update.mdx new file mode 100644 index 0000000000..ffe7088a71 --- /dev/null +++ b/docs/api-reference/processors/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Processor" +api: "PATCH /api/v1/processors/{id}" +description: "update processor configuration." +--- + +Processor operations for result processing. diff --git a/docs/api-reference/provider-groups/add-providers.mdx b/docs/api-reference/provider-groups/add-providers.mdx new file mode 100644 index 0000000000..c94a20503e --- /dev/null +++ b/docs/api-reference/provider-groups/add-providers.mdx @@ -0,0 +1,7 @@ +--- +title: "Add Providers to Group" +api: "POST /api/v1/provider-groups/{id}/relationships/providers" +description: "Add providers to a group." +--- + +Associate providers with a provider group. diff --git a/docs/api-reference/provider-groups/create.mdx b/docs/api-reference/provider-groups/create.mdx new file mode 100644 index 0000000000..a21805ffa9 --- /dev/null +++ b/docs/api-reference/provider-groups/create.mdx @@ -0,0 +1,20 @@ +--- +title: "Create Provider Group" +api: "POST /api/v1/provider-groups" +description: "Create a new provider group." +--- + +Create a group to organize multiple providers together. + +## Request Body +\`\`\`json +{ + "data": { + "type": "provider-groups", + "attributes": { + "name": "Production Providers", + "description": "All production cloud accounts" + } + } +} +\`\`\` diff --git a/docs/api-reference/provider-groups/delete.mdx b/docs/api-reference/provider-groups/delete.mdx new file mode 100644 index 0000000000..ced5ac1ac9 --- /dev/null +++ b/docs/api-reference/provider-groups/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Provider Group" +api: "DELETE /api/v1/provider-groups/{id}" +description: "Remove a provider group." +--- + +Delete a provider group. Providers in the group are not deleted. diff --git a/docs/api-reference/provider-groups/list.mdx b/docs/api-reference/provider-groups/list.mdx new file mode 100644 index 0000000000..14ae1895a0 --- /dev/null +++ b/docs/api-reference/provider-groups/list.mdx @@ -0,0 +1,17 @@ +--- +title: "List Provider Groups" +api: "GET /api/v1/provider-groups" +description: "Retrieve provider groups for organizing providers." +--- + +Get all provider groups used to organize and manage multiple providers. + +## Query Parameters +- `filter[name]` - Filter by group name +- `page[number]`, `page[size]` - Pagination + +## Example +\`\`\`bash +curl "https://api.prowler.com/api/v1/provider-groups" \\ + -H "Authorization: Bearer YOUR_API_KEY" +\`\`\` diff --git a/docs/api-reference/provider-groups/remove-providers.mdx b/docs/api-reference/provider-groups/remove-providers.mdx new file mode 100644 index 0000000000..87bf604bf0 --- /dev/null +++ b/docs/api-reference/provider-groups/remove-providers.mdx @@ -0,0 +1,7 @@ +--- +title: "Remove Providers from Group" +api: "DELETE /api/v1/provider-groups/{id}/relationships/providers" +description: "Remove providers from group." +--- + +Disassociate providers from a provider group. diff --git a/docs/api-reference/provider-groups/retrieve.mdx b/docs/api-reference/provider-groups/retrieve.mdx new file mode 100644 index 0000000000..3b2bf56a4d --- /dev/null +++ b/docs/api-reference/provider-groups/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Provider Group" +api: "GET /api/v1/provider-groups/{id}" +description: "Get provider group details." +--- + +Fetch information about a specific provider group. diff --git a/docs/api-reference/provider-groups/update-providers.mdx b/docs/api-reference/provider-groups/update-providers.mdx new file mode 100644 index 0000000000..376eaf2946 --- /dev/null +++ b/docs/api-reference/provider-groups/update-providers.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Group Providers" +api: "PATCH /api/v1/provider-groups/{id}/relationships/providers" +description: "Update providers in group." +--- + +Modify the list of providers in a group. diff --git a/docs/api-reference/provider-groups/update.mdx b/docs/api-reference/provider-groups/update.mdx new file mode 100644 index 0000000000..841bbe836e --- /dev/null +++ b/docs/api-reference/provider-groups/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Provider Group" +api: "PATCH /api/v1/provider-groups/{id}" +description: "Update provider group." +--- + +Modify provider group name or description. diff --git a/docs/api-reference/providers/check-connection.mdx b/docs/api-reference/providers/check-connection.mdx new file mode 100644 index 0000000000..551a03510d --- /dev/null +++ b/docs/api-reference/providers/check-connection.mdx @@ -0,0 +1,27 @@ +--- +title: "Check Provider Connection" +api: "POST /api/v1/providers/{id}/connection" +description: "Test the connection to a cloud provider." +--- + +Verify that Prowler can successfully connect to the cloud provider using the configured credentials. + +## Path Parameters + +- `id` (required) - UUID of the provider to test + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/providers/{id}/connection" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns a task object. The connection test is performed asynchronously. + + +Use this endpoint after creating or updating a provider to verify the credentials are correct. + diff --git a/docs/api-reference/providers/create.mdx b/docs/api-reference/providers/create.mdx new file mode 100644 index 0000000000..9bc4986cf6 --- /dev/null +++ b/docs/api-reference/providers/create.mdx @@ -0,0 +1,293 @@ +--- +title: "Create Provider" +api: "POST /api/v1/providers" +description: "Register a new cloud provider with Prowler." +--- + +Add a new cloud provider (AWS, Azure, GCP, etc.) to your Prowler tenant. This allows Prowler to scan the provider for security findings and compliance violations. + +## Use Cases + +- **Multi-Cloud Management**: Add multiple cloud accounts to centralize security monitoring +- **Account Onboarding**: Quickly onboard new cloud accounts for security scanning +- **Organization-Wide Coverage**: Add all accounts from AWS Organizations, Azure subscriptions, or GCP projects +- **DevOps Integration**: Automatically register new cloud accounts via CI/CD pipelines + +## Request Body + +The request follows the JSON:API specification: + +```json +{ + "data": { + "type": "providers", + "attributes": { + "provider": "aws", + "alias": "Production AWS Account", + "uid": "123456789012" + } + } +} +``` + +### Attributes + +- `provider` (required, string) - Type of cloud provider: + - `aws` - Amazon Web Services + - `azure` - Microsoft Azure + - `gcp` - Google Cloud Platform + - `kubernetes` - Kubernetes clusters + - `m365` - Microsoft 365 + - `github` - GitHub organizations + - `oci` - Oracle Cloud Infrastructure + +- `alias` (optional, string) - Human-readable name to identify the provider (3-100 characters) + - Examples: "Production AWS Account", "Dev Environment", "Azure Subscription - US" + +- `uid` (required, string) - Unique identifier for the provider (3-250 characters): + - AWS: Account ID (12 digits, e.g., "123456789012") + - Azure: Subscription ID (UUID format) + - GCP: Project ID (string) + - Kubernetes: Cluster name + - M365: Tenant ID + - GitHub: Organization name + - OCI: Tenancy OCID + + +**Important:** Provider-specific configuration (credentials, connection details) is managed separately after provider creation. The initial provider creation only requires the `provider`, `alias`, and `uid` fields. Use the provider update endpoint or UI to configure authentication credentials. + + +## Example Requests + +### AWS Provider +```bash +curl -X POST "https://api.prowler.com/api/v1/providers" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "providers", + "attributes": { + "provider": "aws", + "alias": "Production AWS - US", + "uid": "123456789012" + } + } + }' +``` + +### Azure Provider +```bash +curl -X POST "https://api.prowler.com/api/v1/providers" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "providers", + "attributes": { + "provider": "azure", + "alias": "Production Azure Subscription", + "uid": "aaaabbbb-cccc-dddd-eeee-ffff00001111" + } + } + }' +``` + +### GCP Provider +```bash +curl -X POST "https://api.prowler.com/api/v1/providers" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "providers", + "attributes": { + "provider": "gcp", + "alias": "Production GCP Project", + "uid": "my-gcp-project-id" + } + } + }' +``` + +## Response + +### Success Response (201 Created) + +Returns the created provider with full configuration: + +```json +{ + "data": { + "type": "providers", + "id": "provider-uuid-here", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - US", + "connection": { + "connected": false, + "last_checked_at": null + }, + "inserted_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-15T10:30:00Z" + }, + "relationships": { + "secret": { + "data": { + "type": "provider-secrets", + "id": "secret-uuid" + } + }, + "provider_groups": { + "data": [] + }, + "scans": { + "data": [] + } + } + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the provider +- `provider` (enum) - Type of cloud provider: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci` +- `uid` (string) - Cloud provider account/subscription ID (3-250 characters) +- `alias` (string, nullable) - Human-readable name (3-100 characters) +- `connection` (object, read-only) - Connection status information: + - `connected` (boolean) - Whether provider is connected (initially `false`) + - `last_checked_at` (datetime, nullable) - Last connection verification time +- `inserted_at` (datetime, read-only) - When provider was created +- `updated_at` (datetime, read-only) - Last modification time + +### Error Responses + +**400 Bad Request** - Invalid configuration +```json +{ + "errors": [ + { + "status": "400", + "title": "Invalid Configuration", + "detail": "IAM role ARN format is invalid", + "source": { + "pointer": "/data/attributes/configuration/role_arn" + } + } + ] +} +``` + +**409 Conflict** - Provider already exists +```json +{ + "errors": [ + { + "status": "409", + "title": "Provider Already Exists", + "detail": "A provider with UID '123456789012' already exists in this tenant" + } + ] +} +``` + +**422 Unprocessable Entity** - Validation error +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "Provider must be one of: aws, azure, gcp, kubernetes, m365, github, oci", + "source": { + "pointer": "/data/attributes/provider" + } + } + ] +} +``` + +**422 Unprocessable Entity** - Invalid UID format +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "UID must be between 3 and 250 characters", + "source": { + "pointer": "/data/attributes/uid" + } + } + ] +} +``` + +## Next Steps + +After creating a provider: + +1. **Verify Connection**: Test the provider connection + ```bash + curl -X POST "https://api.prowler.com/api/v1/providers/{provider_id}/connection" \ + -H "Authorization: Bearer YOUR_API_KEY" + ``` + +2. **Run First Scan**: Initiate a security scan + ```bash + curl -X POST "https://api.prowler.com/api/v1/scans" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{"data": {"type": "scans", "attributes": {"provider_id": "provider-uuid"}}}' + ``` + +3. **View Findings**: Check security findings from the scan + ```bash + curl -X GET "https://api.prowler.com/api/v1/findings/latest?filter[provider]=provider-uuid" \ + -H "Authorization: Bearer YOUR_API_KEY" + ``` + +## Prerequisites by Provider Type + +### AWS +1. Create an IAM role in your AWS account +2. Attach the `SecurityAudit` managed policy (or custom policy) +3. Configure trust relationship to allow Prowler to assume the role +4. Note the Role ARN + +[AWS Setup Guide →](/user-guide/providers/aws/getting-started-aws) + +### Azure +1. Create an App Registration in Azure AD +2. Grant `Reader` and `Security Reader` roles at subscription level +3. Create a client secret +4. Note tenant ID, client ID, and subscription ID + +[Azure Setup Guide →](/user-guide/providers/azure/getting-started-azure) + +### GCP +1. Create a service account in your GCP project +2. Grant necessary IAM roles (Viewer, Security Reviewer) +3. Generate and download a JSON key file +4. Use the key file contents in the configuration + +[GCP Setup Guide →](/user-guide/providers/gcp/getting-started-gcp) + + +**Security Considerations:** +- Use least-privilege IAM policies +- Rotate credentials regularly +- Use external IDs for AWS role assumption +- Store credentials securely (never in code) +- Enable audit logging for all provider access +- Use read-only permissions only + + + +After creating a provider, it will show `connected: false` until you verify the connection using the `/providers/{id}/connection` endpoint. + + + +**Best Practice:** Use descriptive aliases that include the environment and region (e.g., "Production AWS US-East", "Dev Azure West Europe") to easily identify providers in your dashboard. + diff --git a/docs/api-reference/providers/delete.mdx b/docs/api-reference/providers/delete.mdx new file mode 100644 index 0000000000..e95e172aab --- /dev/null +++ b/docs/api-reference/providers/delete.mdx @@ -0,0 +1,27 @@ +--- +title: "Delete Provider" +api: "DELETE /api/v1/providers/{id}" +description: "Remove a provider from the system." +--- + +Delete a cloud provider permanently. This will also delete all associated scans and findings. + +## Path Parameters + +- `id` (required) - UUID of the provider to delete + +## Example Request + +```bash +curl -X DELETE "https://api.prowler.com/api/v1/providers/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns `204 No Content` on successful deletion. + + +Deleting a provider will permanently remove all associated scans, findings, and historical data. This action cannot be undone. + diff --git a/docs/api-reference/providers/list.mdx b/docs/api-reference/providers/list.mdx new file mode 100644 index 0000000000..68eceff5e9 --- /dev/null +++ b/docs/api-reference/providers/list.mdx @@ -0,0 +1,120 @@ +--- +title: "List Providers" +api: "GET /api/v1/providers" +description: "Retrieve a list of all configured cloud providers with options for filtering." +--- + +Retrieve all configured cloud providers in your tenant. Providers represent your cloud accounts (AWS, Azure, GCP, etc.) that Prowler scans for security findings. + +## Query Parameters + +### Filtering Options + +**By Type:** +- `filter[provider]`, `filter[provider__in]` - Filter by provider type: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci` + +**By Status:** +- `filter[connected]` - Filter by connection status (boolean) + +**By Alias:** +- `filter[alias]`, `filter[alias__icontains]` - Filter by provider alias + +**By UID:** +- `filter[uid]`, `filter[uid__icontains]` - Filter by provider UID + +**By Date:** +- `filter[inserted_at]`, `filter[inserted_at__date]` - Filter by creation date +- `filter[inserted_at__gte]`, `filter[inserted_at__lte]` - Filter by date range + +### Pagination + +- `page[number]` - Page number to retrieve +- `page[size]` - Number of results per page + +### Sorting + +- `sort` - Field to sort by: `id`, `-id`, `alias`, `-alias`, `inserted_at`, `-inserted_at`, `updated_at`, `-updated_at` + +### Field Selection + +- `fields[providers]` - Specify which fields to return + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/providers?filter[provider]=aws&filter[connected]=true" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns a paginated list of providers with their configuration and connection status: + +```json +{ + "data": [ + { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - US", + "connection": { + "connected": true, + "last_checked_at": "2024-01-20T10:30:00Z" + }, + "inserted_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-01-20T10:30:00Z" + }, + "relationships": { + "secret": { + "data": { + "type": "provider-secrets", + "id": "secret-uuid" + } + }, + "provider_groups": { + "data": [] + }, + "scans": { + "data": [ + { + "type": "scans", + "id": "scan-uuid" + } + ] + } + } + } + ], + "meta": { + "page": { + "number": 1, + "size": 20, + "total": 1, + "total_pages": 1 + } + }, + "links": { + "self": "https://api.prowler.com/api/v1/providers?page[number]=1", + "first": "https://api.prowler.com/api/v1/providers?page[number]=1", + "last": "https://api.prowler.com/api/v1/providers?page[number]=1" + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the provider +- `provider` (enum) - Type of cloud provider: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci` +- `uid` (string) - Provider's unique identifier (3-250 characters) +- `alias` (string, nullable) - Human-readable name (3-100 characters) +- `connection` (object, read-only) - Connection status information: + - `connected` (boolean) - Whether provider is connected + - `last_checked_at` (datetime) - Last connection verification time +- `inserted_at` (datetime, read-only) - When provider was created +- `updated_at` (datetime, read-only) - Last modification time diff --git a/docs/api-reference/providers/retrieve.mdx b/docs/api-reference/providers/retrieve.mdx new file mode 100644 index 0000000000..012b13f2fe --- /dev/null +++ b/docs/api-reference/providers/retrieve.mdx @@ -0,0 +1,101 @@ +--- +title: "Retrieve Provider" +api: "GET /api/v1/providers/{id}" +description: "Fetch detailed information about a specific provider by its ID." +--- + +Retrieve detailed information about a specific cloud provider. + +## Path Parameters + +- `id` (required) - UUID of the provider to retrieve + +## Query Parameters + +### Field Selection + +- `fields[providers]` - Specify which fields to return + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/providers/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns detailed provider information: + +```json +{ + "data": { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - US", + "connection": { + "connected": true, + "last_checked_at": "2024-01-20T10:30:00Z" + }, + "inserted_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-01-20T10:30:00Z" + }, + "relationships": { + "secret": { + "data": { + "type": "provider-secrets", + "id": "secret-uuid" + } + }, + "provider_groups": { + "data": [] + }, + "scans": { + "data": [ + { + "type": "scans", + "id": "scan-uuid-1" + }, + { + "type": "scans", + "id": "scan-uuid-2" + } + ] + } + } + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the provider +- `provider` (enum) - Type of cloud provider: `aws`, `azure`, `gcp`, `kubernetes`, `m365`, `github`, `oci` +- `uid` (string) - Provider's unique identifier (3-250 characters) +- `alias` (string, nullable) - Human-readable name (3-100 characters) +- `connection` (object, read-only) - Connection status information: + - `connected` (boolean) - Whether provider is connected + - `last_checked_at` (datetime) - Last connection verification time +- `inserted_at` (datetime, read-only) - When provider was created +- `updated_at` (datetime, read-only) - Last modification time + +### Error Responses + +**404 Not Found** - Provider does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "Provider not found" + } + ] +} +``` diff --git a/docs/api-reference/providers/secrets/create.mdx b/docs/api-reference/providers/secrets/create.mdx new file mode 100644 index 0000000000..2dd21670a2 --- /dev/null +++ b/docs/api-reference/providers/secrets/create.mdx @@ -0,0 +1,266 @@ +--- +title: "Create Provider Secret" +api: "POST /api/v1/providers/secrets" +description: "Add credentials/secrets to authenticate with a cloud provider." +--- + +Configure authentication credentials for a cloud provider. This endpoint stores the necessary secrets (API keys, role ARNs, service account keys) to allow Prowler to scan your cloud infrastructure. + +## Use Cases + +- **AWS Role Assumption**: Configure IAM role ARN for cross-account access +- **Azure Service Principal**: Store client ID, client secret, and tenant ID +- **GCP Service Account**: Upload service account JSON key +- **Static Credentials**: Store API keys or access keys (not recommended for production) + +## Request Body + +The request follows the JSON:API specification: + +```json +{ + "data": { + "type": "provider-secrets", + "attributes": { + "name": "Production AWS Credentials", + "secret_type": "role", + "secret": { + "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole", + "external_id": "unique-external-id" + } + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } +} +``` + +### Attributes + +- `name` (optional, string, nullable) - Descriptive name for the secret (3-100 characters) +- `secret_type` (required, enum) - Type of secret: + - `role` - IAM role assumption (AWS) + - `service_account` - Service account key (GCP) + - `static` - Static key-value pairs (API keys, credentials) +- `secret` (required, object) - The actual secret data (varies by secret_type) + +### Secret Types and Formats + +**AWS Role (`role`):** +```json +{ + "secret": { + "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole", + "external_id": "your-external-id" + } +} +``` + +**GCP Service Account (`service_account`):** +```json +{ + "secret": { + "service_account_key": "{\"type\":\"service_account\",\"project_id\":\"my-project\",...}" + } +} +``` + +**Azure Service Principal (`static`):** +```json +{ + "secret": { + "client_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111", + "client_secret": "your-client-secret", + "tenant_id": "tenant-uuid" + } +} +``` + +**Static Credentials (`static`):** +```json +{ + "secret": { + "access_key_id": "AKIAIOSFODNN7EXAMPLE", + "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" + } +} +``` + +## Example Requests + +### AWS Role Assumption +```bash +curl -X POST "https://api.prowler.com/api/v1/providers/secrets" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "provider-secrets", + "attributes": { + "name": "Production AWS Role", + "secret_type": "role", + "secret": { + "role_arn": "arn:aws:iam::123456789012:role/ProwlerRole", + "external_id": "prowler-external-id-12345" + } + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } + }' +``` + +### GCP Service Account +```bash +curl -X POST "https://api.prowler.com/api/v1/providers/secrets" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "provider-secrets", + "attributes": { + "name": "GCP Service Account", + "secret_type": "service_account", + "secret": { + "service_account_key": "{\"type\":\"service_account\",\"project_id\":\"my-project-123\",\"private_key_id\":\"key-id\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"prowler@my-project.iam.gserviceaccount.com\",\"client_id\":\"123456789\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\"}" + } + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } + }' +``` + +## Response + +### Success Response (201 Created) + +Returns the created secret metadata (sensitive data is not returned): + +```json +{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "name": "Production AWS Role", + "secret_type": "role", + "inserted_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-15T10:30:00Z" + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the secret +- `name` (string, nullable) - Descriptive name (3-100 characters) +- `secret_type` (enum) - Type: `role`, `service_account`, or `static` +- `inserted_at` (datetime, read-only) - Creation timestamp +- `updated_at` (datetime, read-only) - Last modification timestamp + +### Error Responses + +**400 Bad Request** - Invalid secret format +```json +{ + "errors": [ + { + "status": "400", + "title": "Invalid Secret Format", + "detail": "Role ARN format is invalid" + } + ] +} +``` + +**404 Not Found** - Provider does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Provider Not Found", + "detail": "Provider with ID 'provider-uuid' not found" + } + ] +} +``` + +**422 Unprocessable Entity** - Validation error +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "secret_type is required", + "source": { + "pointer": "/data/attributes/secret_type" + } + } + ] +} +``` + +## Next Steps + +After creating a secret: + +1. **Test Connection**: Verify the credentials work + ```bash + curl -X POST "https://api.prowler.com/api/v1/providers/{provider_id}/connection" \ + -H "Authorization: Bearer YOUR_API_KEY" + ``` + +2. **Run First Scan**: Execute a security scan + ```bash + curl -X POST "https://api.prowler.com/api/v1/scans" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{"data": {"type": "scans", "attributes": {"provider_id": "provider-uuid"}}}' + ``` + + +**Security Critical:** +- Secrets are encrypted at rest in Prowler's database +- Use role assumption (AWS) or service accounts (GCP) instead of static credentials +- Never log or expose secret values +- Rotate credentials regularly +- Use least-privilege IAM policies +- For AWS, always use an external ID for role assumption + + + +The secret data itself is never returned in API responses after creation. Only metadata about the secret is accessible via the API. + + + +**AWS Best Practice:** Create a dedicated IAM role with the `SecurityAudit` managed policy and a trust relationship allowing Prowler to assume it. Use an external ID for additional security. + diff --git a/docs/api-reference/providers/secrets/delete.mdx b/docs/api-reference/providers/secrets/delete.mdx new file mode 100644 index 0000000000..10721378f6 --- /dev/null +++ b/docs/api-reference/providers/secrets/delete.mdx @@ -0,0 +1,73 @@ +--- +title: "Delete Provider Secret" +api: "DELETE /api/v1/providers/secrets/{id}" +description: "Remove a provider secret permanently." +--- + +Delete a provider secret. This removes the credentials used to authenticate with a cloud provider. + +## Path Parameters + +- `id` (required) - UUID of the secret to delete + +## Example Request + +```bash +curl -X DELETE "https://api.prowler.com/api/v1/providers/secrets/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (204 No Content) + +Returns no content on successful deletion. + +### Error Responses + +**404 Not Found** - Secret does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "Secret not found" + } + ] +} +``` + +**409 Conflict** - Secret is in use +```json +{ + "errors": [ + { + "status": "409", + "title": "Secret In Use", + "detail": "Cannot delete secret that is currently associated with an active provider. Remove the provider first or update it to use different credentials." + } + ] +} +``` + + +**Deleting a secret will:** +- Immediately prevent Prowler from accessing the cloud provider +- Stop all scheduled scans for the associated provider +- Make it impossible to run new scans until new credentials are added + +This action cannot be undone. + + + +Before deleting a secret, ensure: +- The provider is no longer needed, OR +- New credentials have been added and tested, OR +- The provider has been deleted or updated to use different credentials + + + +Instead of deleting a secret when rotating credentials, use the update endpoint to replace the old credentials with new ones. This ensures zero downtime. + diff --git a/docs/api-reference/providers/secrets/list.mdx b/docs/api-reference/providers/secrets/list.mdx new file mode 100644 index 0000000000..6ccd982727 --- /dev/null +++ b/docs/api-reference/providers/secrets/list.mdx @@ -0,0 +1,133 @@ +--- +title: "List Provider Secrets" +api: "GET /api/v1/providers/secrets" +description: "Retrieve a list of all provider secrets with filtering options." +--- + +Retrieve metadata about all provider secrets. Note that the actual secret values are never returned - only metadata such as names, types, and timestamps. + +## Query Parameters + +### Filtering + +- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID(s) +- `filter[secret_type]`, `filter[secret_type__in]` - Filter by type: `static`, `role`, `service_account` +- `filter[name]`, `filter[name__icontains]` - Filter by secret name + +### Pagination + +- `page[number]` - Page number to retrieve (default: 1) +- `page[size]` - Number of results per page (default: 20, max: 100) + +### Sorting + +- `sort` - Field to sort by: + - `inserted_at` - Oldest first + - `-inserted_at` - Newest first (default) + - `name` - Alphabetically + - `-name` - Reverse alphabetically + +### Field Selection + +- `fields[provider-secrets]` - Specify which fields to return: `inserted_at`, `updated_at`, `name`, `secret_type`, `provider` + +### Include Related Resources + +- `include` - Include related resources: `provider` + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/providers/secrets?filter[secret_type]=role&include=provider" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns a paginated list of secret metadata: + +```json +{ + "data": [ + { + "type": "provider-secrets", + "id": "secret-uuid-1", + "attributes": { + "name": "Production AWS Role", + "secret_type": "role", + "inserted_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-15T10:30:00Z" + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + }, + { + "type": "provider-secrets", + "id": "secret-uuid-2", + "attributes": { + "name": "GCP Service Account", + "secret_type": "service_account", + "inserted_at": "2024-01-10T08:15:00Z", + "updated_at": "2024-01-10T08:15:00Z" + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid-2" + } + } + } + } + ], + "meta": { + "page": { + "number": 1, + "size": 20, + "total": 2, + "total_pages": 1 + } + }, + "links": { + "self": "https://api.prowler.com/api/v1/providers/secrets?page[number]=1", + "first": "https://api.prowler.com/api/v1/providers/secrets?page[number]=1", + "last": "https://api.prowler.com/api/v1/providers/secrets?page[number]=1" + }, + "included": [ + { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - US" + } + } + ] +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the secret +- `name` (string, nullable) - Descriptive name (3-100 characters) +- `secret_type` (enum) - Type: `role`, `service_account`, or `static` +- `inserted_at` (datetime, read-only) - When secret was created +- `updated_at` (datetime, read-only) - Last modification time + + +Secret values are never returned via the API. Only metadata about secrets is accessible. + + + +Regularly audit your secrets list to identify and remove unused credentials. + diff --git a/docs/api-reference/providers/secrets/retrieve.mdx b/docs/api-reference/providers/secrets/retrieve.mdx new file mode 100644 index 0000000000..e23d83d7f3 --- /dev/null +++ b/docs/api-reference/providers/secrets/retrieve.mdx @@ -0,0 +1,96 @@ +--- +title: "Retrieve Provider Secret" +api: "GET /api/v1/providers/secrets/{id}" +description: "Fetch metadata about a specific provider secret by its ID." +--- + +Retrieve metadata about a specific provider secret. The actual secret values are never returned - only information about the secret. + +## Path Parameters + +- `id` (required) - The UUID of the secret to retrieve + +## Query Parameters + +### Field Selection + +- `fields[provider-secrets]` - Specify which fields to return: `inserted_at`, `updated_at`, `name`, `secret_type`, `provider` + +### Include Related Resources + +- `include` - Include related resources: `provider` + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/providers/secrets/{id}?include=provider" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns secret metadata: + +```json +{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "name": "Production AWS Role", + "secret_type": "role", + "inserted_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-15T10:30:00Z" + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + }, + "included": [ + { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - US" + } + } + ] +} +``` + +### Response Fields + +- `id` (UUID) - Unique identifier for the secret +- `name` (string, nullable) - Descriptive name (3-100 characters) +- `secret_type` (enum) - Type: `role`, `service_account`, or `static` +- `inserted_at` (datetime, read-only) - When secret was created +- `updated_at` (datetime, read-only) - Last modification time + +### Error Responses + +**404 Not Found** - Secret does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "Secret not found" + } + ] +} +``` + + +Secret values are never returned via the API. If you need to update credentials, use the update endpoint with new secret data. + diff --git a/docs/api-reference/providers/secrets/update.mdx b/docs/api-reference/providers/secrets/update.mdx new file mode 100644 index 0000000000..abad4d06bb --- /dev/null +++ b/docs/api-reference/providers/secrets/update.mdx @@ -0,0 +1,168 @@ +--- +title: "Update Provider Secret" +api: "PATCH /api/v1/providers/secrets/{id}" +description: "Update a provider secret's credentials or metadata." +--- + +Update an existing provider secret. This is typically used to rotate credentials or update the secret name. + +## Path Parameters + +- `id` (required) - UUID of the secret to update + +## Request Body + +```json +{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "name": "Updated Secret Name", + "secret": { + "role_arn": "arn:aws:iam::123456789012:role/NewProwlerRole", + "external_id": "new-external-id" + } + } + } +} +``` + +### Attributes + +- `name` (optional, string, nullable) - Update the secret name (3-100 characters) +- `secret` (optional, object) - Update the secret data (format depends on secret_type) +- `secret_type` (read-only) - Cannot be changed after creation + + +The `secret_type` cannot be changed. If you need a different secret type, create a new secret and delete the old one. + + +## Example Requests + +### Update AWS Role ARN +```bash +curl -X PATCH "https://api.prowler.com/api/v1/providers/secrets/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "name": "Production AWS Role - Rotated", + "secret": { + "role_arn": "arn:aws:iam::123456789012:role/ProwlerRoleV2", + "external_id": "prowler-external-id-67890" + } + } + } + }' +``` + +### Update Azure Credentials +```bash +curl -X PATCH "https://api.prowler.com/api/v1/providers/secrets/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "secret": { + "client_id": "aaaabbbb-cccc-dddd-eeee-ffff00001111", + "client_secret": "new-rotated-client-secret", + "tenant_id": "tenant-uuid" + } + } + } + }' +``` + +## Response + +### Success Response (200 OK) + +Returns the updated secret metadata: + +```json +{ + "data": { + "type": "provider-secrets", + "id": "secret-uuid", + "attributes": { + "name": "Production AWS Role - Rotated", + "secret_type": "role", + "inserted_at": "2024-01-15T10:30:00Z", + "updated_at": "2024-01-20T14:45:00Z" + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } +} +``` + +### Error Responses + +**400 Bad Request** - Invalid secret format +```json +{ + "errors": [ + { + "status": "400", + "title": "Invalid Secret Format", + "detail": "Role ARN format is invalid" + } + ] +} +``` + +**404 Not Found** - Secret does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "Secret not found" + } + ] +} +``` + +## Next Steps + +After updating credentials: + +1. **Test Connection**: Verify the new credentials work + ```bash + curl -X POST "https://api.prowler.com/api/v1/providers/{provider_id}/connection" \ + -H "Authorization: Bearer YOUR_API_KEY" + ``` + +2. **Run Scan**: Confirm scanning works with new credentials + ```bash + curl -X POST "https://api.prowler.com/api/v1/scans" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{"data": {"type": "scans", "attributes": {"provider_id": "provider-uuid"}}}' + ``` + + +**Credential Rotation Best Practices:** +- Test new credentials before updating in production +- Keep old credentials valid until confirming new ones work +- Update secrets during maintenance windows +- Verify connection status after updates +- Monitor for authentication failures in scans + + + +When rotating AWS roles, create the new role first, update the secret, test it, then delete the old role to ensure zero downtime. + diff --git a/docs/api-reference/providers/update.mdx b/docs/api-reference/providers/update.mdx new file mode 100644 index 0000000000..896e218365 --- /dev/null +++ b/docs/api-reference/providers/update.mdx @@ -0,0 +1,123 @@ +--- +title: "Update Provider" +api: "PATCH /api/v1/providers/{id}" +description: "Modify certain fields of an existing provider." +--- + +Update an existing cloud provider's configuration or settings. + +## Path Parameters + +- `id` (required) - UUID of the provider to update + +## Request Body + +The request follows the JSON:API specification: + +```json +{ + "data": { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "alias": "Updated Provider Name" + } + } +} +``` + +### Attributes + +- `alias` (optional, string, nullable) - Human-readable name to identify the provider (3-100 characters) + + +Only the `alias` field can be updated. Other fields like `provider`, `uid`, and `connection` are read-only. Provider credentials and configuration are managed separately via the Provider Secrets endpoints. + + +## Example Request + +```bash +curl -X PATCH "https://api.prowler.com/api/v1/providers/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "alias": "Production AWS - Updated" + } + } + }' +``` + +## Response + +### Success Response (200 OK) + +Returns the updated provider with modified alias: + +```json +{ + "data": { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "provider": "aws", + "uid": "123456789012", + "alias": "Production AWS - Updated", + "connection": { + "connected": true, + "last_checked_at": "2024-01-20T10:30:00Z" + }, + "inserted_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-01-20T14:45:00Z" + }, + "relationships": { + "secret": { + "data": { + "type": "provider-secrets", + "id": "secret-uuid" + } + }, + "provider_groups": { + "data": [] + }, + "scans": { + "data": [] + } + } + } +} +``` + +### Error Responses + +**404 Not Found** - Provider does not exist +```json +{ + "errors": [ + { + "status": "404", + "title": "Not Found", + "detail": "Provider not found" + } + ] +} +``` + +**422 Unprocessable Entity** - Invalid alias +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "Alias must be between 3 and 100 characters", + "source": { + "pointer": "/data/attributes/alias" + } + } + ] +} +``` diff --git a/docs/api-reference/resources/latest.mdx b/docs/api-reference/resources/latest.mdx new file mode 100644 index 0000000000..0ebc2437c6 --- /dev/null +++ b/docs/api-reference/resources/latest.mdx @@ -0,0 +1,42 @@ +--- +title: "List Latest Resources" +api: "GET /api/v1/resources/latest" +description: "Retrieve resources from the latest scans for each provider." +--- + +Retrieve cloud resources from the most recent scan for each provider. This endpoint automatically filters to only include data from the latest scans. + +## Query Parameters + +### Filtering Options + +**By Provider:** +- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID(s) +- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type + +**By Resource:** +- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type +- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name +- `filter[region]`, `filter[region__in]` - Filter by region +- `filter[service]` - Filter by cloud service + +### Pagination & Sorting + +- `page[number]`, `page[size]` - Pagination controls +- `sort` - Field to sort by + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/resources/latest?filter[provider_type]=aws&filter[service]=s3" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns resources from the latest scans only. + + +This endpoint is optimized for dashboard views showing current infrastructure state. + diff --git a/docs/api-reference/resources/list.mdx b/docs/api-reference/resources/list.mdx new file mode 100644 index 0000000000..1edf7322ea --- /dev/null +++ b/docs/api-reference/resources/list.mdx @@ -0,0 +1,43 @@ +--- +title: "List Resources" +api: "GET /api/v1/resources" +description: "Retrieve a list of all cloud resources discovered during scans." +--- + +Retrieve all cloud resources (EC2 instances, S3 buckets, IAM roles, etc.) discovered across your providers. + +## Query Parameters + +### Required Filters +- `filter[inserted_at]` - At least one variation of this filter is required +- `filter[inserted_at__gte]`, `filter[inserted_at__lte]` - Filter by date range (maximum 7 days) + +### Filtering Options + +**By Provider:** +- `filter[provider]`, `filter[provider__in]` - Filter by provider UUID(s) +- `filter[provider_type]`, `filter[provider_type__in]` - Filter by provider type + +**By Resource:** +- `filter[resource_type]`, `filter[resource_type__icontains]` - Filter by resource type +- `filter[resource_name]`, `filter[resource_name__icontains]` - Filter by resource name +- `filter[resource_uid]`, `filter[resource_uid__icontains]` - Filter by resource UID +- `filter[region]`, `filter[region__in]` - Filter by region +- `filter[service]`, `filter[service__icontains]` - Filter by cloud service + +### Pagination & Sorting + +- `page[number]`, `page[size]` - Pagination controls +- `sort` - Field to sort by + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/resources?filter[inserted_at__gte]=2024-01-01&filter[resource_type]=aws_s3_bucket" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns a paginated list of cloud resources with their metadata. diff --git a/docs/api-reference/resources/metadata-latest.mdx b/docs/api-reference/resources/metadata-latest.mdx new file mode 100644 index 0000000000..ddb5c649fe --- /dev/null +++ b/docs/api-reference/resources/metadata-latest.mdx @@ -0,0 +1,29 @@ +--- +title: "Retrieve Latest Resources Metadata" +api: "GET /api/v1/resources/metadata/latest" +description: "Fetch unique metadata values from latest scan resources." +--- + +Retrieve metadata values from resources in the most recent scans for each provider. + +## Query Parameters + +### Filtering Options + +Filter by provider, resource type, region, service, etc. + +### Field Selection + +- `fields[resources-metadata]` - Specify which fields to return + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/resources/metadata/latest?filter[provider_type]=azure" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns unique metadata values from latest scan resources. diff --git a/docs/api-reference/resources/metadata.mdx b/docs/api-reference/resources/metadata.mdx new file mode 100644 index 0000000000..c3fb13443b --- /dev/null +++ b/docs/api-reference/resources/metadata.mdx @@ -0,0 +1,32 @@ +--- +title: "Retrieve Resources Metadata" +api: "GET /api/v1/resources/metadata" +description: "Fetch unique metadata values from resources for dynamic filtering." +--- + +Retrieve unique metadata values (services, regions, resource types) from your resources. Useful for building dynamic filters. + +## Query Parameters + +### Required Filters +- `filter[inserted_at]` - At least one variation required (maximum 7 days range) + +### Filtering Options + +Similar to the list resources endpoint - filter by provider, resource type, region, etc. + +### Field Selection + +- `fields[resources-metadata]` - Specify which fields to return + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/resources/metadata?filter[inserted_at__gte]=2024-01-01&filter[provider_type]=aws" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns unique metadata values from your resources. diff --git a/docs/api-reference/resources/retrieve.mdx b/docs/api-reference/resources/retrieve.mdx new file mode 100644 index 0000000000..3ff5e6f577 --- /dev/null +++ b/docs/api-reference/resources/retrieve.mdx @@ -0,0 +1,23 @@ +--- +title: "Retrieve Resource" +api: "GET /api/v1/resources/{id}" +description: "Fetch detailed information about a specific cloud resource." +--- + +Retrieve detailed information about a specific cloud resource including its configuration and associated findings. + +## Path Parameters + +- `id` (required) - UUID of the resource + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/resources/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns detailed resource information including metadata and configuration. diff --git a/docs/api-reference/roles/add-provider-groups.mdx b/docs/api-reference/roles/add-provider-groups.mdx new file mode 100644 index 0000000000..21d440c1a3 --- /dev/null +++ b/docs/api-reference/roles/add-provider-groups.mdx @@ -0,0 +1,7 @@ +--- +title: "Add Provider Groups to Role" +api: "POST /api/v1/roles/{id}/relationships/provider_groups" +description: "Associate provider groups with role." +--- + +Link provider groups to a role for scoped access. diff --git a/docs/api-reference/roles/create.mdx b/docs/api-reference/roles/create.mdx new file mode 100644 index 0000000000..52beca600d --- /dev/null +++ b/docs/api-reference/roles/create.mdx @@ -0,0 +1,20 @@ +--- +title: "Create Role" +api: "POST /api/v1/roles" +description: "Create a new RBAC role." +--- + +Create a custom role with specific permissions. + +## Request Body +\`\`\`json +{ + "data": { + "type": "roles", + "attributes": { + "name": "Security Auditor", + "permissions": ["read:findings", "read:scans"] + } + } +} +\`\`\` diff --git a/docs/api-reference/roles/delete.mdx b/docs/api-reference/roles/delete.mdx new file mode 100644 index 0000000000..c32f76286b --- /dev/null +++ b/docs/api-reference/roles/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Role" +api: "DELETE /api/v1/roles/{id}" +description: "Remove a role." +--- + +Delete a custom role. Built-in roles cannot be deleted. diff --git a/docs/api-reference/roles/list.mdx b/docs/api-reference/roles/list.mdx new file mode 100644 index 0000000000..c32712eb7e --- /dev/null +++ b/docs/api-reference/roles/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Roles" +api: "GET /api/v1/roles" +description: "Retrieve RBAC roles." +--- + +Get all roles available in the tenant for role-based access control. diff --git a/docs/api-reference/roles/remove-provider-groups.mdx b/docs/api-reference/roles/remove-provider-groups.mdx new file mode 100644 index 0000000000..e31582ddf0 --- /dev/null +++ b/docs/api-reference/roles/remove-provider-groups.mdx @@ -0,0 +1,7 @@ +--- +title: "Remove Provider Groups from Role" +api: "DELETE /api/v1/roles/{id}/relationships/provider_groups" +description: "Remove provider groups from role." +--- + +Disassociate provider groups from a role. diff --git a/docs/api-reference/roles/retrieve.mdx b/docs/api-reference/roles/retrieve.mdx new file mode 100644 index 0000000000..34d3d15063 --- /dev/null +++ b/docs/api-reference/roles/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Role" +api: "GET /api/v1/roles/{id}" +description: "Get role details." +--- + +Fetch information about a specific role. diff --git a/docs/api-reference/roles/update-provider-groups.mdx b/docs/api-reference/roles/update-provider-groups.mdx new file mode 100644 index 0000000000..7926aad220 --- /dev/null +++ b/docs/api-reference/roles/update-provider-groups.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Role Provider Groups" +api: "PATCH /api/v1/roles/{id}/relationships/provider_groups" +description: "Update role's provider groups." +--- + +Modify provider group associations for a role. diff --git a/docs/api-reference/roles/update.mdx b/docs/api-reference/roles/update.mdx new file mode 100644 index 0000000000..2380221d27 --- /dev/null +++ b/docs/api-reference/roles/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Role" +api: "PATCH /api/v1/roles/{id}" +description: "Update role permissions." +--- + +Modify role name or permissions. diff --git a/docs/api-reference/saml/create.mdx b/docs/api-reference/saml/create.mdx new file mode 100644 index 0000000000..248862e7e6 --- /dev/null +++ b/docs/api-reference/saml/create.mdx @@ -0,0 +1,21 @@ +--- +title: "Create SAML Configuration" +api: "POST /api/v1/saml-config" +description: "Configure SAML SSO." +--- + +Add SAML identity provider for SSO authentication. + +## Request Body +\`\`\`json +{ + "data": { + "type": "saml-config", + "attributes": { + "entity_id": "https://idp.example.com", + "sso_url": "https://idp.example.com/sso", + "x509_cert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----" + } + } +} +\`\`\` diff --git a/docs/api-reference/saml/delete.mdx b/docs/api-reference/saml/delete.mdx new file mode 100644 index 0000000000..73c0252310 --- /dev/null +++ b/docs/api-reference/saml/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete SAML Configuration" +api: "DELETE /api/v1/saml-config/{id}" +description: "Remove SAML SSO configuration." +--- + +Delete SAML identity provider. Users will need alternative authentication. diff --git a/docs/api-reference/saml/list.mdx b/docs/api-reference/saml/list.mdx new file mode 100644 index 0000000000..83abe21a32 --- /dev/null +++ b/docs/api-reference/saml/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List SAML Configurations" +api: "GET /api/v1/saml-config" +description: "Retrieve SAML SSO configurations." +--- + +Get configured SAML identity providers for single sign-on. diff --git a/docs/api-reference/saml/retrieve.mdx b/docs/api-reference/saml/retrieve.mdx new file mode 100644 index 0000000000..ee029d129e --- /dev/null +++ b/docs/api-reference/saml/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve SAML Configuration" +api: "GET /api/v1/saml-config/{id}" +description: "Get SAML SSO details." +--- + +Fetch SAML configuration details. diff --git a/docs/api-reference/saml/update.mdx b/docs/api-reference/saml/update.mdx new file mode 100644 index 0000000000..5cb8ad8f61 --- /dev/null +++ b/docs/api-reference/saml/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update SAML Configuration" +api: "PATCH /api/v1/saml-config/{id}" +description: "Update SAML SSO settings." +--- + +Modify SAML identity provider configuration. diff --git a/docs/api-reference/scans/compliance.mdx b/docs/api-reference/scans/compliance.mdx new file mode 100644 index 0000000000..eef51b127b --- /dev/null +++ b/docs/api-reference/scans/compliance.mdx @@ -0,0 +1,28 @@ +--- +title: "Get Scan Compliance Report" +api: "GET /api/v1/scans/{id}/compliance/{name}" +description: "Retrieve compliance framework results for a specific scan." +--- + +Get detailed compliance framework results for a specific scan. This endpoint returns the compliance status for frameworks like CIS, PCI-DSS, HIPAA, etc. + +## Path Parameters + +- `id` (required) - UUID of the scan +- `name` (required) - Name of the compliance framework (e.g., `cis_1.5_aws`, `pci_3.2.1_aws`) + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/scans/{id}/compliance/cis_1.5_aws" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns detailed compliance results including requirements passed, failed, and overall compliance score. + + +Use this endpoint to generate compliance reports for auditing and regulatory purposes. + diff --git a/docs/api-reference/scans/create.mdx b/docs/api-reference/scans/create.mdx new file mode 100644 index 0000000000..4c1dad0a6a --- /dev/null +++ b/docs/api-reference/scans/create.mdx @@ -0,0 +1,105 @@ +--- +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) + + +Monitor the scan progress by polling `GET /api/v1/scans/{id}` and checking the `state` and `progress` fields. + + + +Scans typically complete in 3-10 minutes depending on the number of resources. Poll every 30 seconds to monitor progress. + diff --git a/docs/api-reference/scans/list.mdx b/docs/api-reference/scans/list.mdx new file mode 100644 index 0000000000..58239bff14 --- /dev/null +++ b/docs/api-reference/scans/list.mdx @@ -0,0 +1,207 @@ +--- +title: "List Scans" +api: "GET /api/v1/scans" +description: "Retrieve a list of all security scans with filtering options." +--- + +Retrieve all security scans performed across your cloud providers. Scans contain the results of security checks run against your cloud infrastructure. + +## Use Cases + +- **Scan History**: View all scans performed on your infrastructure +- **Compliance Tracking**: Monitor scan completion for compliance requirements +- **Performance Monitoring**: Track scan duration and success rates +- **Audit Trail**: Maintain records of security assessments +- **Troubleshooting**: Investigate failed or stuck scans + +## Query Parameters + +### Filtering Options + +**By Provider:** +- `filter[provider_id]`, `filter[provider_id__in]` - Filter by provider UUID(s) + +**By Status:** +- `filter[state]`, `filter[state__in]` - Filter by scan state: + - `available` - Available + - `scheduled` - Scheduled but not started + - `executing` - Scan currently in progress + - `completed` - Scan finished successfully + - `failed` - Scan encountered errors + - `cancelled` - Scan was cancelled + +**By Date:** +- `filter[inserted_at]`, `filter[inserted_at__date]` - Filter by scan date +- `filter[inserted_at__gte]`, `filter[inserted_at__lte]` - Filter by date range + +### Pagination + +- `page[number]` - Page number to retrieve (default: 1) +- `page[size]` - Number of results per page (default: 20, max: 100) + +### Sorting + +- `sort` - Field to sort by: + - `inserted_at` - Oldest first + - `-inserted_at` - Newest first (default) + - `completed_at` - By completion time + - `-completed_at` - By completion time (descending) + +### Field Selection + +- `fields[scans]` - Specify which fields to return + +## Example Requests + +**Get recent completed scans:** +```bash +curl -X GET "https://api.prowler.com/api/v1/scans?filter[state]=completed&sort=-completed_at&page[size]=10" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +**Get scans for specific provider:** +```bash +curl -X GET "https://api.prowler.com/api/v1/scans?filter[provider_id]=provider-uuid&page[size]=20" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +**Get failed scans from last week:** +```bash +curl -X GET "https://api.prowler.com/api/v1/scans?filter[state]=failed&filter[inserted_at__gte]=2024-01-08" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +### Success Response (200 OK) + +Returns a paginated list of scans: + +```json +{ + "data": [ + { + "type": "scans", + "id": "scan-uuid", + "attributes": { + "status": "completed", + "unique_resource_count": 1247, + "duration": 342.5, + "started_at": "2024-01-15T10:00:00Z", + "completed_at": "2024-01-15T10:05:42Z", + "inserted_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-01-15T10:05:42Z", + "trigger": "manual", + "prowler_version": "4.0.0", + "summary": { + "total_checks": 350, + "passed_checks": 245, + "failed_checks": 85, + "manual_checks": 20, + "total_findings": 1152, + "failed_findings": 342, + "passed_findings": 810, + "severities": { + "critical": 12, + "high": 48, + "medium": 132, + "low": 98, + "informational": 52 + } + }, + "metadata": { + "regions_scanned": ["us-east-1", "us-west-2", "eu-west-1"], + "services_scanned": 45, + "checks_skipped": 0, + "error_count": 0 + } + }, + "relationships": { + "provider": { + "data": { + "type": "providers", + "id": "provider-uuid" + } + } + } + } + ], + "meta": { + "page": { + "number": 1, + "size": 20, + "total": 156, + "total_pages": 8 + } + }, + "links": { + "self": "https://api.prowler.com/api/v1/scans?page[number]=1", + "first": "https://api.prowler.com/api/v1/scans?page[number]=1", + "next": "https://api.prowler.com/api/v1/scans?page[number]=2", + "last": "https://api.prowler.com/api/v1/scans?page[number]=8" + }, + "included": [ + { + "type": "providers", + "id": "provider-uuid", + "attributes": { + "alias": "Production AWS - US", + "provider_type": "aws", + "uid": "123456789012" + } + } + ] +} +``` + +### Response Fields + +**Core Scan Information:** +- `id` (UUID) - Unique identifier for the scan +- `name` (string, nullable) - Optional scan name (3-100 characters) +- `state` (enum, read-only) - Current scan state: + - `available` - Available + - `scheduled` - Scheduled + - `executing` - Currently running + - `completed` - Finished successfully + - `failed` - Failed with errors + - `cancelled` - Was cancelled +- `trigger` (enum, read-only) - How scan was initiated: + - `manual` - Started manually + - `scheduled` - Started by schedule + +**Timing & Progress:** +- `inserted_at` (datetime, read-only) - When scan was created +- `started_at` (datetime, nullable) - When scan execution began +- `completed_at` (datetime, nullable) - When scan finished +- `scheduled_at` (datetime, nullable) - When scan was scheduled for +- `next_scan_at` (datetime, nullable) - When next scan is scheduled +- `duration` (integer, nullable) - Scan duration in seconds +- `progress` (integer) - Scan progress percentage (0-100) + +**Resources:** +- `unique_resource_count` (integer) - Number of unique cloud resources scanned + +### Scan State Lifecycle + +1. **available** → Scan ready to be executed +2. **scheduled** → Scan queued for future execution +3. **executing** → Scan currently in progress +4. **completed** → Scan finished successfully +5. **failed** → Scan encountered fatal errors +6. **cancelled** → Scan was cancelled by user + + +Scans typically complete within 3-10 minutes depending on the number of resources and regions. Large accounts with many resources may take up to 30 minutes. + + + +Only the 100 most recent scans are retained in the API. Export scan data to external storage for long-term retention. + + + +Monitor the `progress` field to track scan execution in real-time. Poll the scan endpoint while `state` is `executing` to see completion percentage. + diff --git a/docs/api-reference/scans/report.mdx b/docs/api-reference/scans/report.mdx new file mode 100644 index 0000000000..e06751a5b9 --- /dev/null +++ b/docs/api-reference/scans/report.mdx @@ -0,0 +1,32 @@ +--- +title: "Generate Scan Report" +api: "GET /api/v1/scans/{id}/report" +description: "Generate a downloadable report for a specific scan." +--- + +Generate and download a comprehensive security report for a specific scan in various formats (PDF, CSV, JSON, HTML). + +## Path Parameters + +- `id` (required) - UUID of the scan + +## Query Parameters + +- `format` - Report format: `pdf`, `csv`, `json`, `html` (default: `json`) + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/scans/{id}/report?format=pdf" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" \ + --output scan-report.pdf +``` + +## Response + +Returns the report file in the requested format. + + +PDF and HTML reports include visualizations and executive summaries, while CSV and JSON provide raw data for analysis. + diff --git a/docs/api-reference/scans/retrieve.mdx b/docs/api-reference/scans/retrieve.mdx new file mode 100644 index 0000000000..e7d16a35ed --- /dev/null +++ b/docs/api-reference/scans/retrieve.mdx @@ -0,0 +1,29 @@ +--- +title: "Retrieve Scan" +api: "GET /api/v1/scans/{id}" +description: "Fetch detailed information about a specific scan." +--- + +Retrieve detailed information about a specific security scan including its results and metadata. + +## Path Parameters + +- `id` (required) - UUID of the scan to retrieve + +## Query Parameters + +### Field Selection + +- `fields[scans]` - Specify which fields to return + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/scans/{id}" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns the scan details including findings summary, duration, and status. diff --git a/docs/api-reference/scans/threatscore.mdx b/docs/api-reference/scans/threatscore.mdx new file mode 100644 index 0000000000..ff1b91a6c1 --- /dev/null +++ b/docs/api-reference/scans/threatscore.mdx @@ -0,0 +1,27 @@ +--- +title: "Get Scan Threat Score" +api: "GET /api/v1/scans/{id}/threatscore" +description: "Retrieve the threat score and risk assessment for a specific scan." +--- + +Get the calculated threat score and risk assessment for a specific scan. The threat score is a weighted metric that considers severity, quantity, and criticality of findings. + +## Path Parameters + +- `id` (required) - UUID of the scan + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/scans/{id}/threatscore" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns the threat score along with contributing factors and risk breakdown. + + +The threat score ranges from 0-100, where higher scores indicate greater security risk. + diff --git a/docs/api-reference/scans/update.mdx b/docs/api-reference/scans/update.mdx new file mode 100644 index 0000000000..f9156a0365 --- /dev/null +++ b/docs/api-reference/scans/update.mdx @@ -0,0 +1,35 @@ +--- +title: "Update Scan" +api: "PATCH /api/v1/scans/{id}" +description: "Update scan metadata." +--- + +Update a scan's name or other mutable fields. + +## Path Parameters + +- `id` (required) - UUID of the scan to update + +## Request Body + +```json +{ + "data": { + "type": "scans", + "id": "scan-uuid", + "attributes": { + "name": "Updated Scan Name" + } + } +} +``` + +## Response + +### Success Response (200 OK) + +Returns the updated scan. + + +Only the `name` field can be updated. State and execution details are read-only. + diff --git a/docs/api-reference/schedules/create-daily.mdx b/docs/api-reference/schedules/create-daily.mdx new file mode 100644 index 0000000000..687470b772 --- /dev/null +++ b/docs/api-reference/schedules/create-daily.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Daily Schedule" +api: "POST /api/v1/schedules/daily" +description: "Schedule daily scans." +--- + +Configure recurring daily scan schedule. diff --git a/docs/api-reference/schedules/daily.mdx b/docs/api-reference/schedules/daily.mdx new file mode 100644 index 0000000000..fa98f70293 --- /dev/null +++ b/docs/api-reference/schedules/daily.mdx @@ -0,0 +1,39 @@ +--- +title: "Configure Daily Scan Schedule" +api: "POST /api/v1/schedules/daily" +description: "Configure automated daily scanning for providers." +--- + +Set up automated daily scans for your cloud providers. + +## Request Body + +```json +{ + "data": { + "type": "schedules", + "attributes": { + "enabled": true, + "time": "02:00", + "timezone": "UTC", + "providers": ["provider-uuid-1", "provider-uuid-2"] + } + } +} +``` + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/schedules/daily" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns the configured schedule. + + +Scans will run automatically at the specified time in the configured timezone. + diff --git a/docs/api-reference/tasks/delete.mdx b/docs/api-reference/tasks/delete.mdx new file mode 100644 index 0000000000..e9c9013c31 --- /dev/null +++ b/docs/api-reference/tasks/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Task" +api: "DELETE /api/v1/tasks/{id}" +description: "delete background tasks." +--- + +Manage asynchronous tasks. diff --git a/docs/api-reference/tasks/list.mdx b/docs/api-reference/tasks/list.mdx new file mode 100644 index 0000000000..9b9f328408 --- /dev/null +++ b/docs/api-reference/tasks/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Task" +api: "GET /api/v1/tasks" +description: "list background tasks." +--- + +Manage asynchronous tasks. diff --git a/docs/api-reference/tasks/retrieve.mdx b/docs/api-reference/tasks/retrieve.mdx new file mode 100644 index 0000000000..141c6f758b --- /dev/null +++ b/docs/api-reference/tasks/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Task" +api: "GET /api/v1/tasks/{id}" +description: "retrieve background tasks." +--- + +Manage asynchronous tasks. diff --git a/docs/api-reference/tenants/create.mdx b/docs/api-reference/tenants/create.mdx new file mode 100644 index 0000000000..4b5f0bfeda --- /dev/null +++ b/docs/api-reference/tenants/create.mdx @@ -0,0 +1,7 @@ +--- +title: "Create Tenant" +api: "POST /api/v1/tenants" +description: "Create a new tenant organization." +--- + +Create a new tenant (organization). diff --git a/docs/api-reference/tenants/delete.mdx b/docs/api-reference/tenants/delete.mdx new file mode 100644 index 0000000000..6df2c1c459 --- /dev/null +++ b/docs/api-reference/tenants/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Tenant" +api: "DELETE /api/v1/tenants/{id}" +description: "Remove a tenant." +--- + +Delete a tenant and all its data. This action cannot be undone. diff --git a/docs/api-reference/tenants/invitations-create.mdx b/docs/api-reference/tenants/invitations-create.mdx new file mode 100644 index 0000000000..25df7989d9 --- /dev/null +++ b/docs/api-reference/tenants/invitations-create.mdx @@ -0,0 +1,42 @@ +--- +title: "Create Tenant Invitation" +api: "POST /api/v1/tenants/invitations" +description: "Invite a user to join your tenant." +--- + +Send an invitation to a user to join your tenant. + +## Request Body + +```json +{ + "data": { + "type": "invitations", + "attributes": { + "email": "newuser@example.com", + "role": "member" + } + } +} +``` + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/tenants/invitations" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "invitations", + "attributes": { + "email": "newuser@example.com", + "role": "member" + } + } + }' +``` + +## Response + +Returns the created invitation. diff --git a/docs/api-reference/tenants/invitations-list.mdx b/docs/api-reference/tenants/invitations-list.mdx new file mode 100644 index 0000000000..39ef1e6b3c --- /dev/null +++ b/docs/api-reference/tenants/invitations-list.mdx @@ -0,0 +1,19 @@ +--- +title: "List Tenant Invitations" +api: "GET /api/v1/tenants/invitations" +description: "Retrieve pending invitations for the current tenant." +--- + +View all pending invitations sent from your tenant to other users. + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/tenants/invitations" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns a list of pending invitations. diff --git a/docs/api-reference/tenants/invitations/delete.mdx b/docs/api-reference/tenants/invitations/delete.mdx new file mode 100644 index 0000000000..d537f39d1a --- /dev/null +++ b/docs/api-reference/tenants/invitations/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete Tenant Invitation" +api: "DELETE /api/v1/tenants/{id}/invitations/{invitation_id}" +description: "Cancel invitation." +--- + +Cancel a pending invitation. diff --git a/docs/api-reference/tenants/invitations/retrieve.mdx b/docs/api-reference/tenants/invitations/retrieve.mdx new file mode 100644 index 0000000000..72fb54a26c --- /dev/null +++ b/docs/api-reference/tenants/invitations/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Tenant Invitation" +api: "GET /api/v1/tenants/{id}/invitations/{invitation_id}" +description: "Get invitation details." +--- + +Fetch information about a specific invitation. diff --git a/docs/api-reference/tenants/invitations/update.mdx b/docs/api-reference/tenants/invitations/update.mdx new file mode 100644 index 0000000000..221a18e93b --- /dev/null +++ b/docs/api-reference/tenants/invitations/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Tenant Invitation" +api: "PATCH /api/v1/tenants/{id}/invitations/{invitation_id}" +description: "Update invitation." +--- + +Modify invitation or resend. diff --git a/docs/api-reference/tenants/list.mdx b/docs/api-reference/tenants/list.mdx new file mode 100644 index 0000000000..fe77d40419 --- /dev/null +++ b/docs/api-reference/tenants/list.mdx @@ -0,0 +1,19 @@ +--- +title: "List Tenants" +api: "GET /api/v1/tenants" +description: "Retrieve a list of tenants you belong to." +--- + +Retrieve all tenants (organizations) that you are a member of. + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/tenants" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns a list of tenants with their details and your role in each. diff --git a/docs/api-reference/tenants/memberships/delete.mdx b/docs/api-reference/tenants/memberships/delete.mdx new file mode 100644 index 0000000000..2bddbb5bc4 --- /dev/null +++ b/docs/api-reference/tenants/memberships/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Remove Tenant Membership" +api: "DELETE /api/v1/tenants/{id}/memberships/{membership_id}" +description: "Remove user from tenant." +--- + +Remove a user's membership from the tenant. diff --git a/docs/api-reference/tenants/memberships/list.mdx b/docs/api-reference/tenants/memberships/list.mdx new file mode 100644 index 0000000000..398717e887 --- /dev/null +++ b/docs/api-reference/tenants/memberships/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Tenant Memberships" +api: "GET /api/v1/tenants/{id}/memberships" +description: "Get all members of a tenant." +--- + +Retrieve users who are members of the tenant. diff --git a/docs/api-reference/tenants/retrieve.mdx b/docs/api-reference/tenants/retrieve.mdx new file mode 100644 index 0000000000..bad7e46252 --- /dev/null +++ b/docs/api-reference/tenants/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve Tenant" +api: "GET /api/v1/tenants/{id}" +description: "Get tenant details." +--- + +Fetch information about a specific tenant. diff --git a/docs/api-reference/tenants/update.mdx b/docs/api-reference/tenants/update.mdx new file mode 100644 index 0000000000..1c48adfa65 --- /dev/null +++ b/docs/api-reference/tenants/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update Tenant" +api: "PATCH /api/v1/tenants/{id}" +description: "Update tenant settings." +--- + +Modify tenant name or configuration. diff --git a/docs/api-reference/tokens/create.mdx b/docs/api-reference/tokens/create.mdx new file mode 100644 index 0000000000..d6e7f971a8 --- /dev/null +++ b/docs/api-reference/tokens/create.mdx @@ -0,0 +1,201 @@ +--- +title: "Create JWT Token" +api: "POST /api/v1/tokens" +description: "Authenticate and obtain a JWT access token." +--- + +Authenticate with Prowler using email and password credentials to receive JWT tokens for API access. This is the primary authentication method for the Prowler API. + +## Use Cases + +- **Initial Authentication**: Login to obtain tokens for API access +- **Application Integration**: Authenticate service accounts or automation tools +- **Multi-tenant Access**: Obtain tokens with specific tenant context +- **Session Management**: Create new sessions for web applications + +## Request Body + +The request follows the JSON:API specification: + +```json +{ + "data": { + "type": "tokens", + "attributes": { + "email": "user@example.com", + "password": "your-password", + "tenant_id": "optional-tenant-uuid" + } + } +} +``` + + +The `tenant_id` field is optional. If omitted, you'll be authenticated with your first tenant membership. Use `/api/v1/tokens/switch` to change tenants after authentication. + + +### Attributes + +- `email` (required, string, write-only) - User email address registered in Prowler +- `password` (required, string, write-only) - User password +- `tenant_id` (optional, string UUID, write-only) - Specific tenant ID to authenticate with + - If not provided, the first tenant membership will be used + - Use this to specify which organization/tenant to access + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/tokens" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "tokens", + "attributes": { + "email": "security-team@company.com", + "password": "SecurePassword123!" + } + } + }' +``` + +## Response + +### Success Response (200 OK) + +Returns JWT access and refresh tokens: + +```json +{ + "data": { + "type": "tokens", + "attributes": { + "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlkIiwiZXhwIjoxNzA2MTg0MDAwfQ...", + "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLWlkIiwiZXhwIjoxNzA4Nzc2MDAwfQ..." + } + } +} +``` + +### Response Fields + +- `access` (string, read-only) - JWT access token for API authentication + - Use this token in the `Authorization: Bearer ` header for API requests + - Typically valid for a limited time (e.g., 1 hour) + +- `refresh` (string, read-only) - JWT refresh token to obtain new access tokens + - Use this token with the `/api/v1/tokens/refresh` endpoint when access token expires + - Typically valid for a longer period (e.g., 30 days) + - Only one refresh token is valid at a time; refreshing invalidates the previous one + +### Error Responses + +**401 Unauthorized** - Invalid credentials +```json +{ + "errors": [ + { + "status": "401", + "title": "Authentication Failed", + "detail": "Invalid email or password" + } + ] +} +``` + +**422 Unprocessable Entity** - Missing or invalid fields +```json +{ + "errors": [ + { + "status": "422", + "title": "Validation Error", + "detail": "Email is required", + "source": { + "pointer": "/data/attributes/email" + } + } + ] +} +``` + +**429 Too Many Requests** - Rate limit exceeded +```json +{ + "errors": [ + { + "status": "429", + "title": "Rate Limit Exceeded", + "detail": "Too many authentication attempts. Please try again in 15 minutes." + } + ] +} +``` + +## Usage Example + +After obtaining tokens, use the `access` token in subsequent API requests: + +```bash +# Save the tokens from the response +ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # from attributes.access +REFRESH_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # from attributes.refresh + +# Use access token in API requests +curl -X GET "https://api.prowler.com/api/v1/providers" \ + -H "Authorization: Bearer $ACCESS_TOKEN" \ + -H "Content-Type: application/vnd.api+json" + +# When access token expires, refresh it +curl -X POST "https://api.prowler.com/api/v1/tokens/refresh" \ + -H "Content-Type: application/vnd.api+json" \ + -d "{\"data\":{\"type\":\"tokens-refresh\",\"attributes\":{\"refresh\":\"$REFRESH_TOKEN\"}}}" +``` + +## Token Lifecycle + +1. **Access Token**: Use for all API requests in the `Authorization` header + - Short-lived (typically 1 hour) + - Included in every API request + +2. **Refresh Token**: Use to obtain new access tokens + - Long-lived (typically 30 days) + - Only used with `/api/v1/tokens/refresh` endpoint + - Previous refresh token is invalidated when a new one is issued + +3. **Token Refresh Flow**: + ```bash + # When access token expires, use refresh token + curl -X POST "https://api.prowler.com/api/v1/tokens/refresh" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "tokens-refresh", + "attributes": { + "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } + } + }' + ``` + +4. **Revocation**: Tokens are automatically invalidated on: + - Password change + - Explicit logout + - Security events + + +**Security Best Practices:** +- Store tokens securely (encrypted storage, environment variables, secure vaults) +- Never commit tokens to version control +- Never log tokens or expose them in error messages +- Use HTTPS for all API communications +- Implement token rotation using refresh tokens +- Revoke tokens when no longer needed + + + +**Rate Limiting:** This endpoint is rate-limited to 5 requests per minute per IP address to prevent brute-force attacks. + + + +For automated systems and CI/CD pipelines, consider using API Keys instead of JWT tokens for more stable, long-lived authentication. + diff --git a/docs/api-reference/tokens/refresh.mdx b/docs/api-reference/tokens/refresh.mdx new file mode 100644 index 0000000000..405408b439 --- /dev/null +++ b/docs/api-reference/tokens/refresh.mdx @@ -0,0 +1,43 @@ +--- +title: "Refresh JWT Token" +api: "POST /api/v1/tokens/refresh" +description: "Refresh an expired JWT token." +--- + +Use a refresh token to obtain a new JWT access token without re-authenticating. + +## Request Body + +```json +{ + "data": { + "type": "tokens", + "attributes": { + "refresh_token": "your-refresh-token" + } + } +} +``` + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/tokens/refresh" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "tokens", + "attributes": { + "refresh_token": "your-refresh-token" + } + } + }' +``` + +## Response + +Returns a new JWT access token. + + +Refresh tokens have a longer lifespan than access tokens and should be used to maintain sessions. + diff --git a/docs/api-reference/tokens/switch.mdx b/docs/api-reference/tokens/switch.mdx new file mode 100644 index 0000000000..22f70f37f5 --- /dev/null +++ b/docs/api-reference/tokens/switch.mdx @@ -0,0 +1,40 @@ +--- +title: "Switch Tenant Context" +api: "POST /api/v1/tokens/switch" +description: "Switch to a different tenant context." +--- + +Switch your authentication context to a different tenant if you belong to multiple tenants. + +## Request Body + +```json +{ + "data": { + "type": "tokens", + "attributes": { + "tenant_id": "tenant-uuid" + } + } +} +``` + +## Example Request + +```bash +curl -X POST "https://api.prowler.com/api/v1/tokens/switch" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + -d '{ + "data": { + "type": "tokens", + "attributes": { + "tenant_id": "tenant-uuid" + } + } + }' +``` + +## Response + +Returns a new JWT token with the selected tenant context. diff --git a/docs/api-reference/users/add-roles.mdx b/docs/api-reference/users/add-roles.mdx new file mode 100644 index 0000000000..c25a47419e --- /dev/null +++ b/docs/api-reference/users/add-roles.mdx @@ -0,0 +1,7 @@ +--- +title: "Add Roles to User" +api: "POST /api/v1/users/{id}/relationships/roles" +description: "Assign roles to user." +--- + +Grant roles to a user for RBAC. diff --git a/docs/api-reference/users/create.mdx b/docs/api-reference/users/create.mdx new file mode 100644 index 0000000000..b57caeb483 --- /dev/null +++ b/docs/api-reference/users/create.mdx @@ -0,0 +1,20 @@ +--- +title: "Create User" +api: "POST /api/v1/users" +description: "Invite a new user to the tenant." +--- + +Create and invite a new user. + +## Request Body +\`\`\`json +{ + "data": { + "type": "users", + "attributes": { + "email": "user@example.com", + "name": "John Doe" + } + } +} +\`\`\` diff --git a/docs/api-reference/users/delete.mdx b/docs/api-reference/users/delete.mdx new file mode 100644 index 0000000000..73d4cb5f03 --- /dev/null +++ b/docs/api-reference/users/delete.mdx @@ -0,0 +1,7 @@ +--- +title: "Delete User" +api: "DELETE /api/v1/users/{id}" +description: "Remove user from tenant." +--- + +Delete a user. This action cannot be undone. diff --git a/docs/api-reference/users/list.mdx b/docs/api-reference/users/list.mdx new file mode 100644 index 0000000000..98f5e9aa10 --- /dev/null +++ b/docs/api-reference/users/list.mdx @@ -0,0 +1,7 @@ +--- +title: "List Users" +api: "GET /api/v1/users" +description: "Retrieve all users in the tenant." +--- + +Get list of users with their roles and permissions. diff --git a/docs/api-reference/users/me.mdx b/docs/api-reference/users/me.mdx new file mode 100644 index 0000000000..c83c7ebeed --- /dev/null +++ b/docs/api-reference/users/me.mdx @@ -0,0 +1,23 @@ +--- +title: "Get Current User" +api: "GET /api/v1/users/me" +description: "Retrieve information about the currently authenticated user." +--- + +Get profile information for the currently authenticated user including roles and permissions. + +## Example Request + +```bash +curl -X GET "https://api.prowler.com/api/v1/users/me" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" \ + -H "Content-Type: application/vnd.api+json" +``` + +## Response + +Returns the current user's profile including email, roles, tenants, and permissions. + + +Use this endpoint to verify authentication and retrieve user context for your application. + diff --git a/docs/api-reference/users/memberships-list.mdx b/docs/api-reference/users/memberships-list.mdx new file mode 100644 index 0000000000..d485705fea --- /dev/null +++ b/docs/api-reference/users/memberships-list.mdx @@ -0,0 +1,7 @@ +--- +title: "List User Memberships" +api: "GET /api/v1/users/{id}/memberships" +description: "Get user's tenant memberships." +--- + +Retrieve tenants the user belongs to. diff --git a/docs/api-reference/users/memberships-retrieve.mdx b/docs/api-reference/users/memberships-retrieve.mdx new file mode 100644 index 0000000000..8c5a101c61 --- /dev/null +++ b/docs/api-reference/users/memberships-retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve User Membership" +api: "GET /api/v1/users/{id}/memberships/{membership_id}" +description: "Get specific membership details." +--- + +Fetch details about a user's membership in a tenant. diff --git a/docs/api-reference/users/remove-roles.mdx b/docs/api-reference/users/remove-roles.mdx new file mode 100644 index 0000000000..1fb69c2c24 --- /dev/null +++ b/docs/api-reference/users/remove-roles.mdx @@ -0,0 +1,7 @@ +--- +title: "Remove Roles from User" +api: "DELETE /api/v1/users/{id}/relationships/roles" +description: "Revoke roles from user." +--- + +Remove role assignments from a user. diff --git a/docs/api-reference/users/retrieve.mdx b/docs/api-reference/users/retrieve.mdx new file mode 100644 index 0000000000..4a8719feb5 --- /dev/null +++ b/docs/api-reference/users/retrieve.mdx @@ -0,0 +1,7 @@ +--- +title: "Retrieve User" +api: "GET /api/v1/users/{id}" +description: "Get user details." +--- + +Fetch information about a specific user. diff --git a/docs/api-reference/users/update-roles.mdx b/docs/api-reference/users/update-roles.mdx new file mode 100644 index 0000000000..9c1d0674de --- /dev/null +++ b/docs/api-reference/users/update-roles.mdx @@ -0,0 +1,7 @@ +--- +title: "Update User Roles" +api: "PATCH /api/v1/users/{id}/relationships/roles" +description: "Update user's assigned roles." +--- + +Modify user role assignments. diff --git a/docs/api-reference/users/update.mdx b/docs/api-reference/users/update.mdx new file mode 100644 index 0000000000..acf22d84f7 --- /dev/null +++ b/docs/api-reference/users/update.mdx @@ -0,0 +1,7 @@ +--- +title: "Update User" +api: "PATCH /api/v1/users/{id}" +description: "Update user information." +--- + +Modify user details or status. diff --git a/docs/docs.json b/docs/docs.json index 54402e5d8a..040841374d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -316,6 +316,271 @@ "troubleshooting" ] }, + { + "tab": "API Reference", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "API Endpoints", + "pages": [ + { + "group": "Authentication", + "pages": [ + "api-reference/tokens/create", + "api-reference/tokens/refresh", + "api-reference/tokens/switch" + ] + }, + { + "group": "API Keys", + "pages": [ + "api-reference/api-keys/list", + "api-reference/api-keys/create", + "api-reference/api-keys/retrieve", + "api-reference/api-keys/update", + "api-reference/api-keys/revoke" + ] + }, + { + "group": "Users", + "pages": [ + "api-reference/users/me", + "api-reference/users/list", + "api-reference/users/create", + "api-reference/users/retrieve", + "api-reference/users/update", + "api-reference/users/delete", + "api-reference/users/memberships-list", + "api-reference/users/memberships-retrieve", + "api-reference/users/add-roles", + "api-reference/users/update-roles", + "api-reference/users/remove-roles" + ] + }, + { + "group": "Tenants", + "pages": [ + "api-reference/tenants/list", + "api-reference/tenants/create", + "api-reference/tenants/retrieve", + "api-reference/tenants/update", + "api-reference/tenants/delete", + { + "group": "Memberships", + "pages": [ + "api-reference/tenants/memberships/list", + "api-reference/tenants/memberships/delete" + ] + }, + { + "group": "Invitations", + "pages": [ + "api-reference/tenants/invitations-list", + "api-reference/tenants/invitations-create", + "api-reference/tenants/invitations/retrieve", + "api-reference/tenants/invitations/update", + "api-reference/tenants/invitations/delete" + ] + } + ] + }, + { + "group": "Invitations", + "pages": [ + "api-reference/invitations/accept" + ] + }, + { + "group": "Provider Groups", + "pages": [ + "api-reference/provider-groups/list", + "api-reference/provider-groups/create", + "api-reference/provider-groups/retrieve", + "api-reference/provider-groups/update", + "api-reference/provider-groups/delete", + "api-reference/provider-groups/add-providers", + "api-reference/provider-groups/update-providers", + "api-reference/provider-groups/remove-providers" + ] + }, + { + "group": "Roles", + "pages": [ + "api-reference/roles/list", + "api-reference/roles/create", + "api-reference/roles/retrieve", + "api-reference/roles/update", + "api-reference/roles/delete", + "api-reference/roles/add-provider-groups", + "api-reference/roles/update-provider-groups", + "api-reference/roles/remove-provider-groups" + ] + }, + { + "group": "SAML Configuration", + "pages": [ + "api-reference/saml/list", + "api-reference/saml/create", + "api-reference/saml/retrieve", + "api-reference/saml/update", + "api-reference/saml/delete" + ] + }, + { + "group": "Providers", + "pages": [ + "api-reference/providers/list", + "api-reference/providers/create", + "api-reference/providers/retrieve", + "api-reference/providers/update", + "api-reference/providers/delete", + "api-reference/providers/check-connection", + { + "group": "Provider Secrets", + "pages": [ + "api-reference/providers/secrets/list", + "api-reference/providers/secrets/create", + "api-reference/providers/secrets/retrieve", + "api-reference/providers/secrets/update", + "api-reference/providers/secrets/delete" + ] + } + ] + }, + { + "group": "Scans", + "pages": [ + "api-reference/scans/list", + "api-reference/scans/create", + "api-reference/scans/retrieve", + "api-reference/scans/update", + "api-reference/scans/compliance", + "api-reference/scans/report", + "api-reference/scans/threatscore" + ] + }, + { + "group": "Findings", + "pages": [ + "api-reference/findings/list", + "api-reference/findings/retrieve", + "api-reference/findings/latest", + "api-reference/findings/services-regions", + "api-reference/findings/metadata", + "api-reference/findings/metadata-latest" + ] + }, + { + "group": "Resources", + "pages": [ + "api-reference/resources/list", + "api-reference/resources/retrieve", + "api-reference/resources/latest", + "api-reference/resources/metadata", + "api-reference/resources/metadata-latest" + ] + }, + { + "group": "Compliance Overview", + "pages": [ + "api-reference/compliance/list", + "api-reference/compliance/requirements", + "api-reference/compliance/attributes", + "api-reference/compliance/metadata" + ] + }, + { + "group": "Overviews", + "pages": [ + "api-reference/overviews/findings", + "api-reference/overviews/findings-severity", + "api-reference/overviews/providers", + "api-reference/overviews/providers-count", + "api-reference/overviews/services" + ] + }, + { + "group": "Integrations", + "pages": [ + "api-reference/integrations/list", + "api-reference/integrations/create", + "api-reference/integrations/retrieve", + "api-reference/integrations/update", + "api-reference/integrations/delete", + "api-reference/integrations/check-connection", + "api-reference/integrations/jira-dispatch" + ] + }, + { + "group": "Lighthouse AI", + "pages": [ + { + "group": "Providers", + "pages": [ + "api-reference/lighthouse/providers/list", + "api-reference/lighthouse/providers/create", + "api-reference/lighthouse/providers/retrieve", + "api-reference/lighthouse/providers/update", + "api-reference/lighthouse/providers/delete", + "api-reference/lighthouse/providers/test-connection", + "api-reference/lighthouse/providers/refresh-models" + ] + }, + { + "group": "Configurations", + "pages": [ + "api-reference/lighthouse/configurations/list", + "api-reference/lighthouse/configurations/create", + "api-reference/lighthouse/configurations/retrieve", + "api-reference/lighthouse/configurations/update", + "api-reference/lighthouse/configurations/delete", + "api-reference/lighthouse/configurations/test-connection" + ] + }, + { + "group": "Models", + "pages": [ + "api-reference/lighthouse/models/list", + "api-reference/lighthouse/models/retrieve" + ] + }, + "api-reference/lighthouse/config-list", + "api-reference/lighthouse/config-update" + ] + }, + { + "group": "Processors", + "pages": [ + "api-reference/processors/list", + "api-reference/processors/create", + "api-reference/processors/retrieve", + "api-reference/processors/update", + "api-reference/processors/delete" + ] + }, + { + "group": "Schedules", + "pages": [ + "api-reference/schedules/create-daily" + ] + }, + { + "group": "Tasks", + "pages": [ + "api-reference/tasks/list", + "api-reference/tasks/retrieve", + "api-reference/tasks/delete" + ] + } + ] + } + ] + }, { "tab": "About Us", "icon": "/favicon.ico", @@ -384,6 +649,16 @@ "website": "https://prowler.com" } }, + "openapi": "/api-reference/openapi.yaml", + "api": { + "baseUrl": "https://api.prowler.com", + "auth": { + "method": "bearer" + }, + "playground": { + "mode": "simple" + } + }, "redirects": [ { "source": "/projects/prowler-open-source/en/latest/tutorials/prowler-app-lighthouse", diff --git a/docs/generate-api-docs.py b/docs/generate-api-docs.py new file mode 100755 index 0000000000..0e269398ca --- /dev/null +++ b/docs/generate-api-docs.py @@ -0,0 +1,409 @@ +#!/usr/bin/env python3 +""" +Prowler API Documentation Auto-Generator +Generates MDX files from OpenAPI specification + +Usage: + python3 generate-api-docs.py [--update-existing] [--dry-run] + +Options: + --update-existing Update existing MDX files (default: skip existing files) + --dry-run Show what would be generated without writing files + --help Show this help message +""" + +import argparse +import json +import sys +from pathlib import Path +from typing import Any, Dict, Optional + +import yaml + + +class APIDocGenerator: + """Generate Mintlify MDX documentation from OpenAPI spec""" + + def __init__(self, openapi_file: str, api_reference_dir: str): + self.openapi_file = openapi_file + self.api_reference_dir = Path(api_reference_dir) + self.spec = None + self.stats = {"generated": 0, "updated": 0, "skipped": 0, "errors": 0} + + def load_spec(self): + """Load OpenAPI specification""" + print(f"📖 Loading OpenAPI spec from {self.openapi_file}") + with open(self.openapi_file, "r") as f: + self.spec = yaml.safe_load(f) + print(f"✅ Loaded spec version {self.spec.get('info', {}).get('version')}") + + def operation_id_to_path(self, operation_id: str) -> Optional[str]: + """Convert operation ID to file path + + Examples: + providers_secrets_create -> providers/secrets/create.mdx + tokens_create -> tokens/create.mdx + users_memberships_list -> users/memberships-list.mdx + """ + parts = operation_id.split("_") + + # Map operation IDs to directory names + path_map = { + "tokens": "tokens", + "api_keys": "api-keys", + "users": "users", + "tenants": "tenants", + "invitations": "invitations", + "providers": "providers", + "scans": "scans", + "findings": "findings", + "resources": "resources", + "compliance": "compliance", + "overviews": "overviews", + "integrations": "integrations", + "lighthouse": "lighthouse", + "processors": "processors", + "schedules": "schedules", + "tasks": "tasks", + "roles": "roles", + "provider_groups": "provider-groups", + "saml_config": "saml", + } + + if not parts: + return None + + base = parts[0] + if base not in path_map: + return None + + directory = path_map[base] + + # Handle nested resources + if len(parts) > 2: + # Check if second part is a sub-resource (not an action) + actions = [ + "list", + "create", + "retrieve", + "update", + "delete", + "revoke", + "accept", + "refresh", + "switch", + "report", + "compliance", + "threatscore", + "latest", + "metadata", + ] + + if parts[1] not in actions: + subdirectory = parts[1].replace("_", "-") + action = "-".join(parts[2:]) + return f"{directory}/{subdirectory}/{action}.mdx" + + # Simple resource action + action = "-".join(parts[1:]) + return f"{directory}/{action}.mdx" + + def format_title(self, operation_id: str, summary: Optional[str]) -> str: + """Format title from operation ID or summary""" + if summary: + return summary + + parts = operation_id.split("_") + action = parts[-1].replace("_", " ").title() + resource = " ".join(parts[:-1]).replace("_", " ").title() + return f"{action} {resource}" + + def extract_parameters(self, operation: Dict[str, Any]) -> str: + """Extract and format parameters section""" + parameters = operation.get("parameters", []) + if not parameters: + return "" + + path_params = [p for p in parameters if p.get("in") == "path"] + query_params = [p for p in parameters if p.get("in") == "query"] + + sections = [] + + if path_params: + sections.append("## Path Parameters\n") + for param in path_params: + name = param.get("name") + required = "required" if param.get("required") else "optional" + desc = param.get("description", "No description") + schema = param.get("schema", {}) + param_type = schema.get("type", "string") + sections.append(f"- `{name}` ({required}, {param_type}) - {desc}") + + if query_params: + sections.append("\n## Query Parameters\n") + for param in query_params: + name = param.get("name") + required = "required" if param.get("required") else "optional" + desc = param.get("description", "No description") + schema = param.get("schema", {}) + param_type = schema.get("type", "string") + sections.append(f"- `{name}` ({required}, {param_type}) - {desc}") + + return "\n".join(sections) + + def extract_request_body(self, operation: Dict[str, Any]) -> str: + """Extract and format request body section""" + request_body = operation.get("requestBody") + if not request_body: + return "" + + content = request_body.get("content", {}) + json_content = content.get("application/vnd.api+json", {}) + + if not json_content: + return "" + + example = json_content.get("example", {}) + + if example: + example_json = json.dumps(example, indent=2) + return f""" +## Request Body + +```json +{example_json} +``` +""" + + # If no example, show schema info + schema = json_content.get("schema", {}) + if schema: + return """ +## Request Body + +Request body follows JSON:API specification. See OpenAPI spec for detailed schema. +""" + + return "" + + def extract_responses(self, operation: Dict[str, Any]) -> str: + """Extract and format responses section""" + responses = operation.get("responses", {}) + if not responses: + return "" + + sections = [] + + # Success response + for status in ["200", "201", "204"]: + response = responses.get(status) + if response: + desc = response.get("description", "Success") + sections.append(f"## Response\n\n{desc}\n") + + content = response.get("content", {}) + json_content = content.get("application/vnd.api+json", {}) + example = json_content.get("example", {}) + + if example: + example_json = json.dumps(example, indent=2) + sections.append(f"```json\n{example_json}\n```\n") + + break + + return "\n".join(sections) + + def generate_mdx( + self, operation_id: str, method: str, path: str, operation: Dict[str, Any] + ) -> str: + """Generate complete MDX content for an endpoint""" + + title = self.format_title(operation_id, operation.get("summary")) + description = operation.get("description") or operation.get("summary") or "" + api_path = f"{method.upper()} {path}" + + # Extract sections + parameters = self.extract_parameters(operation) + request_body = self.extract_request_body(operation) + responses = self.extract_responses(operation) + + # Build MDX content + mdx_parts = [ + "---", + f'title: "{title}"', + f'api: "{api_path}"', + f'description: "{description}"', + "---", + "", + description, + "", + ] + + if parameters: + mdx_parts.extend([parameters, ""]) + + if request_body: + mdx_parts.extend([request_body, ""]) + + if responses: + mdx_parts.extend([responses, ""]) + + return "\n".join(mdx_parts).strip() + "\n" + + def generate_docs(self, update_existing: bool = False, dry_run: bool = False): + """Generate MDX files for all operations""" + + if not self.spec: + raise ValueError("OpenAPI spec not loaded. Call load_spec() first.") + + print("\n🔄 Generating documentation files...") + print(f" Update existing: {update_existing}") + print(f" Dry run: {dry_run}\n") + + generated_files = [] + skipped_files = [] + error_files = [] + + paths = self.spec.get("paths", {}) + total_operations = sum( + len([m for m in p.keys() if m in ["get", "post", "put", "patch", "delete"]]) + for p in paths.values() + ) + + print(f"Found {total_operations} operations to process\n") + + for path, path_item in paths.items(): + for method in ["get", "post", "put", "patch", "delete"]: + operation = path_item.get(method) + if not operation: + continue + + operation_id = operation.get("operationId") + if not operation_id: + continue + + try: + file_path = self.operation_id_to_path(operation_id) + if not file_path: + skipped_files.append((operation_id, "Could not determine path")) + self.stats["skipped"] += 1 + continue + + full_path = self.api_reference_dir / file_path + + # Check if file exists and should be skipped + if full_path.exists() and not update_existing: + # Check if file has substantial content + if full_path.stat().st_size > 150: + skipped_files.append( + (operation_id, "File exists with content") + ) + self.stats["skipped"] += 1 + continue + + # Generate MDX content + mdx_content = self.generate_mdx( + operation_id, method, path, operation + ) + + if dry_run: + print(f"Would generate: {file_path}") + generated_files.append(file_path) + continue + + # Create directory if needed + full_path.parent.mkdir(parents=True, exist_ok=True) + + # Write file + action = "Updated" if full_path.exists() else "Generated" + with open(full_path, "w") as f: + f.write(mdx_content) + + generated_files.append(file_path) + if action == "Updated": + self.stats["updated"] += 1 + else: + self.stats["generated"] += 1 + + print(f"✅ {action}: {file_path}") + + except Exception as e: + error_files.append((operation_id, str(e))) + self.stats["errors"] += 1 + print(f"❌ Error processing {operation_id}: {e}") + + # Print summary + print("\n" + "=" * 60) + print("📊 Generation Summary") + print("=" * 60) + print(f"Generated: {self.stats['generated']}") + print(f"Updated: {self.stats['updated']}") + print(f"Skipped: {self.stats['skipped']}") + print(f"Errors: {self.stats['errors']}") + print(f"Total: {total_operations}") + + if skipped_files and len(skipped_files) <= 10: + print("\nSkipped operations:") + for op_id, reason in skipped_files: + print(f" - {op_id}: {reason}") + + if error_files: + print("\nErrors:") + for op_id, error in error_files: + print(f" - {op_id}: {error}") + + return self.stats + + +def main(): + parser = argparse.ArgumentParser( + description="Generate Mintlify MDX documentation from OpenAPI spec" + ) + parser.add_argument( + "--update-existing", action="store_true", help="Update existing MDX files" + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Show what would be generated without writing files", + ) + + args = parser.parse_args() + + # Paths + script_dir = Path(__file__).parent + openapi_file = script_dir / "api-reference" / "openapi.yaml" + api_reference_dir = script_dir / "api-reference" + + # Check if OpenAPI file exists + if not openapi_file.exists(): + print(f"❌ Error: OpenAPI spec not found at {openapi_file}") + print(" Run ./sync-api-spec.sh first to download the spec") + sys.exit(1) + + # Generate documentation + generator = APIDocGenerator(str(openapi_file), str(api_reference_dir)) + + try: + generator.load_spec() + generator.generate_docs( + update_existing=args.update_existing, dry_run=args.dry_run + ) + + if not args.dry_run: + print("\n✅ Documentation generation complete!") + print("\n💡 Next steps:") + print(" 1. Review generated files in api-reference/") + print(" 2. Add detailed descriptions and examples") + print(" 3. Update docs.json if new groups were added") + print(" 4. Test with: cd docs && mintlify dev") + else: + print("\n🔍 Dry run complete - no files were modified") + + except Exception as e: + print(f"❌ Fatal error: {e}") + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/docs/sync-api-spec.sh b/docs/sync-api-spec.sh new file mode 100755 index 0000000000..35f4ad2abd --- /dev/null +++ b/docs/sync-api-spec.sh @@ -0,0 +1,62 @@ +#!/bin/bash + +# Sync API OpenAPI Specification to Documentation +# This script copies the OpenAPI spec from the API source to the docs folder + +set -e + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +# Paths +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +API_SPEC_SOURCE="$PROJECT_ROOT/api/src/backend/api/specs/v1.yaml" +API_SPEC_DEST="$SCRIPT_DIR/api-reference/openapi.yaml" + +echo "🔄 Syncing API specification to documentation..." + +# Check if source file exists +if [ ! -f "$API_SPEC_SOURCE" ]; then + echo -e "${RED}❌ Error: Source API spec not found at $API_SPEC_SOURCE${NC}" + exit 1 +fi + +# Check if destination directory exists +if [ ! -d "$(dirname "$API_SPEC_DEST")" ]; then + echo -e "${YELLOW}⚠️ Creating destination directory...${NC}" + mkdir -p "$(dirname "$API_SPEC_DEST")" +fi + +# Check if files are different +if [ -f "$API_SPEC_DEST" ]; then + if cmp -s "$API_SPEC_SOURCE" "$API_SPEC_DEST"; then + echo -e "${GREEN}✅ API spec is already up to date!${NC}" + exit 0 + else + echo -e "${YELLOW}⚠️ API spec has changes, updating...${NC}" + fi +fi + +# Copy the file +if cp "$API_SPEC_SOURCE" "$API_SPEC_DEST"; then + echo -e "${GREEN}✅ API specification synced successfully!${NC}" + echo " Source: $API_SPEC_SOURCE" + echo " Destination: $API_SPEC_DEST" + + # Extract version from the spec + VERSION=$(grep -m 1 "version:" "$API_SPEC_DEST" | sed 's/.*version: //') + echo -e "${GREEN} Version: $VERSION${NC}" +else + echo -e "${RED}❌ Error: Failed to sync API specification${NC}" + exit 1 +fi + +echo "" +echo "💡 Next steps:" +echo " 1. Review the changes: git diff docs/api-reference/openapi.yaml" +echo " 2. Test locally: cd docs && mintlify dev" +echo " 3. Commit the changes if everything looks good"