AsyncOS REST API 2.0

Cisco Secure Email Gateway & Cloud Gateway

About

Cisco Secure Email supports Application Programming Interface (API) as of the following releases:

  • AsyncOS 13.x for Cisco Email Security Appliance (ESA) and newer
  • AsyncOS 12.x for Cisco Content Security Management Appliance (SMA) and newer

Programming Guides:

The AsyncOS API for Cisco Email Security appliances (or AsyncOS API) is a representational state transfer (REST) based set of operations that provide secure and authenticated access to the Email Security appliance reports, report counters, and tracking. You can retrieve the Email Security appliance reporting and tracking data using the API.

📘

API Supportability Note

For the releases listed above, you can query for configuration information.
Posting configuration changes is not supported in these releases.

For more information, refer to the Swagger API help. To view the API help, access the new web interface of the appliance, click the help icon on the top right corner of the page and select API Help: Swagger.

These guides are focused on using the API with Cisco Secure Email. With some slight changes to URLs and hostnames, it would work with on-premise deployed SMAs too! It also assumes Cisco Secure Email Cloud Gateway accounts are created, administrators have access, and some working knowledge working with the platform.

This guide will give you a general introduction to using API on the SMA.

Prerequisites for Using AsyncOS API

To use AsyncOS API, you need:

  • A Security Management appliance with AsyncOS 12.0.
  • Knowledge of:
    • HTTP, the protocol used for API transactions. Secure communication over TLS.
    • JavaScript Object Notation (JSON), which the API uses to construct resource representations.
    • JSON Web Token (JWT)
  • A client or programming library that initiates requests and receives responses from the AsyncOS API using HTTP or HTTPS, for example, cURL. The client or programming library must support JSON to interpret the response from the API.
  • Authorization to access the AsyncOS API. See Authorization.
  • AsyncOS API enabled using the ​web interface or CLI. See Enabling AsyncOS API.

Setup

API Access for SMA

  1. Locate the URL for admin access. It should look like: https://dhxxxx-sma1.iphmx.com/
    (Where xxxx = your unique customer account number.)

📘

Note

Please assure the version number upon entry and ensure its 12.x or above. If not, please contact your account team.

UI log-in for SMAUI log-in for SMA

UI log-in for SMA

  1. Once logged in, ensure the API is enabled. Navigate to Management Appliance > Network > IP Interfaces. Click on the interface listed, typically this is the Management interface. View the AsyncOS API section:

📘

Note

This step for CES administrators will require validation from a Cisco account team member or Cisco TAC. CES customers only have a ​Cloud Administrator account, which does not permit administrative access to view Network configuration.

API configuration on the SMA's IP InterfaceAPI configuration on the SMA's IP Interface

API configuration on the SMA's IP Interface

  1. Enable the API ports if they are not already enabled. The associate ports for HTTP/HTTPS traffic will need to be allowed on local network and firewall, if not already configured.

Configure Your Preferred API Development Environment

You may download/utilize your own API environment or 3rd party software. For the purpose of this guide, we will reference using Postman.

  1. Open Postman and create a new GET request:
  1. Save your request using a name/description and file location:
  1. In your newly opened request window, click the Auth (Authorization) tab
  2. Select TYPE=Basic Auth
  3. Enter your CES account username and password
  4. Click Save:
  1. Input a simple API query in the requestor to test connectivity and click Send:
    https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/

If successful, you should be presented the following output:

{
    "error": {
        "message": "Not Found.",
        "code": "404",
        "explanation": "404 = Nothing matches the given URI."
    }
} 

If not, an unsuccessful query would return the following output:

{
    "error": {
        "message": "Unauthorized.",
        "code": "401",
        "explanation": "401 = No permission -- see authorization schemes."
    }
} 
  1. A second simple API query that should return results:
    https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/config/system_time?device_type=sma
{
    "data": {
        "timezone": "America/Los_Angeles",
        "continent": [
            "America",
            "United States",
            "Los_Angeles"
        ],
        "time": "Mon May 13 07:02:36 2019 PDT"
    }
}

For complete details on Requests and Responses: AsyncOS API Requests and Responses

Using the API

Let's build out an API string. First, you will need the default API URL:
https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/

Second, we'll need a "resource" to focus on.

Resources are the following:

  • Calls related to reporting:
    https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/reporting/
  • Calls related to message tracking:
    https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/message-tracking/
  • Calls related to quarantines:
    https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/quarantine/

Within each of the "resource", there is a multitude of counter groups that you can retrieve:
Reporting
Tracking
Quarantines

