Fortinet black logo

Cisco SMA v1.0.1

Copy Link
Copy Doc ID 58b5e552-691b-4c10-9d20-726f9b531148:1

About the connector

The Cisco Content Security Management Appliance (SMA) centralizes management and reporting functions across multiple Cisco email and web security appliances. It simplifies administration and planning, improves compliance monitoring, helps to enable consistent enforcement of policies, and enhances threat protection.

This document provides information about the Cisco SMA connector, which facilitates automated interactions, with a Cisco SMA server using FortiSOAR™ playbooks. Add the Cisco SMA connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically tracking emails in Cisco SMA, retrieving message details from Cisco SMA, and releasing specific emails from quarantine in Cisco SMA.

Version information

Connector Version: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

Following enhancements have been made to the Cisco SMA connector in version 1.0.1:

  • Updated the Get Message Details operation as follows:
    • Changed the Serial Number parameter to be a mandatory input parameter. Earlier it was an optional parameter.
    • Removed the Host Name input parameter.
  • Updated the Track Emails operation by adding the following input parameters:
    • Sender IP
    • File Hash
    • Subject
    • Envelope Sender
    • Envelope Recipient
    • Message ID Header
    • Message Delivery Status
    • Message Delivered
    • Message Direction
    • Messages with Malicious URLs
    • Attachment

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-cisco-sma

For the detailed procedure to install a connector, click here

Prerequisites to configuring the connector

  • You must have the URL of the Cisco SMA server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
  • You must enable AsyncOS API on the Management interface. The ASyncOS API is available from version 12.x.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Cisco SMA connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Server URL URL of the Cisco SMA server to which you will connect and perform automated operations.
Username Username of the Cisco SMA server to which you will connect and perform automated operations.
Password Password of the Cisco SMA server to which you will connect and perform automated operations.
Port AsyncOS API port of the Cisco SMA server.

Defaults to 6443 for the https protocol. For the http protocol port should be set as 6080.

Is Two Factor Authentication Enable Select this checkbox if you have enabled 2FA.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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™ release 4.10.0 and onwards:

Function Description Annotation and Category
Track Emails Track emails on Cisco SMA based on the search option, start and end time of the emails and other input parameters that you have specified. track_emails
Investigation
Get Message Details Retrieves details of a specific message from Cisco SMA based on the start and end time of the message, ICID, message ID, and other input parameters that you have specified. get_message_details
Investigation
Fetch Emails From SPAM Quarantine Fetches emails from the SPAM quarantine in Cisco SMA based on the start and end time of the emails other input parameters that you have specified. fetch_from_spam_quarantine
Investigation
Fetch Emails From Other Quarantine Fetches emails from a specific quarantine in Cisco SMA based quarantine name, quarantine type, the start and end time of the emails, and other input parameters that you have specified. fetch_from_other_quarantine
Investigation
Release Emails From Quarantine Releases specific emails from quarantine in Cisco SMA based on the quarantine name, quarantine type, and message IDs you have specified. release_emails_from_quarantine
Investigation
Delete Message Deletes specific emails from Cisco SMA based on the quarantine name, quarantine type, and message IDs you have specified. delete_message
Investigation

operation: Track Emails

Input parameters

Parameter Description
Start Time Start time from when you want to track emails on Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when you want to track emails on Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Search Option Search option, for example, messages, based on which you want to track emails on Cisco SMA.
Cisco Host (Optional) Hostname based on which you want to track emails on Cisco SMA.
Cisco MID (Optional) Input message ID based on which you want to track emails on Cisco SMA.
Sender IP (Optional) Sender IP address based on which you want to track emails on Cisco SMA.
File Hash (Optional) Input file hash based on which you want to track emails on Cisco SMA.
Subject (Optional) Value of the subject based on which you want to track emails on Cisco SMA. You can choose from the following options: Is, Is Empty, Contains, or Begins With.
If you select Is Empty, then this operation will track only those emails with empty subjects.
If you select Is, then you must specify the following parameter:
  • Subject Is: Specify a subject value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject matches the value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Subject Contains: Specify a subject value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject contains the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Subject Begins With: Specify a subject value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject "Begins With" value matches the "Begins With" value that you have specified.
