Add stacks to File Storage Security using the API

Recommendation

Before using the API, we recommend you run through the stack deployment using the web interfaces of File Storage Security and AWS. The web interfaces provide a user-friendly introduction to the deployment parameters, concepts, and processes.

For instructions on deploying through the web interfaces, see Get started.

Prerequisites

1. (Optional) Install the AWS command-line interface (CLI). All versions are supported.
2. Create Stacks.
3. Create an API Key.

4. Each request that you make requires an authorization and API version in the header.

   • Authorization Header
     • For Trend Micro Cloud One API Key:
       • Key: Authorization
       • Value: ApiKey <your api key value>
     • For Legacy API Key (DEPRECATED):
       • Key: api-secret-key
       • Value: <your api key value>
   • API version header:
     • Key: api-version
     • Value: v1

Example for Trend Micro Cloud One API Key:

GET /api/external-id HTTP/1.1
Authorization: ApiKey YOUR-API-KEY
Api-Version: v1

Example for Legacy API Key:

GET /api/filestorage/external-id HTTP/1.1
api-secret-key: YOUR-API-KEY
Api-Version: v1

where YOUR-API-KEY is replaced with the API key you generated previously.

If the API key is valid, the API call is allowed. If not, a 403 code is returned.

Deploy an all-in-one stack using the API

To deploy the all-in-one stack:

1. Obtain the ARNs of the scanner and storage stacks

   • Option 1 - Through the AWS console:

     • Go to CloudFormation > Stacks > your all-in-one stack > Outputs.
     • Take note of the ScannerStackManagementRoleARN and StorageStackManagementRoleARN values.

   • Option 2 - Through the AWS CLI:

     • Enter the following AWS CLI command:

     aws cloudformation describe-stacks --stack-name ALLINONE-STACK-NAME --output json --query 'Stacks[0].Outputs'

     where...

     ALLINONE-STACK-NAME is replaced with the name of your all-in-one stack.

     • In the command output, take note of the ScannerStackManagementRoleARN and StorageStackManagementRoleARN output values:

     
             {
                 "OutputKey": "ScannerStackManagementRoleARN",
                 "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-All-In-One-Stac-ManagementRole-EWQZVJ9M19R6",
                 "Description": "The ARN of the IAM role for File Storage Security backend services to manage the deployed resources."
             },
             {
                 "OutputKey": "StorageStackManagementRoleARN",
                 "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-All-In-One-Stac-ManagementRole-17O6WHFHH59YY",
                 "Description": "The ARN of the IAM role for File Storage Security backend services to manage the deployed resources."
             },
     

2. Add the scanner and storage stacks to File Storage Security

   First, add the scanner stack:

   • Call Create Stack and include the ScannerStackManagementRoleARN output value in the request body.

     The creation of the scanner stack will begin.

   • Take note of stackID in the API response, which is the scanner stack’s ID.

   • Call Describe Stack using the scanner stack's stackID noted in the previous step, and continue calling until the status in the response body becomes ok.

     You have now added the scanner stack.

   Now add the storage stack:

   • Call Create Stack, and include the previously-noted scanner stack stackID and storage stack StorageStackManagementRoleARN output value in the request body.

   The creation of the storage stack will begin.

   • Take note of stackID in the API response, which is the storage stack’s ID.
   • Call Describe Stack using the storage stack's stackID noted in the previous step, and continue calling until the status in the response body becomes ok.

   The stacks must be added separately, and the scanner stack must be added prior to the storage stack, as described above.

Deploy a scanner stack using the API

To deploy the scanner stack:

1. Obtain the ARN of the scanner stack

   • Option 1 - Through the AWS console:

     • Go to CloudFormation > Stacks > your scanner stack > Outputs.
     • Take note of the ScannerStackManagementRoleARN output value.

   • Option 2 - Through the AWS CLI:

     • Enter the following AWS CLI command:

       aws cloudformation describe-stacks --stack-name SCANNER-STACK-NAME --output json --query 'Stacks[0].Outputs'

       where...

       SCANNER-STACK-NAME is replaced with the name of your scanner stack.

       • In the command output, take note of the ScannerStackManagementRoleARN output value:

       
               {
                   "OutputKey": "ScannerStackManagementRoleARN",
                   "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-Scanner-Stack-ManagementRole-17O6WHFHH59YY",
                   "Description": "The ARN of the IAM role for File Storage Security backend services to manage the deployed resources."
               },
       

       • (Optional) In the command output, take note of the ScannerLambdaAliasARN output value:

       
               {
                   "OutputKey": "ScannerLambdaAliasARN",
                   "OutputValue": "arn:aws:lambda:us-east-1:123456789012:function:FileStorageSecurity-Scanner-Stack-ScannerLambda-I9ni6ZtjUyuD:TM-FSS-MANAGED"
               },
       

2. Add the scanner stack to File Storage Security

   • Call Create Stack and include the scanner stack ScannerStackManagementRoleARN output value in the request body.

     The creation of the scanner stack will begin.

   • Take note of the stackID in the API response, which is the scanner stack’s ID.

   • Call Describe Stack using the scanner stack's stackID noted in the previous step, and continue calling until the status in the response body becomes ok.

     You have now added the scanner stack.

