Welcome to the reference documentation for the public APIs (v4) available for InsightCloudSec.
Here are a few resources to help start using our APIs:
After you’ve got the basics down, you can effectively interact with the sample requests and responses found in this file.
```yaml # InsightCloudSec API # Version: v4Welcome to the reference documentation for the public APIs (v4) available for InsightCloudSec.
Here are a few resources to help start using our APIs:
After you’ve got the basics down, you can effectively interact with the sample requests and responses found in this file.
# Base URL: https://{insightcloudsecUrl}/v4 ``` -------------------------------- ### GET /configs/aws/roles Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Lists existing AWS role configurations. ```markdown ### Parameters - **source_accounts** (string, query, optional): Comma-delimited list of AWS account IDs. - **page** (integer (int32), query, optional): The page number for the list of results to return. Must be positive. - **page_size** (integer (int32), query, optional): The size of the page for the list of results. Must be positive. ### Responses #### 200 - 200 #### 400 - 400 ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/configs/aws/roles?source_accounts=string&page=0&page_size=0" ``` ``` -------------------------------- ### GET /configs/aws/accesskeys Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Lists existing AWS Access Keys. ```markdown ### Parameters - **include_session** (string, query, optional): Set to `true` to return long term *and* temporary STS AssumeRole session access keys. - **source_accounts** (string, query, optional): Comma-delimited list of AWS account IDs. - **page** (integer (int32), query, optional): The page number for the list of results to return. Must be positive. - **page_size** (integer (int32), query, optional): The size of the page for the list of results. Must be positive. ### Responses #### 200 - 200 - **total_count** (integer) (example: 1) - **page_size** (integer) (example: 1) - **data** (array (object)) Array items: - **arn** (string) (example: "arn:partition:service:region:account-id:resource-id") - **account_id** (string) (example: "1234-5678-9012") - **expiration** (string) (example: "2022-10-31T12:00:00Z") - **is_session** (boolean) (example: false) - **id** (integer) (example: 1234567890) - **region_name** (string) (example: "us-east-1") - **organization_id** (integer) (example: 1234567890) - **unique_id** (string) (example: "1234-abcd-5678-efgh") - **aws_access_key_id** (string) (example: "1234abc5-123a-12ab-123a-12a34bcd5678") - **total_pages** (integer) (example: 1) - **page** (integer) (example: 1) #### 400 - 400 ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/configs/aws/accesskeys?include_session=false&source_accounts=string&page=0&page_size=0" ``` ``` -------------------------------- ### GET /insights/findings-per-cloud/{organization_service_id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Get Insight findings for a given Cloud Account. ```markdown ### Parameters - **organization_service_id** (integer (int32), path, required): The InsightCloudSec ID for the Cloud Account. - **cursor** (string, query, optional): The hash value for the next page of results. This value can be obtained from the `next_cursor` parameter in the response object if there are more results that match a successful request. This process can be repeated until the `next_cursor` response parameter is null. ### Responses #### 200 - 200 #### 400 - 400 ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/insights/findings-per-cloud/{organization_service_id}?cursor=string" ``` ``` -------------------------------- ### GET /iac/scans Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml retrieve a list of IaC scan ids ```markdown ### Parameters - **page_size** (integer, query, optional) - **sort** (string (id|create_time), query, optional) - **page** (integer, query, optional) - **sort_dir** (unknown, query, optional) ### Responses #### 200 - OK **ListScanResponse** - **page_size** (integer) (required) - **ids** (array (integer)) (required) - **total_pages** (integer) (required) - **total_count** (integer) (required) - **page** (integer) (required) ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/iac/scans?page_size=25&sort=create_time&page=1&sort_dir=desc" ``` ``` -------------------------------- ### GET /iac/scans/{scan_id}/report Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml API endpoint for GET /iac/scans/{scan_id}/report ```markdown ### Parameters - **scan_id** (string, path, required) ### Responses #### 200 - OK **SarifLog** - **$schema** (string) (required): The absolute URI of a JSON schema document for SARIF - **version** (string) (required): The version of the SARIF standard used - **runs** (array (object)) (required): A list of run objects (SARIF spec v2.1.0, 3.13.4). Each run contains metadata about a single run of an external IaC analysis tool and the results of that run ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/iac/scans/{scan_id}/report" ``` ``` -------------------------------- ### GET /configs/aws/accounts/{organization_service_id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Lists an existing AWS EKS harvesting account configuration. ```markdown ### Parameters - **organization_service_id** (integer (int32), path, required): The Organization Service ID. ### Responses #### 200 - 200 - **name** (string) (example: "my-ics-aws-acct") - **account_id** (string) (example: "1234-5678-9012") - **partition** (string) (example: "aws") - **default_sts_region_name** (string) (example: "us-east-1") - **aws_eks_role_config_id** (integer) (example: 1) - **cloud_type_id** (string) (example: "example-id") - **aws_role_config_id** (integer) (example: 1) #### 400 - 400 ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/configs/aws/accounts/{organization_service_id}" ``` ``` -------------------------------- ### GET /iac/scans/{scan_id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml returns a single IaC scan given a scan_id ```markdown ### Parameters - **scan_id** (string, path, required) ### Responses #### 200 - OK **GetScanResponse** - **drivers** (array (string)) (required) - **scan_target** (string) (required) - **config_id** (integer) - **id** (integer) (required) - **complete_time** (string (date-time)) - **create_time** (string (date-time)) (required) ### Example Usage ```bash curl -X GET "https://{insightcloudsecUrl}/v4/iac/scans/{scan_id}" ``` ``` -------------------------------- ### POST /configs/aws/roles Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Creates an AWS role configuration. ```markdown ### Request Body **Content-Type:** application/json - **role_arn** (string) (required): he Amazon Resource Name (ARN) of the role to assume. - **duration_seconds** (integer (int32)): The duration, in seconds, of the role session. InsightCloudSec highly recommends using exactly 3600 seconds. The value specified can range from 900 seconds (15 minutes) up to the maximum session duration set for the role. However, most `AssumeRole` operations are cross-account and are restricted to 3600 seconds. - **session_name** (string) (required): An identifier for the assumed role session. - **external_id** (string) (required): A unique identifier that required when you assume a role in another account. InsightCloudSec requires a unique external ID for all IAM `AssumeRole` operations. This ID has been auto-generated for this InsightCloudSec Organization in accordance to AWS best practices. - **region_name** (string) (required): AWS region name. This represents the AWS partition where the Access Key was created and is used as the default region for STS operations. - **access_key_id** (integer (int32)): When `AssumeRole` cannot be done via a Trusted Role, provide an InsightCloudSec the integer ID of a saved IAM Access Key. ### Responses #### 201 - 201 #### 400 - 400 ### Example Usage ```bash curl -X POST "https://{insightcloudsecUrl}/v4/configs/aws/roles" \ -H "Content-Type: application/json" \ -d '{ "role_arn": "string", "duration_seconds": "3600", "session_name": "string", "external_id": "string", "region_name": "string", "access_key_id": "0" }' ``` ``` -------------------------------- ### POST /configs/aws/accesskeys Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Creates a new AWS IAM Access Key. ```markdown ### Request Body **Content-Type:** application/json - **region_name** (string) (required): AWS region name. This represents the AWS partition where the Access Key was created and is used as the default region for STS operations. - **aws_access_key_id** (string) (required): The ID for the AWS Access Key. Review the [AWS Access Key documentation](https://docs.aws.amazon.com/IAM/latest/APIReference/welcome.html) for more information. - **aws_secret_access_key** (string) (required): The value for the AWS Secret Access Key. Review the [AWS Access Key documentation](https://docs.aws.amazon.com/IAM/latest/APIReference/welcome.html) for more information. ### Responses #### 201 - 201 - **arn** (string) (example: "arn:partition:service:region:account-id:resource-id") - **account_id** (string) (example: "1234-5678-9012") - **expiration** (string) (example: "2022-10-31T12:00:00Z") - **is_session** (boolean) (example: false) - **id** (integer) (example: 1234567890) - **region_name** (string) (example: "us-east-1") - **organization_id** (integer) (example: 1234567890) - **unique_id** (string) (example: "1234-abcd-5678-efgh") - **aws_access_key_id** (string) (example: "1234abc5-123a-12ab-123a-12a34bcd5678") #### 400 - 400 ### Example Usage ```bash curl -X POST "https://{insightcloudsecUrl}/v4/configs/aws/accesskeys" \ -H "Content-Type: application/json" \ -d '{ "region_name": "string", "aws_access_key_id": "string", "aws_secret_access_key": "string" }' ``` ``` -------------------------------- ### Schema: SarifLog Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Schema definition for SarifLog ```markdown ## Schema: SarifLog Schema definition for SarifLog **Type:** object - **$schema** (string) (required): The absolute URI of a JSON schema document for SARIF - **version** (string) (required): The version of the SARIF standard used - **runs** (array (object)) (required): A list of run objects (SARIF spec v2.1.0, 3.13.4). Each run contains metadata about a single run of an external IaC analysis tool and the results of that run ``` -------------------------------- ### Security: Api-Key Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Requests to this API require an [API key](https://docs.rapid7.com/insightcloudsec/api-documentation#authentication) passed through the `Api-Key` header. For more information on security and access within InsightCloudSec, see [Users, Groups and Roles](https://docs.rapid7.com/insightcloudsec/user-roles). ```markdown ## Security: Api-Key **Description:** Requests to this API require an [API key](https://docs.rapid7.com/insightcloudsec/api-documentation#authentication) passed through the `Api-Key` header. For more information on security and access within InsightCloudSec, see [Users, Groups and Roles](https://docs.rapid7.com/insightcloudsec/user-roles). **Type:** apiKey ``` -------------------------------- ### Schema: ListScanResponse Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Schema definition for ListScanResponse ```markdown ## Schema: ListScanResponse Schema definition for ListScanResponse **Type:** object - **page_size** (integer) (required) - **ids** (array (integer)) (required) - **total_pages** (integer) (required) - **total_count** (integer) (required) - **page** (integer) (required) ``` -------------------------------- ### Schema: GetScanResponse Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Schema definition for GetScanResponse ```markdown ## Schema: GetScanResponse Schema definition for GetScanResponse **Type:** object - **drivers** (array (string)) (required) - **scan_target** (string) (required) - **config_id** (integer) - **id** (integer) (required) - **complete_time** (string (date-time)) - **create_time** (string (date-time)) (required) ``` -------------------------------- ### POST /configs/aws/roles/{id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Updates an existing AWS role configuration. ```markdown ### Parameters - **id** (integer (int32), path, required): The AWS Scanner role configuration ID. ### Request Body **Content-Type:** application/json - **role_arn** (string) (required): The Amazon Resource Name (ARN) of the role to assume. - **duration_seconds** (integer (int32)): The duration, in seconds, of the role session. InsightCloudSec highly recommends using exactly 3600 seconds. The value specified can range from 900 seconds (15 minutes) up to the maximum session duration set for the role. However, most `AssumeRole` operations are cross-account and are restricted to 3600 seconds. - **session_name** (string) (required): An identifier for the assumed role session. - **external_id** (string) (required): A unique identifier that required when you assume a role in another account. InsightCloudSec requires a unique external ID for all IAM `AssumeRole` operations. This ID has been auto-generated for this InsightCloudSec Organization in accordance to AWS best practices. - **region_name** (string) (required): AWS region name. This represents the AWS partition where the Access Key was created and is used as the default region for STS operations. - **access_key_id** (integer (int32)): When `AssumeRole` cannot be done via a Trusted Role, provide an InsightCloudSec the integer ID of a saved IAM Access Key. ### Responses #### 200 - 200 #### 400 - 400 ### Example Usage ```bash curl -X POST "https://{insightcloudsecUrl}/v4/configs/aws/roles/{id}" \ -H "Content-Type: application/json" \ -d '{ "role_arn": "string", "duration_seconds": "3600", "session_name": "string", "external_id": "string", "region_name": "string", "access_key_id": "0" }' ``` ``` -------------------------------- ### POST /configs/aws/accounts/{organization_service_id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Updates an existing AWS EKS harvesting account configuration. ```markdown ### Parameters - **organization_service_id** (integer (int32), path, required): The Organization Service ID. ### Request Body **Content-Type:** application/json - **name** (string) (required): AWS account name. - **aws_role_config_id** (integer (int32)) (required): `AwsIamRoleConfig` ID to be used for general purpose API harvesting. Role must be within the same AWS partition and account. - **aws_eks_role_config_id** (integer (int32)) (required): `AwsIamRoleConfig` ID to be used as the default role for harvesting EKS clusters. Role must be within the same AWS partition and account. ### Responses #### 200 - 200 - **name** (string) (example: "my-ics-aws-acct") - **account_id** (string) (example: "1234-5678-9012") - **partition** (string) (example: "aws") - **default_sts_region_name** (string) (example: "us-east-1") - **aws_eks_role_config_id** (integer) (example: 1) - **cloud_type_id** (string) (example: "example-id") - **aws_role_config_id** (integer) (example: 1) #### 400 - 400 ### Example Usage ```bash curl -X POST "https://{insightcloudsecUrl}/v4/configs/aws/accounts/{organization_service_id}" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "aws_role_config_id": "0", "aws_eks_role_config_id": "0" }' ``` ``` -------------------------------- ### DELETE /configs/aws/accesskeys/{id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Deletes an existing AWS Access Key. ```markdown ### Parameters - **id** (integer (int32), path, required): Access Key Configuration ID. ### Responses #### 200 - 200 #### 400 - 400 ### Example Usage ```bash curl -X DELETE "https://{insightcloudsecUrl}/v4/configs/aws/accesskeys/{id}" ``` ``` -------------------------------- ### DELETE /configs/aws/roles/{id} Source: https://docs.rapid7.com/_api/insightcloudsec-v4-api.yaml Deletes an existing AWS Scanner role configuration. ```markdown ### Parameters - **id** (integer (int32), path, required): The AWS Scanner Role configuration ID. ### Responses #### 200 - 200 #### 400 - 400 ### Example Usage ```bash curl -X DELETE "https://{insightcloudsecUrl}/v4/configs/aws/roles/{id}" ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.