AWS Cloudwatch Logs v1.0.0

About the connector

AWS CloudWatch Log helps you monitor, store, and access your system, application, and custom log files. This connector facilitates automated operations related to the log group, log streams, and metrics.

This document provides information about the AWS CloudWatch Log Connector, which facilitates automated interactions, with an AWS CloudWatch Log server using FortiSOAR™ playbooks. Add the AWS CloudWatch Log Connector as a step in FortiSOAR™ playbooks and perform automated operations with AWS CloudWatch Log.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 7.2.2 and later

AWS CloudWatch Log Version Tested on: 1.247354.0b251981

Authored By: Fortinet

Certified: Yes

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-cloudwatch-log

Prerequisites to configuring the connector

• The CloudWatch service must be integrated with your AWS instance for you to connect and perform automated operations
• The IAM role and your access credentials to that server must have relevant permissions for CloudWatch Logs service.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the AWS CloudWatch Log server.

Minimum Permissions Required

• Refer to AWS CloudWatch Logs' permissions page to assign appropriate permissions.

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 CloudWatch Log 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 CloudWatch Log 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 CloudWatch Log service. Access Credentials AWS Region: Specify the AWS region of your account required to access the AWS CloudWatch service. AWS Access Key ID: Specify the AWS Access Key's ID required to access the AWS CloudWatch service. AWS Secret Access Key: Specify the AWS Secret Access Key required to access the AWS CloudWatch Log 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
Create Log Group	Creates a log group based on the name you have specified. You can validate the log group creation at CloudWatch > Log Groups.	create_log_group Miscellaneous
Create Log Stream	Creates a log stream based on the log group and the log stream name you have specified. You can validate the log stream creation at CloudWatch > Log Groups > Log Streams.	create_log_stream Miscellaneous
Get Log Groups List	Gets a list of the log groups based on the log group name's prefix and the number of results to display on a page. You can list all the log groups or filter the results by the log group name's prefix.	get_list_log_groups Investigation
Get Log Streams List	Gets a list of the log streams for a specified log group based on the log group name you and the list order you have specified. You can list all the log streams or filter the results log group name's prefix.	get_list_log_streams Investigation
Get Log Events	Gets all the log events or logs for the duration and the log stream you have specified. You can view the log event entries at CloudWatch > Log Groups > Log Stream > Log Events	get_log_events Investigation
Delete Log Group	Deletes a log group, and its associated archived log events, permanently based on the log group name you have specified. You can validate the log group's removal from CloudWatch > Log Groups.	delete_log_group Miscellaneous
Delete Log Stream	Deletes the log stream and its associated archived log events based on the log group and the log stream name you have specified. Validate log stream removal at CloudWatch > Log Groups > Log Streams.	delete_log_stream Miscellaneous
Update Log Retention Policy	Sets a retention policy that retains log events based on the log group name and the number of days to retain.	update_log_retention_policy Miscellaneous
Revert Log Retention Policy	Reverts the retention of the specified log group based on the log group name you have specified. Log events do not expire if they belong to log groups without a retention policy.	revert_log_retention_policy Miscellaneous
Upload Log Event	Uploads log events to the log stream based on the log's group name and the stream name specified. You can upload multiple logs by specifying a sequence IS.	upload_log_event Miscellaneous
Run Log Insight Query	Runs a query to get log insights using CloudWatch Logs Insights based on the comma-separated log group names, time range, and the query you have specified.	run_log_insight_query Investigation
Get Log Insight Query Result	Runs a log insight query based on the query ID that you have specified.	get_log_insight_query_result Investigation
Stop Log Insight Query	Stops a CloudWatch Logs Insights query that is in progress based on the query ID you have specified.	stop_log_insight_query Miscellaneous

operation: Create Log Group

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify a name for the log group that is being created.
KMS Key ARN	(Optional) Specify the Amazon Resource Name (ARN) of the Customer Managed Key(CMK) to use when encrypting log data.
Tags	(Optional) Specify the key-value pairs to add as tags.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Create Log Stream

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify a name for the log group to which the created log stream belongs.
Log Stream Name	Specify a name for the log stream to be created.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Get Log Groups List

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name Prefix	(Optional) Specify a log group name prefix to list all the log group names starting with the specified prefix.
Next Page Token	(Optional) Specify the token for the next set of items to return. If the results exceed the limit specified (default 50) then output contains the next page token as well.
Limit	(Optional) Specify the maximum number of items to return. If left blank, the default is up to 50 items.

