AWS IAM

LAST UPDATED: 06/06/2024

Overview

AWS Identity and Access Management (IAM) is a web service for securely controlling access to AWS services. With IAM, you can centrally manage users, security credentials such as access keys, and permissions that control which AWS resources users and applications can access.

D3 SOAR is providing REST operations to function with AWS IAM.

AWS IAM is available for use in:

D3 SOAR	V14.7.12+
Category	Identity Access Management
Deployment Options	Option II, Option IV

Known Limitations

AWS Identity and Access Management (IAM) has quotas that limit the size of objects. This affects how you name an object, the number of objects you can create, and the number of characters you can use when you pass an object.

Please refer to the IAM and AWS STS quotas, name requirements, and character limits for detailed information.

Connection

To connect to AWS IAM from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Access Key	The access key for authentication. Please check the Policy Permission for this access key or role (if roleArn is specified) in the AWS Management Console and ensure that this access key includes ListRoles, ListPolicies, ListRolePolicies, GetRole, GetRolePolicy, ListEntitiesForPolicy, AttachRolePolicy, DetachRolePolicy, ListAttachedRolePolicies, GetPolicy, GetPolicyVersion and ListPoilcyVersions permissions. The following are required permissions for each command: Test Connection (ListRoles), List Roles (ListRoles), List Policies (ListPolicies), List Role Policies (ListRolePolicies), Get IAM Role (GetRole), Get Role Policy (GetRolePolicy), List Entities For Policy (ListEntitiesForPolicy), Attach Role Policy (AttachRolePolicy), Get Bucket Policy (GetBucketPolicy), Detach Role Policy (DetachRolePolicy), Get Policy (GetPolicy), Get Policy Version (GetPolicyVersion), List Policy Versions (ListPolicyVersions).	AKIAxxxxxxxxxxxx4CYL
Secret Key	The secret key for authentication.	Xdwchs**E8vjHyIx9x6iPuWdX**DXSdH
Default Role ARN	The Amazon Resource Name (ARN) of the role to assume. Role ARN can be obtained from AWS IAM GUI. Please ensure the role you assume has permission to run related commands. Additionally, the role you assume must trust the account which you are using to connect. Please refer to Editing the trust relationship for an existing role.	arn:aws:iam::391****688:role/d3*role
Default Role Session Name	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If the Role Session Name parameter is not specified, but the Default Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Default Session Duration Time	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified, then the default value of 3600 seconds will be used.	1800

Permission Requirements

Each endpoint in the AWS IAM API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Policy
Command	Service	Access level (Actions)
Attach Role Policy	IAM	AttachRolePolicy
Detach Role Policy	IAM	DetachRolePolicy
Get IAM Role	IAM	GetRole
Get Policy	IAM	GetPolicy
Get Policy Version	IAM	GetPolicyVersion
Get Role Policy	IAM	GetRolePolicy
List Attached Role Policies	IAM	ListAttachedRolePolicies
List Entities For Policy	IAM	ListEntitiesForPolicy
List Managed Policies	IAM	ListPolicies
List Policy Versions	IAM	ListPolicyVersions
List Role Policies	IAM	ListRolePolicies
List Roles	IAM	ListRoles
Test Connection	IAM	ListRoles

Configuring AWS IAM to Work with D3 SOAR

If your login user is ready to use (no policy configure needed), please follow the steps below to get your access key and secret key.

If you want to configure an account with limited API access, please follow the Create Policy > Create User > Access Key and Secret Key to get keys.

Sign in to the AWS console with your account credentials.
Click the account icon at the top right corner, then click Security Credentials.

On my security credentials page, under the AWS IAM credentials tab, click the button Create access key to create a new Access Key and Secret Key.

READER NOTE

If you do not have permission to read or create an access key, please ask your administrator for help.

Copy the Access key ID and the Secret access key to use to connect with D3 SOAR.

READER NOTE

The secret access key can only be viewed or downloaded at this time. It is recommended that you promptly download the .csv file and securely store it for future reference. If you lose or forget your secret key, you will not be able to recover it. If you have lost your secret key, you will need to create a new access key and deactivate the old key. You can have a maximum of two access keys (active or inactive) at a time.

Creating Policy

