CyCognito Cloud Connectors API
The Cloud Connectors API from CyCognito — 4 operation(s) for cloud connectors.
OpenAPI Specification
openapi: 3.0.3
info:
version: 0.0.1
title: CyCognito API V1 Reference Assets Cloud Connectors API
description: 'The CyCognito API V1 is a REST API that allows you to post and get data from our main data entities—assets and issues. You can also manage the scope of your attack surface, attribute assets to organizations, and verify the identity of IP scans on your assets. Our legacy API (V0) documentation is available for download [here](https://platform.cycognito.com/CyCognito-API-V0-Reference.pdf). While V0 is still being supported, please note that this API is undergoing deprecation.
| Code | Name | Description |
|------|------|-------------|
| 200 | OK | Success |
| 400 | Bad Request | The request is malformed—e.g., the body cannot be properly parsed, expected fields are not included in the body, or unsupported request header values. |
| 403 | Access Restricted | There are insufficient permissions or a valid API key was not provided. |
| 404 | Not Found | The provided resource was not found. |
| 405 | Method Not Allowed | The HTTP method is not allowed for the given resource. |
| 415 | Unsupported Media Type | The request content type is not supported. |
| 5XX | | Server failure | |
'
tags:
- name: Cloud Connectors
paths:
/v1/cloud-environments:
get:
description: Retrieve a list of cloud environments.
security:
- apiAuth: []
summary: Retrieve multiple cloud environment data
tags:
- Cloud Connectors
responses:
'200':
content:
application/json:
schema:
anyOf:
- type: array
items:
type: object
properties:
id:
description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix.
type: string
example: 12312-3213-12341
test-status:
description: Indicates whether the connector was configured correctly or not.
type: string
example: Success
provider:
description: The name of the cloud service provider (e.g., AWS). **Note:** Currently only AWS is supported.
type: string
enum:
- AWS
- Azure
- GCP
- Cloudflare
- WIZ
example: AWS
cloud-env-name:
description: A name used solely for identifying the cloud connector and the environment connected to it.
type: string
example: Acme AWS cloud environment
required:
- id
- test-status
- provider
- cloud-env-name
- type: object
properties:
exception:
description: Indicates whether the specified cloud environment exists or not.
type: string
required:
- exception
post:
description: Create a new cloud environment for the specified provider. **Note:** This endpoint currently only supports setting up connectors for single AWS accounts. The accompanying YAML script can be downloaded via the link generated by the *Get YAML for AWS* API endpoint.
security:
- apiAuth: []
summary: Add new AWS connector
tags:
- Cloud Connectors
requestBody:
content:
application/json:
schema:
type: object
properties:
connector-name:
description: 'A name used solely for identifying the cloud connector and the environment connected to it. It is recommended to provide a unique name which helps identify the cloud environment to which it is connected. Cloud connector names are limited to 50 characters, and may contain only alphanumeric characters and the following special characters: `-_()[]`'
type: string
organization-attribution:
description: The name of the organization that all cloud-fetched assets will be attributed to.
type: string
provider:
description: The name of the cloud service provider (i.e., AWS).
type: string
enum:
- aws
provider-details:
description: Details specific to the provider.
type: object
properties:
account-id:
description: Your AWS account ID. Learn how to find this 12-digit number by reading the <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html#FindingYourAWSId">AWS documentation</a>.
type: string
arn:
description: 'The Amazon Resource Name (ARN). The formatted [ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) will look like: `arn:aws:iam::123456789012:role/CyCognitoCloudConnector-a123b4567c`.'
type: string
required:
- account-id
- arn
required:
- connector-name
- organization-attribution
- provider
- provider-details
example: "{\n \"connector-name\": \"Acme AWS Cloud Environment\",\n \"organization-attribution\": \"Acme Corporation\",\n \"provider\": \"aws\",\n \"provider-details\": {\n \"account-id\": \"123456789012\",\n \"arn\": \"arn:aws:iam::123456789012:role/CyCognitoCloudConnector-a123b4567c\"\n }\n}"
responses:
'200':
content:
application/json:
schema:
anyOf:
- type: object
properties:
cloud-env-id:
description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`).
type: string
required:
- cloud-env-id
- type: object
properties:
error:
description: A message describing the reason for the failure.
type: string
required:
- error
/v1/cloud-environments/script:
post:
description: Generate the YAML script required for creating new AWS connectors.
security:
- apiAuth: []
summary: Get YAML for AWS
tags:
- Cloud Connectors
requestBody:
content:
application/json:
schema:
type: object
properties:
provider:
description: The name of the cloud service provider (i.e., AWS).
type: string
enum:
- aws
privilege:
description: Determines the permission level granted to the Connector ('regular' or 'least').
type: string
enum:
- regular
- least
required:
- provider
- privilege
responses:
'200': {}
/v1/cloud-environments/{cloud-env-id}:
get:
description: Fetch data for a single cloud environment.
security:
- apiAuth: []
summary: Retrieve single cloud environment data
tags:
- Cloud Connectors
parameters:
- name: cloud-env-id
in: path
schema:
type: string
required: true
description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`).
responses:
'200':
content:
application/json:
schema:
anyOf:
- type: object
properties:
id:
description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix.
type: string
example: 12312-3213-12341
test-status:
description: Indicates whether the connector was configured correctly or not.
type: string
example: Success
provider:
description: The name of the cloud service provider (e.g., AWS). **Note:** Currently only AWS is supported.
type: string
enum:
- AWS
- Azure
- GCP
- Cloudflare
- WIZ
example: AWS
cloud-env-name:
description: A name used solely for identifying the cloud connector and the environment connected to it.
type: string
example: Acme AWS cloud environment
required:
- id
- test-status
- provider
- cloud-env-name
- type: object
properties:
exception:
description: Indicates whether the specified cloud environment exists or not.
type: string
required:
- exception
/v1/cloud-environments/{cloud-env-id}/test-connector:
put:
description: Trigger a test to determine whether the specified cloud connector is configured correctly.
security:
- apiAuth: []
summary: Test connector
tags:
- Cloud Connectors
parameters:
- name: cloud-env-id
in: path
schema:
type: string
required: true
description: A unique identifier for the cloud environment. This ID can be extrapolated from the `cloud-env-id` field (from the *Add new connector* response) by removing the `cloud-env/` prefix (e.g., `12312-3213-12341`).
responses:
'200':
content:
application/json:
schema:
type: object
properties:
message:
description: A message indicating the result of the test.
type: string
example: Cloud environment test completed successfully.
status:
description: The status of the test, either *completed* or *failed*.
type: string
enum:
- completed
- failed
example: completed
required:
- message
- status
components:
securitySchemes:
apiAuth:
type: apiKey
name: Authorization
in: header