Trigger Analysis Partner Account
This API supports several use cases where partners want to trigger analysis of an account's IAM configuration:
- Assess IAM security as part of a partner-led AWS security audit or to generate leads for IAM improvement projects
- Integrate IAM governance workflows into their own Cloud & Security products
You can trigger an analysis for a partner-managed account using the k9 API with:
POST /partner/{partner_id}/customer/{partner_customer_id}/account/{account_id}/analysis
To simplify adoption, this API only requires information the partner already has so that the partner does not need to, e.g. maintain a mapping of the partner's Customer ID to the k9 Customer ID. Additionally, you can audit accounts using your existing access to the target cloud account by providing a credential to the API (details).
When you successfully trigger an account analysis, k9 will immediately return an execution id. k9 will deliver the analysis to the secure inbox configured for the partner or customer account once it is complete. An incremental analysis generally takes at least 10 minutes for small accounts and up to 2 hours for large accounts.
Request Headers
Set the Content-Type
header to application/json
Request Path Parameters
The account analysis API requires three path parameters:
partner_id
: 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}
partner_customer_id
: 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}
account_id
: the AWS account ID to analyze, e.g. 123456789012
Type: String
Pattern: [\d]{12}
Request Body
Authenticate with the configured authentication method
When relying on a previously-configured config
or cvs
auditor authentication method, populate the request body with a json
document like:
{
"partnerId": "{partner_id}",
"partnerCustomerId": "{partner_customer_id}",
"accountId": "{account_id}"
}
Authenticate with your own credential
You can provide your own credential for k9 to audit the account by populating the request body with a json
document like:
{
"partnerId": "{partner_id}",
"partnerCustomerId": "{partner_customer_id}",
"accountId": "{account_id}",
"auditorAuthMethod": "credential",
"auditorAuthCredential": {
"provider": "aws",
"type": "credential_sts",
"details": {
"accessKey": "AKIA_EXAMPLE",
"secretKey": "xlCs_EXAMPLE",
"sessionToken": "a32gh_EXAMPLE",
"expiration": "2025-04-10T12:34:56.789Z",
"arn": "arn:aws:sts::123456789012:assumed-role/auditor/iam-audit"
}
}
}
The big advantage of this approach is that you can audit the account using your existing access and have full control of the session's permissions (k9 needs a subset of the SecurityAudit AWS managed policy). You can set the session duration to as low as 15 minutes.
Note: When the Trigger API receives a request with a credential, k9 encrypts the credential using AES-256 with an envelope encryption scheme and encryption context that includes the unique audit execution ID as additional authentication data. The encrypted credential is deleted after retrieving the account's configuration metadata.
To supply your own credential, you must specify the following members:
auditorAuthMethod
: is the auditor authentication method to use for the analysis; the value should be credential
when using your own credential
auditorAuthCredential
: The auditorAuthCredential
data structure contains three required members:
provider
: the cloud platform instance; supported values:aws
,aws-us-gov
type
: the type of credential contained in details; supported values:credential_sts
details
: the actual details of the credential, which are specific to the cloud platform.
auditorAuthCredential
details for an STS credential
The details member of an auditorAuthCredential
for the credential_sts
type maps the
AWS STS token data members and the assumed role's ARN:
accessKey
: The access key ID that identifies the temporary security credentials.secretKey
: The secret access key that can be used to sign requests.sessionToken
: The token that users must pass to the service API to use the temporary credentials.expiration
: The date on which the current credentials expire.arn
: The ARN of the STS session for the assumed role
Response
Success
When you successfully trigger an account analysis, the API will respond with:
Response Status Code: 202 (Accepted)
Response Body (Example):
{
"partnerId": "{partner_id}",
"partnerCustomerId": "{partner_customer_id}",
"customerId": "{customer_id}",
"accountId": "{account_id}",
"executionId": "ondemand-{customer_id}-{account_id}-{START_YYYY-MM-DD}_{RANDSTR}"
}
The response contains information confirming the analysis request was accepted.
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
The executionId
is a token the caller can use to identify this analysis. The executionId
is meant to be opaque to machines, but useful to people. It identifies the analysis' k9 Customer ID, AWS account ID, the date the analysis was started (UTC), and a random 4-character suffix.
Example executionId
: ondemand-P123456-430363089266-123456789012-2022-11-11_ONO2
.
Not Authorized
If the calling principal is not authorized to trigger an analysis, the API will respond with:
Response Status Code: 403 (Forbidden)
Response Body (Example):
{
"message": "Caller is not authorized to trigger analysis for k9 partnerId (P123456) and partnerCustomerId (550e8400-e29b-41d4-a716-446655440000)"
}