Reporting API

The Reporting API empowers customers to create their reports and dashboards, enabling better management of their clients. This enhanced capability increases sellers' ability to attract customers and provides customers with more information on the usage of the ETD. The API allows search for a period of 90 days.

Currently Secure Email Threat Defence has five reporting APIs -

1. Total messages scanned aggregated by directions
2. Total traffic by verdicts
3. Total messages by retropective verdicts
4. Top 10 Targets by threat along with conviction count
5. Top 10 Senders by threat

Total message scanned aggregated by directions, total traffic by verdicts, and total messages by retroVerdicts

Total message scanned aggregated by directions, Total traffic by verdicts, and Total messages by retroVerdicts reporting APIs allow you to generate reports on the total number of messages scanned by the ETD, aggregated based on direction, verdicts, and retrospective verdicts.

Available API endpoints are:

Americas API endpoint:

https://api.us.etd.cisco.com/v1/messages/report 

Europe API endpoint:

https://api.de.etd.cisco.com/v1/messages/report

Australia API endpoint:

https://api.au.etd.cisco.com/v1/messages/report

India API endpoint:

https://api.in.etd.cisco.com/v1/messages/report

UAE API endpoint:

https://api.ae.etd.cisco.com/v1/messages/report

Sample request using CURL:

  curl --location 'https://api.de.etd.cisco.com/v1/messages/report' \
--header 'x-api-key: apikeyTest’ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOtMzQ2OGZhNjYwNWVmIn0.GuVau-3aTtYAZeQL0iJOBRif_Ir7DKuE4BKuK-DsCyA' \
--data '    {
    "aggregationInterval": "1d",
    "timestamp": [
        "2023-11-19T12:00:00Z",
        "2023-11-20T23:59:59Z"
    ],
    "aggregateBy": "directions"
    }'  

Note:

1. aggregateBy supports direction, verdicts, and retroVerdicts depending on the user's choice of the report.
2. aggregationInterval supports 1hr, 1d, or 30d.
3. For the intervals longer than seven days, aggreagtionInterval can be 1d or 30d.
4. The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response of total message scanned by direction:

{
    "data": {
        "aggregationInterval": "1h",
        "totalMessages": 3,
        "aggregations": [
            {
                "startTimestamp": "2023-11-19T12:00:00.000Z",
                "messageCount": 2,
                "messages": {
                    "incoming": 0,
                    "outgoing": 0,
                    "internal": 2
                }
            },
            {
                "startTimestamp": "2023-11-19T13:00:00.000Z",
                "messageCount": 1,
                "messages": {
                    "incoming": 1,
                    "outgoing": 0,
                    "internal": 0
                }
            }
        ]
    }
}

Sample Response of total traffic by verdicts:

{

    "data": {
        "aggregationInterval": "1d",
        "totalMessages": 45,
        "aggregations": [
            {
                "startTimestamp": "2023-11-19T00:00:00.000Z",
                "messageCount": 42,
                "messages": {
                    "malicious": 28,
                    "spam": 6,
                    "phishing": 6,
                    "graymail": 0,
                    "bec": 0,
                    "scam": 2
                }
            },
            {
                "startTimestamp": "2023-11-20T00:00:00.000Z",
                "messageCount": 3,
                "messages": {
                    "malicious": 0,
                    "spam": 3,
                    "phishing": 0,
                    "graymail": 0,
                    "bec": 0,
                    "scam": 0
                }
            }
        ]
    }
}

Sample Response of total messages by retrospective verdicts:

{

    "data": {
        "aggregationInterval": "1d",
        "totalMessages": 45,
        "aggregations": [
            {
                "startTimestamp": "2024-01-19T00:00:00.000Z",
                "messageCount": 42,
            },
            {
                "startTimestamp": "2024-01-20T00:00:00.000Z",
                "messageCount": 3,  
            }
        ]
    }
}

Top 10 Targets by threat along with conviction count

This reporting API enables you to identify the top 10 target addresses that received the most threat messages and their respective conviction counts over the past 90 days.

Available API endpoints are:

Americas API endpoint:

https://api.us.etd.cisco.com/v1/messages/report/top 

Europe API endpoint:

https://api.de.etd.cisco.com/v1/messages/report/top

Australia API endpoint:

https://api.au.etd.cisco.com/v1/messages/report/top

India API endpoint:

https://api.in.etd.cisco.com/v1/messages/report/top

UAE API endpoint:

https://api.ae.etd.cisco.com/v1/messages/report/top

Sample request using CURL:

  curl --location 'https://api.de.etd.cisco.com/v1/messages/report/top' \
--header 'x-api-key: apikeyTest’ \  
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOtMzQ2OGZhNjYwNWVmIn0.GuVau-3aTtYAZeQL0iJOBRif_Ir7DKuE4BKuK-DsCyA' \
--data '    {
    "timestamp": [
        "2023-11-19T12:00:00Z",
        "2023-11-20T23:59:59Z"
    ],
    "reportType": "targets"
    }'  

Note: The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response:

{
    "data": {
        "topTargets": [
            {
                "emailAddress": "sacjha@raptoretdautoe2e.onmicrosoft.com",
                "malicious": 258,
                "phishing": 127,
                "bec": 42,
                "scam": 129
            },
            {
                "emailAddress": "aanderson@raptoretdautoe2e.onmicrosoft.com",
                "malicious": 50,
                "phishing": 32,
                "bec": 0,
                "scam": 0
            }
        ]
    }
}

Top 10 Senders by threat

This reporting API enables you to identify the top 10 external sender addresses that sent the most threat messages over the past 90 days.

Available API endpoints are:

Americas API endpoint:

https://api.us.etd.cisco.com/v1/messages/report/top 

Europe API endpoint:

https://api.de.etd.cisco.com/v1/messages/report/top

Australia API endpoint:

https://api.au.etd.cisco.com/v1/messages/report/top

India API endpoint:

https://api.in.etd.cisco.com/v1/messages/report/top

UAE API endpoint:

https://api.ae.etd.cisco.com/v1/messages/report/top

Sample request using CURL:

  curl --location 'https://api.de.etd.cisco.com/v1/messages/report/top' \
--header 'x-api-key: apikeyTest’ \  
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Bearer Token>' \
--data '    {
    "timestamp": [
        "2024-01-19T12:00:00Z",
        "2023-01-20T23:59:59Z"
    ],
    "reportType": "threatSenders"
    }'  

Note: The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response:

{
    "data": {
        "topExternalThreatSenders": [
            {
                "emailAddress": "sacjha@raptoretdautoe2e.onmicrosoft.com",
                "total": 30
            },
            {
                "emailAddress": "aanderson@raptoretdautoe2e.onmicrosoft.com",
                "total": 50
            }
        ]
    }
}