Output

The output contains the following populated JSON schema:
{
"logGroups": [
{
"logGroupName": "",
"creationTime": "",
"metricFilterCount": "",
"arn": "",
"storedBytes": ""
}
],
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Get Log Streams List

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group.
Order By	(Optional) Select if the results are to be ordered by the Log Stream Name or Event Time If you choose LogStreamName then specify a Log Stream Name prefix to match.
Next Page Token	(Optional) Specify the token for the next set of items to return. If the results exceed the limit specified (default 50), the output contains the next page token as well.
Limit	The maximum number of items returned. If left blank, the default is up to 50 items.

Output

The output contains the following populated JSON schema:
{
"logStreams": [
{
"logStreamName": "",
"creationTime": "",
"arn": "",
"storedBytes": ""
}
],
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Get Log Events

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group.
Log Stream Name	Specify the name of the log stream.
Start Time	(Optional) Specify the start of the time range for which log events are to be fetched.
End Time	(Optional) Specify the end of the time range for which log events are to be fetched.
Next Page Token	(Optional) Specify the token for the next set of items to return. If the results exceed the limit specified (default 50) then output contains the next page token as well.
Limit	(Optional) Specify the maximum number of log events that are to be listed. If not specified, the default value is 50.
Oldest Logs First	(Optional) Select the checkbox if you want the earliest log events to be returned first. By default, the box is unchecked.

Output

The output contains the following populated JSON schema:
{
"events": [],
"nextForwardToken": "",
"nextBackwardToken": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Delete Log Group

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group to be deleted.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Delete Log Stream

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group.
Log Stream Name	Specify the name of the log stream to be deleted.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Update Log Retention Policy

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group.
Retention Period	Specify the period to retain the log events in the log group you have specified.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Revert Log Retention Policy

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the log group name.

Output

The output contains the following populated JSON schema:
{
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Upload Log Event

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Name	Specify the name of the log group.
Log Stream Name	Specify the name of the log stream.
Timestamp	Specify the timestamp of the log event.
Message	Specify a message for the log event.
Sequence Token	(Optional) Specify the sequence token obtained from the response of the previous upload call.

Output

The output contains the following populated JSON schema:
{
"rejectedLogEventsInfo": {
"tooOldLogEventEndIndex": ""
},
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Run Log Insight 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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Group Names	Specify the list of log groups, as comma-separated-values, to be queried.
Start Time	Specify the beginning of the time range to query.
End Time	Specify the end of the time range to query.
Query String	Specify the query string to be used as a log insight query.
Limit	Specify the maximum number of log events to be returned. The default value is 50.

Output

The output contains the following populated JSON schema:
{
"queryId": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Get Log Insight Query Result

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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Insight Query ID	Specify the ID of the log insight query.

Output

The output contains the following populated JSON schema:
{
"results": [],
"statistics": {
"recordsMatched": "",
"recordsScanned": "",
"bytesScanned": ""
},
"status": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

operation: Stop Log Insight 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 CloudWatch Role ARN: ARN of the role that you want to 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.
Log Insight Query ID	Specify the ID of the log insight query to stop.

Output

The output contains the following populated JSON schema:
{
"success": "",
"ResponseMetadata": {
"RequestId": "",
"HTTPStatusCode": "",
"HTTPHeaders": {
"x-amzn-requestid": "",
"content-type": "",
"content-length": "",
"date": ""
},
"RetryAttempts": ""
}
}

Included playbooks

The Sample - AWS CloudWatch Log - 1.0.0 playbook collection comes bundled with the AWS CloudWatch Log connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after Installing the AWS CloudWatch Log connector.

• Create Log Group
• Create Log Stream
• Delete Log Group
• Delete Log Stream
• Get Log Events
• Get Log Groups List
• Get Log Insight Query Result
• Get Log Streams List
• Revert Log Retention Policy
• Run Log Insight Query
• Stop Log Insight Query
• Update Log Retention Policy
• Upload Log Event

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.