3. (Optional) Update KMS key policy if enabling ScanResultTopic SNS encryption

   • You only need to do this step if you deploy the storage stack in a different AWS account from the scanner stack.

   • Enter the following AWS CLI command:

     aws kms get-key-policy --key-id KMS-MASTER-KEY-ARN-FOR-SNS --policy-name default --output text > key-policy.json

     where...

     KMS-MASTER-KEY-ARN-FOR-SNS is replaced with the ARN of your KMS key used for SNS ScanResultTopic encryption.

   • Edit key-policy.json and insert a new Statement object in it.

     
         {
             "Sid": "Grant Scanner permission",
             "Effect": "Allow",
             "Principal": {
                 "AWS": 
             },
             "Action": [
                 "kms:Decrypt",
                 "kms:GenerateDataKey"
             ],
             "Resource": "*"
         }
     

     where...

     ScannerExecutionRoleARN is replaced with the ARN of the scannerExecutionRole in your scanner stack.

   • Enter the following AWS CLI command:

     aws kms put-key-policy --key-id KMS-MASTER-KEY-ARN-FOR-SNS --policy-name default --policy file://key-policy.json

     KMS-MASTER-KEY-ARN-FOR-SNS is replaced with the ARN of your KMS key used for SNS ScanResultTopic encryption.

Deploy an account scanner stack using the API

To deploy the account scanner stack:

1. Obtain the ARN of the scanner stack

   • Option 1 - Through the AWS console:

     • Go to CloudFormation > Stacks > your scanner stack > Outputs.
     • Take note of the AccountScannerStackManagementRoleARN output value.

   • Option 2 - Through the AWS CLI:

     • Enter the following AWS CLI command:

       aws cloudformation describe-stacks --stack-name SCANNER-STACK-NAME --output json --query 'Stacks[0].Outputs'

       where...

       SCANNER-STACK-NAME is replaced with the name of your scanner stack.

       • In the command output, take note of the AccountScannerStackManagementRoleARN output value:

         
             {
                 "OutputKey": "AccountScannerStackManagementRoleARN",
                 "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-Scanner-Stack-ManagementRole-17O6WHFHH59YY",
                 "Description": "The ARN of the IAM role for File Storage Security backend services to manage the deployed resources."
             },
         

2. Add the scanner stack to File Storage Security

   • Call Create Stack and include the scanner stack AccountScannerStackManagementRoleARN output value in the request body.

     The creation of the scanner stack will begin.

   • Take note of the stackID in the API response, which is the account scanner stack’s ID.

   • Call Describe Stack using the account scanner stack's stackID noted in the previous step, and continue calling until the status in the response body becomes ok.

     You have now added the account scanner stack.

Deploy a storage stack using the API

To deploy the storage stack:

1. Obtain the ARN of the storage stack

   • Option 1 - Through the AWS console:

     • Go to CloudFormation > Stacks > your storage stack > Outputs.
     • Take note of the StorageStackManagementRoleARN output value.
     • (Optional) Take note of the BucketListenerRoleARN output value.

   • Option 2 - Through the AWS CLI:

     • Enter the following AWS CLI command:

       aws cloudformation describe-stacks --stack-name STORAGE-STACK-NAME --output json --query 'Stacks[0].Outputs'

       where...

       STORAGE-STACK-NAME is replaced with the name of your storage stack.

     • In the command output, take note of the StorageStackManagementRoleARN output value:

       
           {
               "OutputKey": "StorageStackManagementRoleARN",
               "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-All-In-One-Stac-ManagementRole-17O6WHFHH59YY",
               "Description": "The ARN of the IAM role for File Storage Security backend services to manage the deployed resources."
           },
       

     • (Optional) In the command output, take note of the BucketListenerRoleARN output value:

       
           {
               "OutputKey": "BucketListenerRoleARN",
               "OutputValue": "arn:aws:iam::123456789012:role/FileStorageSecurity-All-In-One-BucketListenerExecutionR-5RKPKU3L3P3C"
           },
       

2. Add the storage stack to File Storage Security

   • Call List Stacks to retrieve the scanner stack’s stackID.

   • Call Create Stack and include the scanner stack stackID and the storage stack StorageStackManagementRoleARN output value in the request body.

     The creation of the storage stack will begin.

   • Take note of the stackID in the API response, which is the storage stack’s ID.

   • Call Describe Stack using the storage stack's stackID noted in the previous step, and continue calling until the status in the response body becomes ok.

     You have now added the storage stack.

3. (Optional) Update KMS key policy if enabling scanner queue encryption

   • You only need this step if you deploy the storage stack in a different AWS account from the scanner stack. And you also want to enable server-side encryption for SQS queues.

   • Enter the following AWS CLI command:

     aws kms get-key-policy --key-id KMS-MASTER-KEY-ARN-FOR-SQS --policy-name default --output text > key-policy.json

     where...

     KMS-MASTER-KEY-ARN-FOR-SQS is replaced with the ARN of your KMS key using for SQS encryption.

   • Edit key-policy.json and insert a new Statement object in it.

     
         {
             "Sid": "Grant bucketListener permission",
             "Effect": "Allow",
             "Principal": {
                 "AWS": 
             },
             "Action": [
                 "kms:Decrypt",
                 "kms:GenerateDataKey"
             ],
             "Resource": "*"
         }
     

     where...

     BucketListenerRoleARN is replaced with the ARN of bucketListener in your storage stack.

   • Enter the following AWS CLI command:

     aws kms put-key-policy --key-id KMS-MASTER-KEY-ARN-FOR-SQS --policy-name default --policy file://key-policy.json

     KMS-MASTER-KEY-ARN-FOR-SQS is replaced with the ARN of your KMS key using for SQS encryption.