Envelope Sender (Optional) Value of the Envelope Sender based on which you want to track emails from Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Envelope Sender Contains: Specify an envelope sender value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Envelope Sender Is: Specify an envelope sender value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Sender Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender "Begins With" value matches the "Begins With" value that you have specified.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to track emails from Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Envelope Recipient Is: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.
Message ID Header (Optional) ID of the input message header based on which you want to track emails on Cisco SMA.
Message Delivery Status (Optional) Status of the input message delivery based on which you want to track emails on Cisco SMA. You can choose from the following options: Delivered, Dropped, Aborted, or Bounced.
Message Delivered (Optional) Select this option to track only those emails that have been delivered.
Message Direction (Optional) Direction based on which you want to track emails on Cisco SMA. You can choose between Incoming or Outgoing.
Messages with Malicious URLs (Optional) Select this option to track only those emails that contain malicious URLs.
Attachment (Optional) Input attachment name based on which you want to track emails on Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Attachment Name Contains: Specify a attachment name value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Attachment Name Is: Specify a attachment name value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Attachment Name Begins With: Specify a attachment name value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name "Begins With" value matches the "Begins With" value that you have specified.
Offset (Optional) Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with limit, which determines how many records to retrieve starting from the offset.
Limit (Optional) Maximum number of records this operation should retrieve from Cisco SMA.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": "",
"num_bad_records": ""
},
"data": [
{
"attributes": {
"recipient": [],
"replyTo": "",
"senderDomain": "",
"messageStatus": "",
"direction": "",
"senderIp": "",
"hostName": "",
"serialNumber": "",
"sender": "",
"timestamp": "",
"isCompleteData": "",
"senderGroup": "",
"subject": "",
"sbrs": "",
"mid": [],
"icid": "",
"verdictChart": "",
"mailPolicy": []
}
}
]
}

operation: Get Message Details

Input parameters

Parameter Description
Start Time Start time from when you want to retrieve message details from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when you want to retrieve message details from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Message ID ID of the message for which you want to retrieve message details from Cisco SMA. For example, 150.
ICID ICID of the message for which you want to retrieve message details from Cisco SMA. For example, 150.
Serial Number Serial number whose associated message details from Cisco SMA. Serial Number to get its details. For example, 64122536256E-FCH1812V1ST.

Output

The output contains the following populated JSON schema:
{
"data": {
"messages": {
"recipient": [],
"hostName": "",
"showSummaryTimeBox": "",
"messageStatus": "",
"direction": "",
"showAMP": "",
"showDLP": "",
"summary": [
{
"description": "",
"timestamp": "",
"lastEvent": ""
}
],
"sender": "",
"messageSize": "",
"sendingHostSummary": {
"ipAddress": "",
"sbrsScore": "",
"reverseDnsHostname": ""
},
"senderGroup": "",
"attachments": [],
"timestamp": "",
"showURL": "",
"isCompleteData": "",
"midHeader": "",
"mid": [],
"subject": "",
"smtpAuthId": "",
"mailPolicy": []
}
}
}

operation: Fetch Emails From SPAM Quarantine

Input parameters

Parameter Description
Start Time Start time from when the emails are quarantined in the SPAM folder based on which you want to retrieve emails from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when the emails are quarantined in the SPAM folder based on which you want to retrieve emails from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Sorting (Optional) Value and/or direction to sort the results retrieved by this operation. You can specify the following options: Order By or Order Direction. You can also specify both Order By and Order Direction.
If you select Order Direction, then you must specify the following parameter:
  • Order Direction: Sort results retrieved by this operation in this direction. You can choose one of the following: Ascending or Descending.
If you select Order By, then you must specify the following parameter:
  • Order By: Sort results retrieved by this operation using the value specified You can choose one of the following: From Address, To Address, or Subject.
Lazy Loading Select this option if you want to limit the result data retrieved by this operation using lazy loading.
If you check the Lazy Loading checkbox, then you must specify the following parameters:
  • Offset: Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with Limit, which determines how many records to retrieve starting from the offset.
  • Limit: Maximum number of records this operation should retrieve from Cisco SMA.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Is, Begins With, Ends With, or Does Not Contain.
