About the connector
AWS Athena is an interactive query service that lets you use standard SQL to analyze data directly in Amazon S3.
This document provides information about the AWS Athena Connector, which facilitates automated interactions, with a AWS Athena server using FortiSOAR™ playbooks. Add the AWS Athena Connector as a step in FortiSOAR™ playbooks and perform automated operations with AWS Athena.
Version information
Connector Version: 1.1.0
FortiSOAR™ Version Tested on: 7.2.2-1098
AWS Athena Version Tested on: 2022-11-17T16:04
Authored By: Fortinet
Certified: Yes
Release Notes for version 1.1.0
Following enhancements have been made to the AWS Athena Connector in version 1.1.0:
- This connector version is now certified
- You can specify an IAM role, as a configuration type, when configuring the connector
Installing the connector
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-aws-athena
Prerequisites to configuring the connector
- You must have the URL of AWS Athena server to which you connect and perform automated operations, and credentials to access that server.
- The FortiSOAR™ server should have outbound connectivity to port 443 on the AWS Athena server.
Minimum Permissions Required
Configuring the connector
For the procedure to configure a connector, click here
Configuration parameters
In FortiSOAR™, on the Content Hub page, click the Manage tab, and then click the AWS Athena connector card. On the connector popup, click the Configurations tab to enter the required configuration details:
| Parameter |
Description |
| Configuration Type |
Select the Configuration Type from IAM Role or Access Credentials. The selected configuration type determines the type of credentials that you require to access AWS Athena and perform automated actions. Enter the requested details as per the following:
- IAM Role
- AWS Instance IAM Role: Specify the IAM Role of your AWS instance that you need to access the AWS Athena service.
- Access Credentials
- AWS Region: Specify the AWS region of your account required to access the AWS Athena service.
- AWS Access Key ID: Specify the AWS Access Key's ID required to access the AWS Athena service.
- AWS Secret Access Key: Specify the AWS Secret Access Key required to access the AWS Athena service.
|
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set to True. |
Actions supported by the connector
The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™:
| Function |
Description |
Annotation and Category |
| Run Athena Query |
Runs the SQL query statements contained in the Query field, based on the Configuration selected, Location, Encryption, and other input parameters that you have specified. |
run_athena_query
Investigation |
operation: Run Athena Query
Input parameters
| Parameter |
Description |
| Assume a Role |
Select this checkbox if you have specified IAM Role as the configuration type in Configuration Parameters. Enabling this option makes the following parameters mandatory:
- AWS Region: AWS region of your account to access the AWS Athena
- Role ARN: ARN of the role that you want assume to execute this action on AWS.
- Session Name: Name of the session that will be created to execute this action on AWS.
If you have specified Access Credentials as the configuration type, then enabling this parameter is optional. |
| Query |
Specify the SQL query statements to be executed. |
| Location |
Specify an output location in Amazon S3 where the results are to be stored. |
| Encryption |
Specify one of the following encryption formats that you want to use:
SSE-S3: Amazon S3 server-side encryption with Amazon S3-managed keysSSE-KMS: Server-side encryption with KMS-managed keysCSE-KMS: Client-side encryption with KMS-managed keys
If you choose SSE-KMS or CSE-KMS, KMS is the KMS key ARN or ID. |
| Database Name |
(Optional) Specify the name of the Athena database in which to run the query. |
| Max Tries |
(Optional) Specify the maximum number of attempts to fetch the results of the query. If left blank, the default value is 60. |
Output
The output contains the following populated JSON schema:
{
"error": "",
"error_message": "",
"response": {
"error": "",
"result": {
"ResultSet": {
"Rows": [
{
"Data": [
{
"VarCharValue": ""
}
]
}
],
"ResultSetMetadata": {
"ColumnInfo": [
{
"CatalogName": "",
"SchemaName": "",
"TableName": "",
"Name": "",
"Label": "",
"Type": "",
"Precision": 123,
"Scale": 123,
"Nullable": "",
"CaseSensitive": ""
}
]
}
},
"NextToken": ""
}
}
}
Included playbooks
The Sample - AWS Athena - 1.1.0 playbook collection comes bundled with the AWS Athena connector. The playbook contain steps using which you can perform the supported action. You can see the following bundled playbook in the Automation > Playbooks section in FortiSOAR™ after installing the AWS Athena connector.
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection, since the sample playbook collection gets deleted during connector upgrade and delete.