Click on Services, which will expand the navigation menu. Then select IAM.
Select Access management, which will open a menu where you can select Policies. Then, click the Create Policy button.
In the Select a service section, click on Service to Choose a service. Please refer to Permission Requirements for the service you have selected. Then click Next.
Search and assign using the search box in the Actions allowed section. For example, search for ListRoles in the search box, and use the tick box underneath it to select this action. Please refer to Permission Requirements for the necessary Access level (Actions). It is possible to specify multiple permissions under the same policy. Then click Next.
Type a name in the text box under Policy name. Click Create policy.

Creating User

Locate the Users tab.
Type a user name into the User details field, then click Next.
Select your desired permissions under Permissions options. It is suggested to link directly to your created policy. Please refer to Creating Policy for more detailed information.
Alternatively, you may create a role with your desired permissions. Please refer to Adding a Role and Trusted Entities for creating user roles. Once the role is created, it is not required to assign the role directly to the user. Instead, you can assign the role through the D3 connection or D3 commands. Please refer to AssumeRole - AWS Security Token Service for more details.

Then click Next.

Review the details you have entered, and click Create user.

5. Find the user you just created. Copy the User ARN.

Adding a Role and Trusted Entities

Sign in to the AWS IAM console with your administrator credentials.
On the left side menu, click Roles and then click the Create role button at the top right.
Select AWS account under Trusted entity type. Depending on your request, choose the appropriate account under An AWS account, then click Next.
Use the search box to search for the policy name. Add the required permissions by selecting the policy, then click Next.
Enter the Role name, and click Create role.
Find the role. Navigate to Roles, and select the role that you have just created. Click Create rule.
Navigate to Roles and select the tab Trust relationships. Click Edit trust policy.
Return to Edit trust policy that is opened in your other browser tab/window. Paste the following code to your trust policy. Then paste your copied user ARN (please refer to step 5 of Creating User for getting user ARN) to the "AWS" field in the code. Click Update policy.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::******:user/DOC_User",
"Service": "iam.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

The Role ARN is ready to use.

Access Key and Secret Key

Find the user you have created, and click on your user to access the details.
Under the Security credentials tab, click on Create access key.
Create an access key and save the details. Click Done after saving these credentials.

READER NOTE

The secret access key can only be viewed or downloaded at this time. It is recommended that you promptly download the .csv file and securely store it for future reference. If you lose or forget your secret key, you will not be able to recover it. If you have lost your secret key, you will need to create a new access key and deactivate the old key. You can have a maximum of two access keys (active or inactive) at a time.

Configuring D3 SOAR to Work with AWS IAM

Log in to D3 SOAR.
Find the AWS IAM integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type AWS IAM in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to AWS IAM.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Access Key obtained from the AWS IAM platform in step 4 of Configuring AWS IAM to Work with D3 SOAR.
  2. Input the Secret Key obtained from the AWS IAM platform in step 4 of Configuring AWS IAM to Work with D3 SOAR.
  3. (Optional) Input the Default Role ARN obtained from the AWS IAM platform in step 9 of Adding a Role and Trusted Entities.
  4. (Optional) Input the Default Role Session Name.
  5. (Optional) Input the Default Session Duration Time. The default value is 3,600.
10. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

AWS IAM includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the AWS IAM API, please refer to the AWS IAM API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring AWS IAM to Work with D3 SOAR for details.

Attach Role Policy

Attaches the specified managed policy to the specified IAM role. When a managed policy is attached to a role, the managed policy becomes part of the role's permission (access) policy.

READER NOTE