If you select Is, then you must specify the following parameter:
  • Envelope Recipient Is: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Recipient Ends With: Specify an envelope recipient value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Recipient Does Not Contain: Specify an envelope recipient value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope recipient value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"mid": "",
"attributes": {
"subject": "",
"date": "",
"toAddress": [],
"fromAddress": [],
"envelopeRecipient": [],
"size": ""
}
}
]
}

operation: Fetch Emails From Other Quarantine

Input parameters

Parameter Description
Start Time Start time from when the emails are quarantined in the quarantine folder that you have specified based on which you want to retrieve emails from Cisco SMA.
End Time End time till when the emails are quarantined in the quarantine folder that you have specified based on which you want to retrieve emails from Cisco SMA.
Quarantine Name Name of the quarantine in which you want to search in Cisco SMA, and from you want to retrieve emails.
Quarantine Type Type of the quarantine that you want to search in Cisco SMA, and from you want to retrieve emails. For example, pvo.
Offset Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with Limit, which determines how many records to retrieve starting from the offset.
Limit Maximum number of records this operation should retrieve from Cisco SMA.
Subject (Optional) Value of the subject based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, Does Not Contain, Does Not Start With, or Does Not End With.
If you select Matches Exactly, then you must specify the following parameter:
  • Subject Matches Exactly: Specify a subject that you want to match in the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Subject Ends With: Specify a subject value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Subject Contains: Specify a subject value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Subject Does Not Contain: Specify a subject value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Subject Begins With: Specify a subject value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Subject Does Not End With: Specify a subject value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Subject Does Not Start With: Specify a subject value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Starts With" value Does Not match with the "Starts With" value that you have specified.
Originating ESA IP address of the ESA in which the email was processed.
Attachment Details (Optional) Name and/or size based on which you want to filter emails retrieved by this operation. You can specify the following options: Attachment Name or Attachment Size Filter By. You can also specify both Attachment Name and Attachment Size Filter By.
If you select Attachment Name, then you must specify the following parameter:
  • Attachment Name: Name of the attachment, based on which you want to filter emails retrieved by this operation.
If you select Attachment Size Filter by, then you must specify the following parameter:
  • Size Filter: Attachment size filter based on which you want to filter emails retrieved by this operation. You can choose one of the following: Range, More Than, or Less Than.
    • If you select Range, then in the Attachment Size From Value field, enter the attachment size in KB from which you want to filter emails, and in the Attachment Size To Value field, enter the attachment size in KB till which you want to filter emails.
    • If you select More Than, then in the Attachment Size From Value field, enter the attachment size in KB more than which you want to filter emails.
    • If you select Less Than, then in the Attachment Size From Value field, enter the attachment size in KB lesser than which you want to filter emails.
Sorting (Optional) Value and/or direction to sort the results retrieved by this operation. You can specify the following options: Order By or Order Direction. You can also specify both Order By and Order Direction.
If you select Order Direction, then you must specify the following parameter:
  • Order Direction: Sort results retrieved by this operation in this direction. You can choose one of the following: Ascending or Descending.
If you select Order By, then you must specify the following parameter:
  • Order By: Sort results retrieved by this operation using the value specified You can choose one of the following: Sender, Subject, Received, Scheduled Exit, or Size.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, or Does Not Contain.
If you select Matches Exactly, then you must specify the following parameter:
  • Envelope Recipient Matches Exactly: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Recipient Ends With: Specify an envelope recipient value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Recipient Does Not Contain: Specify an envelope recipient value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope recipient value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Envelope Recipient Does Not End With: Specify an envelope recipient value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Envelope Recipient Does Not Start With: Specify an envelope recipient value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Starts With" value Does Not match with the "Starts With" value that you have specified.
Envelope Sender (Optional) Value of the Envelope Sender based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, or Does Not Contain.
If you select Matches Exactly, then you must specify the following parameter:
  • Envelope Sender Matches Exactly: Specify an envelope sender value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Sender Ends With: Specify an envelope sender value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Sender Contains: Specify an envelope sender value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Sender Does Not Contain: Specify an envelope sender value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Sender Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Envelope Sender Does Not End With: Specify an envelope sender value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Envelope Sender Does Not Start With: Specify an envelope sender value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Starts With" value Does Not match with the "Starts With" value that you have specified.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"mid": "",
