Skip to content

Configure Monitoring for Partner Account

Note: This is a draft API and is subject to change.

Partners can create or update a k9 customer account monitoring configuration using the k9 API with:

PUT /partner/{partnerId}/customer/{partnerCustomerId}/account/{accountId}

When you successfully store an account configuration, the account will be included in k9 Security's daily analysis. You can also trigger an analysis of the account for immediate execution.

Request Headers

Set the Content-Type header to application/json

Request Path Parameters

The create account configuration API requires three path parameters:

partnerId: the k9 Partner ID that manages the account to analyze, e.g. P123456. k9 Security will provide the Partner ID to the partner.

Type: String

Pattern: P[\d]{6}

partnerCustomerId: the partner's own unique customer or tenant identifier for the managed customer environment, e.g. a UUID, AWS Organization ID, SHA256 digest

Type: String

Pattern: [\w-_.]{6,64}

accountId: the AWS account ID to configure monitoring for, e.g. 123456789012

Type: String

Pattern: [\d]{12}

Request Body

Populate the request body with a json document specifying auditor principal configuration information like:

{
  "partnerId": "P123456",
  "partnerCustomerId": "abcd-1234-defg-5678",
  "accountId": "123456789012",
  "provider": "aws",
  "auditorAuthMethod": "config",
  "auditorAuthConfig": {
    "roleArn": "arn:aws:iam::123456789012:role/k9-auditor",
    "externalId": "EXAMPLE-EXTERNAL-ID-1234"
  }
}

Alternatively, specify that k9 will use a credential vending service to authenticate to the account:

{
  "partnerId": "P123456",
  "partnerCustomerId": "abcd-1234-defg-5678",
  "accountId": "234567890123",
  "provider": "aws-us-gov",
  "auditorAuthMethod": "cvs"
}

Request Body Elements

The request body contains several elements:

partnerId: (required) the k9 Partner ID; same as defined in the request path

partnerCustomerId: (required) the Partner's unique identifier for the customer; same as defined in the request path

accountId: (required) the AWS account ID to monitor; same as defined in the request path

provider: (required) the cloud service provider instance the account is part of, allowed values: aws, aws-us-gov

auditorAuthMethod: (required) the method k9 should use to authenticate the auditor, allowed values: config, cvs; the cvs method is only available for OEM integrations

auditorAuthConfig: (optional) the auditor principal and supporting configuration to use when auditing the monitored account

For AWS, the auditorAuthConfig configuration object should contain:

  • roleArn: (required) the ARN of the IAM role principal to use to audit the account
  • externalId: (required) the external ID to use when assuming the auditor role

Response

Success

When you successfully store an account configuration, the API will respond with:

Response Status Code: 200 (Success)

Response Body (Example):

{
  "partnerId": "P123456",
  "partnerCustomerId": "abcd-1234-defg-5678",
  "customerId": "P123456-430363089266",
  "provider": "aws",
  "accountId": "123456789012"
}

The customerId is the automatically managed k9 Customer ID that the partner's Customer ID is mapped to within k9. The customerId for partner-managed accounts has the form {partner_id}-{12-digit zero-padded number}

Example customerId: P123456-430363089266

Not Authorized

If the calling principal is not authorized to create the account configuration, the API will respond with:

Response Status Code: 403 (Forbidden)

Response Body (Example):

{
  "message": "Caller is not authorized to create the account configuration."
}

Last update: May 20, 2024