Role Name and Policy Arn are required parameters to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.
Run the List Policies command to obtain Policy Arn. Policy Arns can be found in the raw data at the path $.Policies[*].Arn.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name (not ARN) of the role to attach the managed policy to. Role Name can be obtained using the List Roles command.	d3_test
Policy Arn	Required	The Amazon Resource Name (ARN) of the IAM managed policy you want to attach. Policy Arn can be obtained using the List Policies command.	arn:aws:iam::aws:policy/********
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "AttachedPolicies": [
        {
            "PolicyName": "AmazonEC2FullAccess",
            "PolicyArn": "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
        },
        {
            "PolicyName": "AmazonEC2ContainerRegistryReadOnly",
            "PolicyArn": "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
        },
        {
            "PolicyName": "CastleTest",
            "PolicyArn": "arn:aws:iam::391******688:policy/CastleTest"
        },
        {
            "PolicyName": "AccessAnalysis",
            "PolicyArn": "arn:aws:iam::391******688:policy/AccessAnalysis"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "81f****************a50",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "81f****************a50",
            "content-type": "text/xml",
            "content-length": "1039",
            "date": "Tue, 07 Jun 2022 00:06:17 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "PolicyNames": [
        "AmazonEC2ContainerRegistryReadOnly"
    ],
    "PolicyARNs": [
        "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Attach Role Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 5, valid min length: 20.

Error Sample Data

Attach Role Policy failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 5, valid min length: 20.

Detach Role Policy

Removes the specified managed policy from the specified role.

READER NOTE

Role Name and Policy Arn are required parameters to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.
Run the List Policies command to obtain Policy Arn. Policy Arns can be found in the raw data at the path $.Policies[*].Arn.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name (not ARN) of the role to detach the policy from. Role Name can be obtained using the List Roles command.	d3_test
Policy Arn	Required	The Amazon Resource Name (ARN) of the IAM managed policy you want to detach. Policy Arn can be obtained using the List Policies command.	arn:aws:iam::aws:policy/********
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, then use the value of the connection parameter Default Role ARN. Please note: Please ensure the role you assume has permission to run related commands. Additionally, the role assumed must trust the account which you are using to connect. Please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "AttachedPolicies": [
        {
            "PolicyName": "AmazonEC2FullAccess",
            "PolicyArn": "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
        },
        {
            "PolicyName": "CastleTest",
            "PolicyArn": "arn:aws:iam::391******688:policy/CastleTest"
        },
        {
            "PolicyName": "AccessAnalysis",
            "PolicyArn": "arn:aws:iam::391******688:policy/AccessAnalysis"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "825****************a56",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "825****************a56",
            "content-type": "text/xml",
            "content-length": "850",
            "date": "Tue, 07 Jun 2022 00:44:53 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "PolicyNames": [
        "AmazonEC2FullAccess"
    ],
    "PolicyARNs": [
        "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Detach Role Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 5, valid min length: 20.

Error Sample Data

Detach Role Policy failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 5, valid min length: 20.

Get IAM Role

Retrieves information about the specified role.

READER NOTE

Role Name is a required parameter to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name (not ARN) of the IAM role to retrieve information about. Role Name can be obtained using the List Roles command.	D3_test
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, then use the value of the connection parameter Default Role ARN. Note:To assume a role, ensure the role you assume has permission to run related commands. Additionally, the role you assume must trust the account which you are using to connect. Please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Role": {
        "Path": "/",
        "RoleName": "d3_test",
        "RoleId": "ARO********SPN",
        "Arn": "arn:aws:iam::391******688:role/d3_test",
        "CreateDate": "2022-06-06 18:32:54+00:00",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "ec2.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                }
            ]
        },
        "Description": "Allows EC2 instances to call AWS services on your behalf.",
        "MaxSessionDuration": 3600,
        "RoleLastUsed": {}
    },
    "ResponseMetadata": {
        "RequestId": "794****************71e",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "794****************71e",
            "content-type": "text/xml",
            "content-length": "891",
            "date": "Mon, 06 Jun 2022 21:43:00 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RoleName": [
        "d3_test"
    ],
    "RoleID": [
        "ARO********SPN"
    ],
    "ARN": [
        "arn:aws:iam::391******688:role/d3_test"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get IAM Role failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: An error occurred (NoSuchEntity) when calling the GetRole operation: The role with name **** cannot be found.

Error Sample Data

Get IAM Role failed.

Status Code: 403.

Message: An error occurred (NoSuchEntity) when calling the GetRole operation: The role with name **** cannot be found.

Get Policy

Retrieves information about the specified managed policy, including the policy's default version and the total number of IAM users, groups, and roles to which the policy is attached. To retrieve the actual policy document, use the Get Policy Version command.

READER NOTE

Policy Arn is a required parameter to run this command.

Run the List Policies or List Attached Role commands to obtain Policy Arn. Policy Arns can be found in the raw data at the paths $.Policies[*].Arn and $.AttachedPolicies[*].PolicyArn, respectively.

Input

Input Parameter	Required/Optional	Description	Example
Policy Arn	Required	The Amazon Resource Name (ARN) of the managed policy to retrieve information about. Policy Arn can be obtained using the List Policies or List Attached Role commands.	arn:aws:iam::391******688:policy/CastleTest
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, then use the value of the connection parameter Default Role ARN. Note: Please ensure the role you assume has permission to run related commands. Additionally, the role assumed must trust the account which you are using to connect. Please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Policy": {
        "PolicyName": "CastleTest",
        "PolicyId": "ANP**********V3E",
        "Arn": "arn:aws:iam::391******688:policy/CastleTest",
        "Path": "/",
        "DefaultVersionId": "v3",
        "AttachmentCount": 2,
        "PermissionsBoundaryUsageCount": 0,
        "IsAttachable": true,
        "CreateDate": "2018-07-12 22:19:32+00:00",
        "UpdateDate": "2022-06-06 18:43:37+00:00",
        "Tags": []
    },
    "ResponseMetadata": {
        "RequestId": "05f****************9aa",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "05f****************9aa",
            "content-type": "text/xml",
            "content-length": "757",
            "date": "Thu, 09 Jun 2022 18:22:00 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "PolicyName": [
        "CastleTest"
    ],
    "PolicyID": [
        "ANP**********V3E"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

Error Sample Data

Get Policy failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

Get Policy Version

Retrieves information about the specified version of the specified managed policy, including the policy document.

READER NOTE

Policy Arn and Version ID are required parameters to run this command.

Run the List Policies or List Attached Roles Policies commands to obtain Policy Arn. Policy Arns can be found in the raw data at the paths $.Policies[*].Arn and $.AttachedPolicies[*].PolicyArn, respectively.
Run the List Policy Versions command to obtain Version ID. Version IDs can be found in the raw data at the path $.Versions[*].VersionId.

Input

Input Parameter	Required/Optional	Description	Example
Policy Arn	Required	The Amazon Resource Name (ARN) of the managed policy to retrieve information about the specified version. Policy Arn can be obtained using the List Policies and List Attached Role Policies commands.	arn:aws:iam::391******688:policy/CastleTest
Version ID	Required	The policy version to retrieve. This parameter allows a string of characters that consists of the lowercase letter 'v' followed by one or two digits, and optionally followed by a period '.' and a string of letters and digits. Version ID can be obtained using the List Policy Versions command.	V3
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "PolicyVersion": {
        "Document": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Sid": "Visual******0",
                    "Effect": "Allow",
                    "Action": "s3:ListBucket",
                    "Resource": "arn:aws:s3:::castletest"
                }
            ]
        },
        "VersionId": "v3",
        "IsDefaultVersion": true,
        "CreateDate": "2022-06-06 18:43:37+00:00"
    },
    "ResponseMetadata": {
        "RequestId": "77b****************066",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "77b****************066",
            "content-type": "text/xml",
            "content-length": "973",
            "date": "Thu, 09 Jun 2022 19:08:42 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "IsDefaultVersion": [
        "true"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Policy Version failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 5, valid min length: 20.

Error Sample Data

Get Policy Version failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 5, valid min length: 20.

Get Role Policy

Retrieves the specified inline policy document that is embedded with the specified IAM role.

READER NOTE

Role Name and Policy Name are required parameters to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.
Run the List Role Policies command to obtain Policy Name. Policy Names can be found in the raw data at the path $.PolicyNames.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name (not ARN) of the role associated with the inline policy. Role Name can be obtained using the List Roles command.	d3_test
Policy Name	Required	The name of the policy document to retrieve. Policy Name can be obtained using the List Role Policies command.	D3cloudwatchpolicy
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "RoleName": "d3_test",
    "PolicyName": "d3cloudwatchpolicy",
    "PolicyDocument": {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "Visual*******0",
                "Effect": "Allow",
                "Action": "cloudwatch:ListTagsForResource",
                "Resource": "arn:aws:cloudwatch:*:391******688:alarm:*"
            },
            {
                "Sid": "Visual*******1",
                "Effect": "Allow",
                "Action": [
                    "cloudwatch:ListMetricStreams",
                    "cloudwatch:ListDashboards",
                    "cloudwatch:ListMetrics"
                ],
                "Resource": "*"
            }
        ]
    },
    "ResponseMetadata": {
        "RequestId": "f53****************f79",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "f53****************f79",
            "content-type": "text/xml",
            "content-length": "1561",
            "date": "Mon, 06 Jun 2022 21:57:29 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RoleName": [
        "d3_test"
    ],
    "PolicyName": [
        "d3cloudwatchpolicy"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Role Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: An error occurred (NoSuchEntity) when calling the GetRolePolicy operation: The role with name **** cannot be found.'.

Error Sample Data

Get Role Policy failed.

Status Code: 403.

Message: An error occurred (NoSuchEntity) when calling the GetRolePolicy operation: The role with name **** cannot be found.'.

List Attached Role Policies

Lists all managed policies that are attached to the specified IAM role.

READER NOTE

Role Name is a required parameter to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name (not ARN) of the role for which to list attached policies. Role Name can be obtained using the List Roles command.	D3_test
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "AttachedPolicies": [
        {
            "PolicyName": "AmazonEC2FullAccess",
            "PolicyArn": "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
        },
        {
            "PolicyName": "AmazonEC2ContainerRegistryReadOnly",
            "PolicyArn": "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
        },
        {
            "PolicyName": "CastleTest",
            "PolicyArn": "arn:aws:iam::391******688:policy/CastleTest"
        },
        {
            "PolicyName": "AccessAnalysis",
            "PolicyArn": "arn:aws:iam::391******688:policy/AccessAnalysis"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "b99****************6fc",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "b99****************6fc",
            "content-type": "text/xml",
            "content-length": "1039",
            "date": "Mon, 06 Jun 2022 23:57:24 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "PolicyNames": [
        "AmazonEC2FullAccess"
    ],
    "PolicyARNs": [
        "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Attached Role Policies failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: An error occurred (NoSuchEntity) when calling the ListAttachedRolePolicies operation: The role with name **** cannot be found.

Error Sample Data

List Attached Role Policies failed.

Status Code: 403.

Message: An error occurred (NoSuchEntity) when calling the ListAttachedRolePolicies operation: The role with name **** cannot be found.

List Entities For Policy

Lists all IAM users, groups, and roles that the specified managed policy is attached to. Note: this command can be used to retrieve roles that are attached to a specified managed policy.

READER NOTE

Policy Arn is a required parameter to run this command.

Run the List Policies command to obtain Policy Arn. Policy Arns can be found in the raw data at the path $.Policies[*].Arn.

Input

Input Parameter	Required/Optional	Description	Example
Policy Arn	Required	The Amazon Resource Name (ARN) of the IAM managed policy to retrieve attached entities. Policy Arn can be obtained using the List Policies command.	arn:aws:iam::391******688:policy/AccessAnalysis
Entity Filter	Optional	The entity type used to filter results. For example, when this parameter is set to Role, only the roles attached to the specified policy are returned. This parameter is optional. If not specified, all attached entities (users, groups, and roles) are returned.	Role
Policy Usage Filter	Optional	The policy usage method for filtering the results. To list only permissions policies, set this parameter to Permissions Policy. To list only the policies used to set permissions boundaries, set it to Permissions Boundary. This parameter is optional. If not specified, all policy usage methods are returned.	Permissions Policy
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "PolicyGroups": [
        {
            "GroupName": "d3cyber",
            "GroupId": "AGP********WXU"
        }
    ],
    "PolicyUsers": [],
    "PolicyRoles": [
        {
            "RoleName": "d3_test",
            "RoleId": "ARO********SPN"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "50b****************4b4",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "50b****************4b4",
            "content-type": "text/xml",
            "content-length": "653",
            "date": "Mon, 06 Jun 2022 22:56:21 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RoleNames": [
        "d3_test"
    ],
    "RoleIDs": [
        "ARO********SPN"
    ],
    "UserNames":[],
    "UserIDs": [],
    "GroupNames": [
        "d3cyber"
    ],
    "GroupIDs": [
        "AGP********WXU"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Entities For Policy failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

Error Sample Data

List Entities For Policy failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

List Managed Policies

Lists all the managed policies that are available in your AWS account, including your own customer-defined managed policies and all AWS managed policies.

Input

Input Parameter	Required/Optional	Description	Example
Scope	Optional	The scope to use for filtering the results. To list only AWS managed policies, set Scope to AWS. To list only the customer managed policies in your AWS account, set Scope to Local. If the parameter is not specified, all policies will be returned.	Local
Only Attached	Optional	The flag to filter the results to only the attached policies. When Only Attached is true , the returned list contains only the managed policies that are attached to an IAM user, group, or role. When Only Attached is false , or when the parameter is not specified, all policies will be returned.	True
Policy Usage Filter	Optional	The policy usage method to use for filtering the results. To list only permissions policies, set Policy Usage Filter to Permissions Policy. To list only the policies used to set permissions boundaries, set the value to Permissions Boundary. If the parameter is not specified, all policies will be returned. Please note, this parameter is applicable when Only Attached parameter is set to True.	Permissions Policy
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Policies": [
        {
            "PolicyName": "AccessAnalyzerMonitorServicePolicy_L35****SQD",
            "PolicyId": "ANP**********DO3",
            "Arn": "arn:aws:iam::391******688:policy/service-role/AccessAnalyzerMonitorServicePolicy_L35****SQD",
            "Path": "/service-role/",
            "DefaultVersionId": "v1",
            "AttachmentCount": 1,
            "PermissionsBoundaryUsageCount": 0,
            "IsAttachable": true,
            "CreateDate": "2022-06-06 18:37:12+00:00",
            "UpdateDate": "2022-06-06 18:37:12+00:00"
        }
    ],
    "IsTruncated": true,
    "Marker": "ABf***********************************Q==",
    "ResponseMetadata": {
        "RequestId": "11a*****************26b",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "11a*****************26b",
            "content-type": "text/xml",
            "content-length": "1076",
            "date": "Mon, 06 Jun 2022 21:20:52 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "PolicyNames": [
        "AccessAnalyzerMonitorServicePolicy_L35****SQD"
    ],
    "PolicyIDs": [
        "ANP**********DO3"
    ],
    "ARNS": [
        "arn:aws:iam::391******688:policy/service-role/AccessAnalyzerMonitorServicePolicy_L35****SQD"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Managed Policies failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 6, valid min length: 20.

Error Sample Data

List Managed Policies failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 6, valid min length: 20.

List Policy Versions

Lists information about the versions of the specified managed policy, including the version that is currently set as the policy's default version.

READER NOTE

Policy Arn is a required parameter to run this command.

Run the List Policies or List Attached Roles Policies commands to obtain Policy Arn. Policy Arns can be found in the raw data at the paths $.Policies[*].Arn and $.AttachedPolicies[*].PolicyArn, respectively.

Input

Input Parameter	Required/Optional	Description	Example
Policy Arn	Required	The Amazon Resource Name (ARN) of the IAM policy for which you want the versions. Policy Arn can be obtained using List Policies or List Attached Role Policies command.	arn:aws:iam::391******688:policy/CastleTest
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Versions": [
        {
            "VersionId": "v3",
            "IsDefaultVersion": true,
            "CreateDate": "2022-06-06 18:43:37+00:00"
        },
        {
            "VersionId": "v2",
            "IsDefaultVersion": false,
            "CreateDate": "2018-07-13 00:23:05+00:00"
        },
        {
            "VersionId": "v1",
            "IsDefaultVersion": false,
            "CreateDate": "2018-07-12 22:19:32+00:00"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "727****************938",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "727****************938",
            "content-type": "text/xml",
            "content-length": "852",
            "date": "Thu, 09 Jun 2022 19:36:35 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "VersionIDs": [
        "v3",
        "v2",
        "v1"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Policy Versions failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

Error Sample Data

List Policy Versions failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter PolicyArn, value: 6, valid min length: 20.

List Role Policies

Lists the names of the inline policies that are embedded in the specified IAM role.

READER NOTE

Role Name is a required parameter to run this command.

Run the List Roles command to obtain Role Name. Role Names can be found in the raw data at the path $.Roles[*].RoleName.

Input

Input Parameter	Required/Optional	Description	Example
Role Name	Required	The name of the role to list inline policies for. Role Name can be obtained from the List Roles command.	D3_test
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Versions": [
        {
            "VersionId": "v3",
            "IsDefaultVersion": true,
            "CreateDate": "2022-06-06 18:43:37+00:00"
        },
        {
            "VersionId": "v2",
            "IsDefaultVersion": false,
            "CreateDate": "2018-07-13 00:23:05+00:00"
        },
        {
            "VersionId": "v1",
            "IsDefaultVersion": false,
            "CreateDate": "2018-07-12 22:19:32+00:00"
        }
    ],
    "IsTruncated": false,
    "ResponseMetadata": {
        "RequestId": "727****************938",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "727****************938",
            "content-type": "text/xml",
            "content-length": "852",
            "date": "Thu, 09 Jun 2022 19:36:35 GMT"
        },
        "RetryAttempts": 0
    }
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "VersionIDs": [
      "v3",
      "v2",
      "v1"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Role Policies failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: An error occurred (NoSuchEntity) when calling the ListRolePolicies operation: The role with name **** cannot be found.

Error Sample Data

List Role Policies failed.

Status Code: 403.

Message: An error occurred (NoSuchEntity) when calling the ListRolePolicies operation: The role with name **** cannot be found.

List Roles

Lists the IAM roles.

Input

Input Parameter	Required/Optional	Description	Example
Role Arn	Optional	The Amazon Resource Name (ARN) of the role to assume. If not specified, the value of the connection parameter Default Role ARN will be used. Please ensure that the assumed role has the necessary permissions to execute the relevant commands. Additionally, the assumed role must be trusted by the account used for connection. For more information, please refer to Editing the trust relationship for an existing role - AWS Directory Service.	arn:aws:iam::391****688:role/d3*role
Role Session Name	Optional	The identifier for the assumed role session. Use the role session name to uniquely identify a session, especially when the same role is assumed by different principals or for different purposes. The role session name should consist of upper- and lower-case alphanumeric characters with no spaces. Additionally, you can include underscores or any of the following characters: =,.@-. If this parameter is not specified but the Role ARN parameter is, the D3 system will automatically generate a role session name for you.	d3***role_Session1
Session Duration Time	Optional	The duration of the role assumption session in seconds. The value can range from 900 seconds (15 minutes) up to the maximum session duration setting for the role, which is 1 hour by default. If this parameter is not specified but the Role ARN parameter is, then the default value of 3600 seconds will be used.	1800

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE

{
    "Roles": [
        {
            "Path": "/service-role/",
            "RoleName": "AccessAnalyzerMonitorServiceRole_A5V****1LT",
            "RoleId": "ARO*********JGM",
            "Arn": "arn:aws:iam::391******688:role/service-role/AccessAnalyzerMonitorServiceRole_A5V****1LT",
            "CreateDate": "2022-06-06 18:37:12+00:00",
            "AssumeRolePolicyDocument": {
                "Version": "2012-10-17",
                "Statement": [
                    {
                        "Effect": "Allow",
                        "Principal": {
                            "Service": "access-analyzer.amazonaws.com"
                        },
                        "Action": "sts:AssumeRole"
                    }
                ]
            },
            "MaxSessionDuration": 3600
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RoleNames": [
        "AccessAnalyzerMonitorServiceRole_A5V****1LT"
    ],
    "RoleIDs": [
        "ARO*********JGM"
    ],
    "ARNs": [
        "arn:aws:iam::391******688:role/service-role/AccessAnalyzerMonitorServiceRole_A5V****1LT"
    ]
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Roles failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 6, valid min length: 20.

Error Sample Data

List Roles failed.

Status Code: 403.

Message: Parameter validation failed:\nInvalid length for parameter RoleArn, value: 6, valid min length: 20.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration

The API returned an error message

No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the AWS IAM portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: An error occurred (InvalidClientTokenId) when calling the ListRoles operation: The security token included in the request is invalid.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: An error occurred (InvalidClientTokenId) when calling the ListRoles operation: The security token included in the request is invalid.