"attributes": {
"received": "",
"originatingEsaIp": "",
"esaHostName": "",
"esaMid": "",
"scheduledExit": "",
"sender": "",
"recipient": [],
"subject": "",
"quarantineForReasonDict": [
{
"quarantineName": "",
"reason": []
}
],
"quarantineForReason": [],
"inQuarantines": "",
"size": ""
}
}
]
}

operation: Release Emails From Quarantine

Input parameters

Parameter Description
Message IDs List of Message IDs that you want to release from quarantine in Cisco SMA. You can enter multiple message IDs in the CSV or List format. For example, 150,151,152 or [150,151,152]
Quarantine Type Type of the quarantine from which you want to release the emails. For example, pvo.
Quarantine Name Name of the quarantine from which you want to release the emails. For example, spam.

Output

The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}

operation: Delete Message

Input parameters

Parameter Description
Message IDs List of Message IDs that you want to delete from Cisco SMA. You can enter multiple message IDs in the CSV or List format. For example, 150,151,152 or [150,151,152]
Quarantine Type Type of the quarantine from which you want to delete the emails. For example, pvo.
Quarantine Name Name of the quarantine from which you want to release the emails. For example, spam.

Output

The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}

Included playbooks

The Sample - Cisco SMA - 1.0.1 playbook collection comes bundled with the Cisco SMA connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in CyOPsTM after importing the Cisco SMA connector.

  • Delete Message
  • Fetch Emails From Other Quarantine
  • Fetch Emails From SPAM Quarantine
  • Get Message Details
  • Release Emails From Quarantine
  • Track Emails

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.

Previous
Next

About the connector

The Cisco Content Security Management Appliance (SMA) centralizes management and reporting functions across multiple Cisco email and web security appliances. It simplifies administration and planning, improves compliance monitoring, helps to enable consistent enforcement of policies, and enhances threat protection.

This document provides information about the Cisco SMA connector, which facilitates automated interactions, with a Cisco SMA server using FortiSOAR™ playbooks. Add the Cisco SMA connector as a step in FortiSOAR™ playbooks and perform automated operations, such as automatically tracking emails in Cisco SMA, retrieving message details from Cisco SMA, and releasing specific emails from quarantine in Cisco SMA.

Version information

Connector Version: 1.0.1

Authored By: Fortinet

Certified: No

Release Notes for version 1.0.1

Following enhancements have been made to the Cisco SMA connector in version 1.0.1:

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-cisco-sma

For the detailed procedure to install a connector, click here

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Cisco SMA connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Server URL URL of the Cisco SMA server to which you will connect and perform automated operations.
Username Username of the Cisco SMA server to which you will connect and perform automated operations.
Password Password of the Cisco SMA server to which you will connect and perform automated operations.
Port AsyncOS API port of the Cisco SMA server.

Defaults to 6443 for the https protocol. For the http protocol port should be set as 6080.

Is Two Factor Authentication Enable Select this checkbox if you have enabled 2FA.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as 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™ release 4.10.0 and onwards:

Function Description Annotation and Category
Track Emails Track emails on Cisco SMA based on the search option, start and end time of the emails and other input parameters that you have specified. track_emails
Investigation
Get Message Details Retrieves details of a specific message from Cisco SMA based on the start and end time of the message, ICID, message ID, and other input parameters that you have specified. get_message_details
Investigation
Fetch Emails From SPAM Quarantine Fetches emails from the SPAM quarantine in Cisco SMA based on the start and end time of the emails other input parameters that you have specified. fetch_from_spam_quarantine
Investigation
Fetch Emails From Other Quarantine Fetches emails from a specific quarantine in Cisco SMA based quarantine name, quarantine type, the start and end time of the emails, and other input parameters that you have specified. fetch_from_other_quarantine
Investigation
Release Emails From Quarantine Releases specific emails from quarantine in Cisco SMA based on the quarantine name, quarantine type, and message IDs you have specified. release_emails_from_quarantine
Investigation
Delete Message Deletes specific emails from Cisco SMA based on the quarantine name, quarantine type, and message IDs you have specified. delete_message
Investigation

operation: Track Emails

Input parameters