Finally, you may need other notable variables:

  • Device type: device_type=esa
  • Device name: device_name=esa1.hcxxx-xx.iphmx.com
    (there are # of esa devices powering the CES account: esa1, esa2, esa3, etc)
  • Group name: device_group_name=Hosted_Cluster
  • Date/Time format: startDate=YYYY-MM-DDT00:00:00.000Z&endDate=YYYY-MM-DDT00:00:00.000Z

Scenario #1: Incoming Mail Summary

Counter query adding totals across all ESAs grouped in Hosted_Cluster – Incoming Mail Summary Stats by category

Query:

https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/reporting/mail_incoming_traffic_summary?startDate=2019-05-01T19:00:00.000Z&endDate=2019-05-12T23:00:00.000Z&device_type=esa&device_group_name=Hosted_Cluster
Sample Output (truncated screenshot, using the "Pretty" output option in Postman)Sample Output (truncated screenshot, using the "Pretty" output option in Postman)

Sample Output (truncated screenshot, using the "Pretty" output option in Postman)

Scenario #2: AMP

Counter query adding totals AMP hits for all ESAs in Hosted_Cluster

Query:

https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/reporting/mail_incoming_traffic_summary/detected_amp?startDate=2019-05-01T19:00:00.000Z&endDate=2019-05-12T23:00:00.000Z&device_type=esa&device_group_name=Hosted_Cluster
Sample Output (truncated screenshot, using the "Raw" output option in Postman)Sample Output (truncated screenshot, using the "Raw" output option in Postman)

Sample Output (truncated screenshot, using the "Raw" output option in Postman)

Scenario #3: Output query from Message Tracking

Query:

https://dhxxxx-sma1.iphmx.com/sma/api/v2.0/message-tracking/messages?startDate=2019-04-01T01:00:00.000Z&endDate=2019-05-02T09:36:00.000Z&ciscoHost=All_Hosts&searchOption=messages&offset=0&limit=20
Sample Output (truncated screenshot, using the "Pretty" output option in Postman)Sample Output (truncated screenshot, using the "Pretty" output option in Postman)

Sample Output (truncated screenshot, using the "Pretty" output option in Postman)

Troubleshooting

📘

Note

For CLI access, please see: CLI access > connect2ces.sh

Create and view an API log from the CLI:

sma1.hcxxx-yy.iphmx.com> logconfig

Choose the operation you want to perform:
- NEW - Create a new log.
- EDIT - Modify a log subscription.
- DELETE - Remove a log subscription.
- SETUP - General settings.
- LOGHEADERS - Configure headers to log.
- HOSTKEYCONFIG - Configure SSH host keys.
[]> new

Choose the log file type for this subscription:
1. Cisco Text Mail Logs
2. qmail Format Mail Logs
3. Delivery Logs
4. Bounce Logs
5. Status Logs
6. Smartlicense Logs
7. Domain Debug Logs
8. Injection Debug Logs
9. SMTP Conversation Logs
10. System Logs
11. CLI Audit Logs
12. FTP Server Logs
13. HTTP Logs
14. NTP logs
15. LDAP Debug Logs
16. Scanning Logs
17. Spam Quarantine Logs
18. Spam Quarantine GUI Logs
19. Reporting Logs
20. Reporting Query Logs
21. Updater Logs
22. SNMP Logs
23. Tracking Logs
24. SMA Logs
25. Safe/Block Lists Logs
26. Authentication Logs
27. Upgrade Logs
28. Haystack Logs
29. Backup Logs
30. API Logs
31. CTR Logs
[1]> 30

Please enter the name for the log:
[]> mysma_api

Log level:
1. Critical
2. Warning
3. Information
4. Debug
5. Trace
[3]>

Choose the method to retrieve the logs.
1. FTP Poll
2. FTP Push
3. SCP Push
[1]>

Filename to use for log files:
[api]>

Would you like to append system based unique identifiers like $hostname, $serialnumber to the log filename? [N]>

Do you want to configure time-based log files rollover? [N]>

Please enter the maximum file size. You can specify suffixes: "m" for megabytes, "k" for kilobytes. Suffixes are case-insensitive:
[10485760]>

Please enter the maximum number of files:
[10]> 

Once you have committed the changes post-log creation, you can then run tail to monitor the log:

sma1.hcxxxx-yy.iphmx.com> tail mysma_api

Press Ctrl-C to stop.
Mon May 13 07:25:10 2019 Info: Begin Logfile
Mon May 13 07:25:10 2019 Info: Version: 12.0.0-478 SN: 420D4B6FA42Exxxxyyyy-CE7Dxxxxyyyy
Mon May 13 07:25:10 2019 Info: Time offset from UTC: -25200 seconds
Mon May 13 07:25:22 2019 Info: 68.123.123.123 - - 13/May/2019 07:25:22 -0700 GET /sma/api/v2.0/config/system_time?device_type=sma HTTP/1.0 200 -
Mon May 13 07:25:36 2019 Info: User joe_user not authorized
Mon May 13 07:25:36 2019 Info: 68.123.123.123 - - 13/May/2019 07:25:36 -0700 GET /sma/api/v2.0/config/appliances?device_type=sma HTTP/1.0 401 -
Mon May 13 07:25:47 2019 Info: 68.123.123.123 - - 13/May/2019 07:25:47 -0700 GET /sma/api/v2.0/config/centralized_services?device_type=sma HTTP/1.0 200 -

The following are some of the events that are logged in the API logs:

  • API has started or stopped
  • Connection to the API failed or closed (after providing response)
  • Authentication succeeded or failed
  • Request contains errors
  • Error while communicating network configuration changes with AsyncOS API

Additional References


Did this page help you?