Parameter Description
Start Time Start time from when you want to track emails on Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when you want to track emails on Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Search Option Search option, for example, messages, based on which you want to track emails on Cisco SMA.
Cisco Host (Optional) Hostname based on which you want to track emails on Cisco SMA.
Cisco MID (Optional) Input message ID based on which you want to track emails on Cisco SMA.
Sender IP (Optional) Sender IP address based on which you want to track emails on Cisco SMA.
File Hash (Optional) Input file hash based on which you want to track emails on Cisco SMA.
Subject (Optional) Value of the subject based on which you want to track emails on Cisco SMA. You can choose from the following options: Is, Is Empty, Contains, or Begins With.
If you select Is Empty, then this operation will track only those emails with empty subjects.
If you select Is, then you must specify the following parameter:
  • Subject Is: Specify a subject value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject matches the value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Subject Contains: Specify a subject value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject contains the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Subject Begins With: Specify a subject value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose subject "Begins With" value matches the "Begins With" value that you have specified.
Envelope Sender (Optional) Value of the Envelope Sender based on which you want to track emails from Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Envelope Sender Contains: Specify an envelope sender value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Envelope Sender Is: Specify an envelope sender value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Sender Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope sender "Begins With" value matches the "Begins With" value that you have specified.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to track emails from Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Envelope Recipient Is: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.
Message ID Header (Optional) ID of the input message header based on which you want to track emails on Cisco SMA.
Message Delivery Status (Optional) Status of the input message delivery based on which you want to track emails on Cisco SMA. You can choose from the following options: Delivered, Dropped, Aborted, or Bounced.
Message Delivered (Optional) Select this option to track only those emails that have been delivered.
Message Direction (Optional) Direction based on which you want to track emails on Cisco SMA. You can choose between Incoming or Outgoing.
Messages with Malicious URLs (Optional) Select this option to track only those emails that contain malicious URLs.
Attachment (Optional) Input attachment name based on which you want to track emails on Cisco SMA. You can choose from the following options: Contains, Is and Begins With.
If you select Contains, then you must specify the following parameter:
  • Attachment Name Contains: Specify a attachment name value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name contains the value that you have specified.
If you select Is, then you must specify the following parameter:
  • Attachment Name Is: Specify a attachment name value that you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name matches the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Attachment Name Begins With: Specify a attachment name value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will track only those emails whose attachment name "Begins With" value matches the "Begins With" value that you have specified.
Offset (Optional) Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with limit, which determines how many records to retrieve starting from the offset.
Limit (Optional) Maximum number of records this operation should retrieve from Cisco SMA.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": "",
"num_bad_records": ""
},
"data": [
{
"attributes": {
"recipient": [],
"replyTo": "",
"senderDomain": "",
"messageStatus": "",
"direction": "",
"senderIp": "",
"hostName": "",
"serialNumber": "",
"sender": "",
"timestamp": "",
"isCompleteData": "",
"senderGroup": "",
"subject": "",
"sbrs": "",
"mid": [],
"icid": "",
"verdictChart": "",
"mailPolicy": []
}
}
]
}

operation: Get Message Details

Input parameters

Parameter Description
Start Time Start time from when you want to retrieve message details from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when you want to retrieve message details from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Message ID ID of the message for which you want to retrieve message details from Cisco SMA. For example, 150.
ICID ICID of the message for which you want to retrieve message details from Cisco SMA. For example, 150.
Serial Number Serial number whose associated message details from Cisco SMA. Serial Number to get its details. For example, 64122536256E-FCH1812V1ST.

Output

The output contains the following populated JSON schema:
{
"data": {
"messages": {
"recipient": [],
"hostName": "",
"showSummaryTimeBox": "",
"messageStatus": "",
"direction": "",
"showAMP": "",
"showDLP": "",
"summary": [
{
"description": "",
"timestamp": "",
"lastEvent": ""
}
],
"sender": "",
"messageSize": "",
"sendingHostSummary": {
"ipAddress": "",
"sbrsScore": "",
"reverseDnsHostname": ""
},
"senderGroup": "",
"attachments": [],
"timestamp": "",
"showURL": "",
"isCompleteData": "",
"midHeader": "",
"mid": [],
"subject": "",
"smtpAuthId": "",
"mailPolicy": []
}
}
}

operation: Fetch Emails From SPAM Quarantine

Input parameters

Parameter Description
Start Time Start time from when the emails are quarantined in the SPAM folder based on which you want to retrieve emails from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
End Time End time till when the emails are quarantined in the SPAM folder based on which you want to retrieve emails from Cisco SMA. Enter the time in the YYYY-MM-DDThh:mm:00.000Z format.
Sorting (Optional) Value and/or direction to sort the results retrieved by this operation. You can specify the following options: Order By or Order Direction. You can also specify both Order By and Order Direction.
If you select Order Direction, then you must specify the following parameter:
  • Order Direction: Sort results retrieved by this operation in this direction. You can choose one of the following: Ascending or Descending.
If you select Order By, then you must specify the following parameter:
  • Order By: Sort results retrieved by this operation using the value specified You can choose one of the following: From Address, To Address, or Subject.
Lazy Loading Select this option if you want to limit the result data retrieved by this operation using lazy loading.
If you check the Lazy Loading checkbox, then you must specify the following parameters:
  • Offset: Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with Limit, which determines how many records to retrieve starting from the offset.
  • Limit: Maximum number of records this operation should retrieve from Cisco SMA.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Is, Begins With, Ends With, or Does Not Contain.
If you select Is, then you must specify the following parameter:
  • Envelope Recipient Is: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Recipient Ends With: Specify an envelope recipient value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Recipient Does Not Contain: Specify an envelope recipient value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope recipient value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"mid": "",
"attributes": {
"subject": "",
"date": "",
"toAddress": [],
"fromAddress": [],
"envelopeRecipient": [],
"size": ""
}
}
]
}

operation: Fetch Emails From Other Quarantine

Input parameters

Parameter Description
Start Time Start time from when the emails are quarantined in the quarantine folder that you have specified based on which you want to retrieve emails from Cisco SMA.
End Time End time till when the emails are quarantined in the quarantine folder that you have specified based on which you want to retrieve emails from Cisco SMA.
Quarantine Name Name of the quarantine in which you want to search in Cisco SMA, and from you want to retrieve emails.
Quarantine Type Type of the quarantine that you want to search in Cisco SMA, and from you want to retrieve emails. For example, pvo.
Offset Specify an offset value to retrieve a subset of records starting with the offset value. Offset works with Limit, which determines how many records to retrieve starting from the offset.
Limit Maximum number of records this operation should retrieve from Cisco SMA.
Subject (Optional) Value of the subject based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, Does Not Contain, Does Not Start With, or Does Not End With.
If you select Matches Exactly, then you must specify the following parameter:
  • Subject Matches Exactly: Specify a subject that you want to match in the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Subject Ends With: Specify a subject value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Subject Contains: Specify a subject value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Subject Does Not Contain: Specify a subject value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Subject Begins With: Specify a subject value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Subject Does Not End With: Specify a subject value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Subject Does Not Start With: Specify a subject value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose subject "Starts With" value Does Not match with the "Starts With" value that you have specified.
Originating ESA IP address of the ESA in which the email was processed.
Attachment Details (Optional) Name and/or size based on which you want to filter emails retrieved by this operation. You can specify the following options: Attachment Name or Attachment Size Filter By. You can also specify both Attachment Name and Attachment Size Filter By.
If you select Attachment Name, then you must specify the following parameter:
  • Attachment Name: Name of the attachment, based on which you want to filter emails retrieved by this operation.
If you select Attachment Size Filter by, then you must specify the following parameter:
  • Size Filter: Attachment size filter based on which you want to filter emails retrieved by this operation. You can choose one of the following: Range, More Than, or Less Than.
    • If you select Range, then in the Attachment Size From Value field, enter the attachment size in KB from which you want to filter emails, and in the Attachment Size To Value field, enter the attachment size in KB till which you want to filter emails.
    • If you select More Than, then in the Attachment Size From Value field, enter the attachment size in KB more than which you want to filter emails.
    • If you select Less Than, then in the Attachment Size From Value field, enter the attachment size in KB lesser than which you want to filter emails.
Sorting (Optional) Value and/or direction to sort the results retrieved by this operation. You can specify the following options: Order By or Order Direction. You can also specify both Order By and Order Direction.
If you select Order Direction, then you must specify the following parameter:
  • Order Direction: Sort results retrieved by this operation in this direction. You can choose one of the following: Ascending or Descending.
If you select Order By, then you must specify the following parameter:
  • Order By: Sort results retrieved by this operation using the value specified You can choose one of the following: Sender, Subject, Received, Scheduled Exit, or Size.
Envelope Recipient (Optional) Value of the Envelope Recipient based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, or Does Not Contain.
If you select Matches Exactly, then you must specify the following parameter:
  • Envelope Recipient Matches Exactly: Specify an envelope recipient value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Recipient Ends With: Specify an envelope recipient value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Recipient Contains: Specify an envelope recipient value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Recipient Does Not Contain: Specify an envelope recipient value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Recipient Begins With: Specify an envelope recipient value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Envelope Recipient Does Not End With: Specify an envelope recipient value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Envelope Recipient Does Not Start With: Specify an envelope recipient value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope recipient "Starts With" value Does Not match with the "Starts With" value that you have specified.
Envelope Sender (Optional) Value of the Envelope Sender based on which you want to retrieve emails from Cisco SMA. You can choose from the following options: Contains, Matches Exactly, Begins With, Ends With, or Does Not Contain.
If you select Matches Exactly, then you must specify the following parameter:
  • Envelope Sender Matches Exactly: Specify an envelope sender value that you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender value matches the value that you have specified.
If you select Ends With, then you must specify the following parameter:
  • Envelope Sender Ends With: Specify an envelope sender value whose "Ends With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Ends With" value matches the "Ends With" value that you have specified.
If you select Contains, then you must specify the following parameter:
  • Envelope Sender Contains: Specify an envelope sender value whose value "contains" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender contains the value that you have specified.
If you select Does Not Contain, then you must specify the following parameter:
  • Envelope Sender Does Not Contain: Specify an envelope sender value whose value "does not contain" the value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender does not contain the value that you have specified.
If you select Begins With, then you must specify the following parameter:
  • Envelope Sender Begins With: Specify an envelope sender value whose "Begins With" value you want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Begins With" value matches the "Begins With" value that you have specified.
If you select Does Not End With, then you must specify the following parameter:
  • Envelope Sender Does Not End With: Specify an envelope sender value whose "Ends With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Ends With" value Does Not match with the "Ends With" value that you have specified.
If you select Does Not Start With, then you must specify the following parameter:
  • Envelope Sender Does Not Start With: Specify an envelope sender value whose "Starts With" value you do not want to match with the emails in Cisco SMA, i.e., this operation will retrieve only those emails whose envelope sender "Starts With" value Does Not match with the "Starts With" value that you have specified.

Output

The output contains the following populated JSON schema:
{
"meta": {
"totalCount": ""
},
"data": [
{
"mid": "",
"attributes": {
"received": "",
"originatingEsaIp": "",
"esaHostName": "",
"esaMid": "",
"scheduledExit": "",
"sender": "",
"recipient": [],
"subject": "",
"quarantineForReasonDict": [
{
"quarantineName": "",
"reason": []
}
],
"quarantineForReason": [],
"inQuarantines": "",
"size": ""
}
}
]
}

operation: Release Emails From Quarantine

Input parameters

Parameter Description
Message IDs List of Message IDs that you want to release from quarantine in Cisco SMA. You can enter multiple message IDs in the CSV or List format. For example, 150,151,152 or [150,151,152]
Quarantine Type Type of the quarantine from which you want to release the emails. For example, pvo.
Quarantine Name Name of the quarantine from which you want to release the emails. For example, spam.

Output

The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}

operation: Delete Message

Input parameters

Parameter Description
Message IDs List of Message IDs that you want to delete from Cisco SMA. You can enter multiple message IDs in the CSV or List format. For example, 150,151,152 or [150,151,152]
Quarantine Type Type of the quarantine from which you want to delete the emails. For example, pvo.
Quarantine Name Name of the quarantine from which you want to release the emails. For example, spam.

Output

The output contains the following populated JSON schema:
{
"data": {
"action": "",
"totalCount": ""
}
}

Included playbooks

The Sample - Cisco SMA - 1.0.1 playbook collection comes bundled with the Cisco SMA connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in CyOPsTM after importing the Cisco SMA 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.

Previous
Next